I want to write the manpage for my CLI-script with Asciidoc and convert it with
a2x --doctype manpage --format manpage MYMANPAGE.ASCIIDOC
I could not find any Asciidoc example out there which can successfully be converted to a manpage with this command.
Could you point me to an example or provide one?
Found an example - from the Asciidoc sources itself:
http://code.google.com/p/asciidoc/source/browse/doc/asciidoc.1.txt
(Still, more examples for Ascii-doc-formatted manpages very welcome!)
In addition to the link from #ifischer's answer, which provides a very useful example, I would like to direct readers to the following page from the asciidoc documentation: http://www.methods.co.nz/asciidoc/chunked/ch24.html.
In particular, it mentions that:
the title needs to be properly formatted (e.g: PROGRAM(1))
the doctype needs to be "manpage" (e.g: ":doctype: manpage")
the first section needs to be "Name". The contents of this section must also be properly formatted (e.g: "program - ...")
the second section needs to be "Synopsis". It appears the contents of this section can be anything, although standard manpage practice would be to list all of the program invocation options.
The document must of course be a properly formatted asciidoc document.
There are optional pieces of information which can be set for the manpage via ":directives:" in the document header.
When you run a2x, it will automatically name the outputted manpage based on the contents of the name section and title. I believe it's always named "name.x", where name is from the name section and x is the number from the title.
Related
I am trying to use tableofcontents command from Doxygen Doc.
To me \tableofcontents['{'[option[:level]][,option[:level]]*'}'] seems very cryptic.
Could you give an example of how to pass options and levels?
From the doxygen documentation:
24.111 \tableofcontents['{'[option[:level]][,option[:level]]'}']
Creates a table of contents at the top of a page, listing all sections and subsections in the page. The option can
be HTML or LaTeX or XML or DocBook. When a level is specified this means the maximum nesting level that
is shown. The value of level should be in the range 1..5, values outside this range are considered to be 5. In
case no level is specified level is set to 5 (show all) In case no option. is specified \tableofcontents
acts as if just the option HTML and XML was specified. In case of multiple \tableofcontents commands
in a page the option(s)
See also the beginning of the chapter "Special Commands" where a small description is of some of the used symbols.
So e.g.:
\tableofcontents
\tableofcontents{HTML}
\tableofcontents{HTML:3}
\tableofcontents{HTML:2,LaTex:3}
I want to put keywords and comments in my source file.
the keywords documentation for gettext says: if keywordspec is of the form ‘id:argnum...,"xcomment"’, xgettext, when extracting a message from the specified argument strings, adds an extracted comment xcomment to the message.
I couldn't find any samples to help me with this.
This is my X-Pedit-KeywordsList header,
"X-Poedit-KeywordsList: __;_ex;\n"
And this is a sample line in my php source code:
_ex("unlock_level", "Available at level #.")
I expect the output to be:
# "Available at level #."
msgid "unlock_level"
How should I edit my keywordslist header (and/or the source)?
An example for the keyword spec (bourne shell syntax!) is:
xgettext --keyword='_ex:1,"my comment"' so.php
Unfortunately, this is not what you want. It produces this po entry:
#. my comment
#: so.php:3
msgid "unlock_level"
msgstr ""
The above command-line translates to "extract the first argument all all calls to _ex() as the msgid, and always add the comment 'my comment' to the PO entry". You can only specify which arguments are the singular, the plural, or the message context.
The X-POEdit-KeywordsList seems to be a custom header used by POEdit. It doesn't help you either.
You can kind of achieve the desired result by changing your sources to this:
<?
# TRANSLATORS: Available at level #.
_ex("unlock_level");
?>
Now invoke xgettext like this:
xgettext --add-comments=TRANSLATORS: --keyword=_ex so.php
You get this PO entry:
#. TRANSLATORS: Available at level #.
#: so.php:3
msgid "unlock_level"
msgstr ""
The option --add-comments=TRANSLATORS: has the effect that it adds comments that immediately precede a keyword iff that comment starts exactly with the string "TRANSLATORS:". You can exchange "TRANSLATORS:" with a string of your choice. You can also omit the argument to --add-comments and extract all comments that immediately precede keywords.
Not quite what you originally wanted but as close as you can get.
Poedit supports translator comments. I ended up adding localization keys to my source file like this:
// TRANSLATORS: "Available at level #."
__("unlock_level")
And this is what I get in my po file by pressing the update button in Poedit:
#. TRANSLATORS: "Available at level #."
msgid "unlock_level"
I just came across this post because I was also looking for a way to do this, and just wanted to add that #Paiman Roointans' solution works because PoEdit uses the TRANSLATORS: tag as default tag for comment extraction via gettext.
This can actually be seen if you open PoEdit -> Preferences -> Extractors, then click on the little "+" button at the bottom left of the window, which will show you the command PoEdit fires by default for an extraction of your translation strings from the source file, which is sth like:
xgettext -L PHP --add-comments=TRANSLATORS: --force-po -o %o %C %K %F
where %o %C %K %F are the respective placeholders, for example %o for the output filename, %K for the keyword list (you specify in POEdits keyword mask), etc.
To change the default comment identifier in PoEdit, simply go to Translation -> Properties -> Click on "Advanced Extraction Preferences" under de "Translation Properties" tab of the window which then pops up. Normally the first field there should tell you the current string being used as comment identifying tag. Change that for example to mysamplecommentkey, and write a translation like this in your PHP code, for example:
/* mysamplecommentkey: This is a test */
gettext( "Translate Me" );
And your "Translate Me" will have the This is a test comment attached to it when extracting from the source code.
And, just another point: You should rather use a POT instead of a PO template file for your gettext localizations in PoEdit. Set all of your keyword extractors and / or comment identifier string, then extract from your source code into your .pot file, everytime when you update your translations.
Then, in all of your PO files, you simply hit update from POT-File in PoEdit, and it will correctly update all of your translations, including all of the comments for translators, which will all be drawn from the POT file directly too (so you better write these translator comments in a language that all of your translators most likely understand).
It took me some time to figure all of this out, and I would have saved tons of hours if I knew all of this from upon the beginning, so I wanted to share this here. If used correctly, PoEdit (already the free version of it) can save you a lot of time!
To distinguish this question from Doxygen: Adding a custom link under the "Related Pages" section which has an accepted answer that is not a real answer to the question, I specifically add prewritten to the question.
What I want:
Write one document tex file (without preamble, since this file will be \input-ed into a full document)
Import the document into Doxygen's HTML output.
Using Doxygen to produce tex file will probably not work, since it does too much layout work [This holds for its HTML output too like empty table rows 2015]. If Doxygen takes some other input that can easily be transformed into LaTeX, that will do.
You can easily add an already existing Latex file to your doxygen documentation using \latexonly\input{yourfile}\endlatexonly.
I would assume you put it e.g. under a doxygen \page.
I'm trying to document a C API which is all contained in a single C Header file. When I run doxygen, on the file, it's giving me errors for currently undocumented C Macros, but when I add the necessary documentation for macros, although the undocumented errors are cleared, the macros plus documentation do not appear in the doxygen generated html output.
Only a fraction of the documented header file, the structures, actually appears in any doxygen output. I can't see anything in configuration settings or documentation that would assist in clarifying why doxygen does not place documented code from the header file into its generated output.
Does anybody know why this would be the case?
See items 2 and 3 of the FAQ: http://www.doxygen.org/manual/faq.html
In short you are likely missing a comment block with #file to document your header file.
I need to refer to Doxygen documentation pages. The file names however are not stable as they change after every generation. My idea is to create a symlink to each HTML file created by Doxygen , having a stable and human friendly name. Have anyone tried this?
Actually, it might be very easy just to parse the annotated.html file Doxygen produces. Any documented class shows up there as a line like:
`<tr><td class="indexkey"><a class="el" href="dd/de6/a00548.html">
ImportantClass</a></td>`
The hard problem for me is that I would like to have my file names (i.e. the symlinks) be visible on my server like:
http://www.package.com/com.package.my.ImportantClass.html
[Yes, the code is in java]. So the question actually reads: "how to connect a HTML page by Doxygen with the right java class name and its package name.
You seem to have SHORT_NAMES enabled, which will indeed produce volatile names. When you set SHORT_NAMES to NO in the configuration file (the default), you will get longer names, but these are stable over multiple runs (i.e. they are based on the name, and for functions also on (a hash of) the parameters.