With my team we create software we need to document. I have found doxygen which seems a nice program to do this. Although our programming language is not supported (RAPID).
Yesterday I have asked a question about this. Albert was kind enough to provide a clue in the right direction. A filter should be the right way to go in stead of an preprocessor.
But I did not provide the syntax of the RAPID code which can be found here :
http://futurecnc.code.arc.cmu.edu/wp/wp-content/uploads/2011/12/RAPID-Reference-Manual-Instructions.pdf
I found the help guide about creating filters from the doxygen website. Also i have found an example filter created by Bert Jordan for perl :
http://www.doxygen.nl/helpers.html
Some questions :
Is a filter the right way to go, or is a preprocessor needed ?
What is the filter exactly doing ?
Doxygen has an lexical scanner, what kind of format must be used for the filter to convert the rapid code to a supported language?
I hope, I have given a clear description now :)
edit : I'm searching for information about how to create the actual filter.
Does anybody know a good source for this ?
There are some examples on filters for other languages at the doxygen site under the helpers section.
I have used an doxygen filter (which is not listed there) for Bash for one of my projects. The filter is pretty simple and might be a good example. This filter is available at Anvils github.
In essence it is just a ~130 line sed script converting bash to quasi-C which doxygen can parse. You could write your own sed script for RAPID.
You should add it to your Doxyfile with:
# Tell doxygen to handle files with sh extension as C files
EXTENSION_MAPPING = sh=C
# Tell doxygen to run sh files through the below sed script
FILTER_PATTERNS = *.sh=MY_PATH/doxygen-bash.sed
There is also a python example via the helpers page here.
The main part to understand is that the filter can be anything you like to write. Python, sed, shell, etc. Doxygen just calls your filter, runs the code through it and your filter should output a language Doxygen can parse.
Related
I'm currently trying to customize the standard writer built into Pandoc to produce output in the ConTeXt format from Markdown input. Unfortunately, the documentation to create a custom writer found at the Pandoc website is not giving me too much information apart from how to write a custom HTML writer. So, I would like to ask for help with some fundamental ideas:
What would be the preferrable way to add some (probably) very simple functionality to the ConTeXt writer, e.g.: I would like to rewrite the sequence of characters " - " (in a Markdown document) as another sequence "~-- " (in the resulting ConTeXt document).
If I understood correctly, I'm supposed to base my custom writer on the standard (built-in) writers... But where can I find these? There doesn't seem to be anything in /usr/share/pandoc/(I'm working on Linux).
The website mentions the "classic style" and the "new style". Apart from one obviously being newer, what style am I supposed to use?
I know that these questions may sound rather simple, but there doesn't seem to be a lot of information available beyond the usual basic stuff. Any help would be much appreciated.
Pandoc has another feature that is similar to custom writers, called "Lua filters". Filters are quite likely a simpler and better choice in this case: They allow to modify the internal document representation. E.g.:
function Inlines (inlines)
for i=#inlines, 3, -1 do -- iterate backwards through the list of inlines
if inlines[i-2].t == 'Space' and inline[i-1] == pandoc.Str '-' and
inlines[i].t == 'Space' then
-- Replace elements with raw ConTeXt
inlines[i-2] = pandoc.RawInline('context', '~--')
inlines:remove(i)
inlines:remove(i-1)
end
end
return inlines
end
The above would be used b writing it to a file, and then passing that file to pandoc via --lua-filters FILENAME.lua
The documentation for Lua filters is also less sparse and hopefully more approachable than the docs for custom writers.
I write documentation for a project using Sphinx. I have code examples (defined as code-blocks, both literally included and just typed inline). In these code examples there are comments, but when I produce documentation translation, they are not extracted into .po files, and obviously are not translated.
How can I translate comments in code examples?
I found other questions about Sphinx modifications. The answers proposed modifying conf.py (making some hooks), creating roles or extensions. I never did that before and I don't know where to start and what solution would be better. Is there any existing solution for this problem?
UPD. These are examples of code I want to show in my documentation:
git clone https://github.com/ynikitenko/lena
# most of requirements are for development only
pip install -r lena/requirements.txt
(here I'd like to translate the comment). A more difficult (maybe not so needed) example is this:
class End(object):
"""Stop sequence here."""
def run(self, flow):
"""Exhaust all preceding flow and stop iteration
(yield nothing to the following flow).
"""
for val in flow:
pass
return
# otherwise it won't be a generator
yield "unreachable"
These examples are formatted with the directive
.. code-block::
I wrote to the official sphinx-users google group, and this is the answer from Matt from Documatt:
It's impossible. Sphinx will have to understand comments in every language.
If you want to translate comments in code-block (and literal blocks after ::), you must translate them all. Add gettext_additional_targets = ["literal-block"] to your conf.py and re-run POT/PO update.
The code lines remain in the "translations" of code, but now the problem is solved for me.
Hello there,
just a "quick" question - I already installed the mediawiki properly - same with the extension itself, all working properly.
The thing is that Mediawiki extension page (https://www.mediawiki.org/wiki/Extension:AbuseFilter) won't tell me much about HOW to write a code for a filter, and google searches didn't return any valuable data like code block examples.
I'd be overjoyed if somebody could provide me a working code for the filter, even as simple as one for replacing typical f-bomb for the word "flowers", or whatever, since strReplace does nothing on it's own and I have no idea how to handle things.
Thanks in advance for any suggestions. :)
The official manual is here. For real-life examples, just go to Special:AbuseFilter on a wiki that's using it and see the code of public filters. For example, on English Wikipedia.
I am working on a project using a bash shell script. The idea is to grep a wget retrieved page, in order to pick up a certain paragraph on the web page. The area I would like to copy, usually starts with a
<p><b>
but the paragraph also contains other bits of HTML code, such as anchor tags, that I don't want to be in the output of the grep.
I have tried
cat page.html| grep "<p><b>" >grep.txt
and then I grep the output file, which now contains the paragraph I want
cat grep.txt|grep -v '<p>|<b>|<a>' >grep.txt
but then all it does is clear everything from the file and not read anything. How can I get it to exclude only the HTML code?
I am also trying to follow the links that are in the paragraph that I grep, in order to do the same thing with those pages. Only 2 levels deep, so the main page and then what ever sub page(s) stem from the first paragraph of the main page. I know this is a difficult idea, hopefully I explained well enough to get some help. If you have any ideas, any help is appreciated.
Do you have to do this in bash? It seems to me that Python would lend itself to this problem, in particular a library called Beautiful Soup.
I've used this for parsing HTML in the past and it's the easiest tool I could find. It has good documentation for dealing with html.
Perhaps you could make a standalone python code that extracts the HTML and then echos the string you're after. The python code could then be called from inside your bash script if you have some bash functions you want to perform on the string.
I know this is 7 years old but just posting solution I have with bash
https://api.jquery.com/jquery.grep/
I have complex log files, which are full of noise.
Can someone recommand a simple utility program which I can use to define lines which I want to filter out, or highlight using wildcards or any other method?
As well, a utility that can find logs which fulfill a certain condition (e.g., contains a line of a certain template) among a directory full of logs?
Regards
Have a look at LogParser from Microsoft. It has a SQL-like query language to allow you to filter log files based on conditions. Jeff Atwood has a brief overview of it here.
There's always good old "grep".
I have used Bear tail with great success. They have a free as well as a paid version.
If you have a bit of time to play with PERL and regular expressions, this is the kind of thing they do beautifully.