Valid Asciidoc to convert to Manpage (with a2x) - manpage

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

Custom/Distributed documentation of changes with Doxygen

I am attempting to get the following feature working with Doxygen.
Is this possible, and how best to do this?
We are working with an existing Tcl codebase that came with an EDA tool, a lot of which is code that gets 'sourced' and is not necessarily organized in procedures. There are numerous improvements/modifications that we have applied to this code base. An example customization would be of the form "allow feature X to be controlled with new configuration variable Y", and involves modifications made to fileA, fileB, and fileC.
I have Doxygen parsing the entire code base. Besides standard language documentation I am looking to extract a list of all customizations we have made, including which files were modified (and approx line number), what changes were made in each file, capture of the modified code from each files, and pointer to the file listing and line number where the modification was made.
I expect this to require custom Doxygen comments/tags in fileA, fileB, and fileC, and the closest I managed to get is by placing the following at each location where something is modified in fileA fileB and fileC:
##
# \page custom_mypage1 Customization enabling control of X with variable Y
#
# This is a test comment 1
#
This allows for collecting the comments from the three locations, but I can't figure out how to:
include portion of the source code that follows, and
how to have the generated documentation include references to file/line number of where the comment came from
Using xrefitem instead of page would provide the link between the summary page and source.
To include a code snippet in the page, snippet may help.
Example:
/**
\xrefitem customization1 "Change for 1" "Changes for customization1"
Description of change.
\snippet CurrentSourceFile.cpp change1
*/
//! [change1]
Modified code here...
//! [change1]

How to render LaTeX/PDF with a forced line break on a definition list in reStructuredText

I want to render a pdf file in reStructuredText with a proper line break, such that:
Keyword
Definition
This renders correctly with a Read the Docs template, but it doesn't produce the line break when using default settings and make latexpdf. Is there a simple function I can apply to the LaTeX output options in conf.py for this issue?
Note: I already submitted this question on TeX and was told to try Stack Overflow. The snippet above should be the shortest code required to reproduce my use case. As I said, these are the default settings as far as I know. I haven't made any significant changes. The lack of line break over definition lists seems to be the intended output for LaTeX pdf files.
Using the rinohtype PDF builder for Sphinx allows for fine control of style aspects such as these. The default style sheet actually inserts line breaks between a keyword and its definition in definition lists. Otherwise the style of the produced PDF is very similar to the output of the LaTeX builder. You can create your own style sheet and template configuration to customize the look of the PDF to your needs.
(Full disclosure: I am the author of rinohtype)
Here's a partial answer, to the limit of my knowledge. I hope it gets you further along.
By default the conversion applies a bold style to the term, and the definition of the term is inline with the term and line wraps with an indent on subsequent lines. See screenshot below for example output from the PDF for Pyramid documentation.
When you do make latexpdf you invoke two processors in succession, converting reST files to a LaTeX file, then running those files through pdflatex to generate the PDF.
Here's what appears for the first glossary entry in pyramid.tex for the first step:
\item[{ACE\index{ACE|textbf}}] \leavevmode\phantomsection\label{\detokenize{glossary:term-ace}}
An \sphinxstyleemphasis{access control entry}. An access control entry is one element
in an {\hyperref[\detokenize{glossary:term-acl}]{\sphinxtermref{ACL}}}. An access control entry is a three-tuple that
describes three things: an \sphinxstyleemphasis{action} (one of either \sphinxcode{Allow} or
\sphinxcode{Deny}), a {\hyperref[\detokenize{glossary:term-principal}]{\sphinxtermref{principal}}} (a string describing a user or
group), and a {\hyperref[\detokenize{glossary:term-permission}]{\sphinxtermref{permission}}}. For example the ACE, \sphinxcode{(Allow,
'bob', 'read')} is a member of an ACL that indicates that the
principal \sphinxcode{bob} is allowed the permission \sphinxcode{read} against the
resource the ACL is attached to.
The question now boils down to how to change that output so that it can be styled as you desire. And for that, you'll need to parse through the Sphinx documentation on LaTeX customization. How to do that is beyond my knowledge.
You can achieve that with a substitution to inject raw LaTeX code.
Keyword
|br| Definition
Keyword2
|br| Long definition long definition long definition long definition long
definition long definition long definition long definition long definition
long definition long definition long definition long definition long
definition long definition long definition long definition long definition
long definition long definition long definition long definition long
definition long definition long definition
.. |br| raw:: latex
\mbox{}\newline
This produces in PDF:
Note that the raw LaTeX code is not injected into other targets, only the latexpdf target.

Nested block macros in asciidoc

I am using asciidoc to generate course materials as PDF. When the materials are printed, I do not want the code samples to be highlighted, because they do not print well. When the materials are read with a PDF reader, I do want highlighting.
I have defined a variable highlight, and I can do the following, which works fine:
ifdef::highlight[]
[source, {language}]
endif::highlight[]
----
code
----
I have dozens of code examples in dozens of chapters, so I'd like to use a macro that can check the status of the highlight variable and conditionally include the source macro. Then I can generate the print-friendly version by default, but define the highlight version on the command line when I need the viewer-friendly version.
I have written such a macro (in my asciidoc config file):
[macros]
(?u)^(?P<name>hlsource)::(?P<target>\S*?)(\[(?P<attrlist>.*?)\])$=#
[hlsource-blockmacro]
ifdef::highlight[]
[source, {language}]
endif::highlight[]
The problem is that it literally includes the text "[source, python]" in my generated PDF file rather than being interpreted as an asciidoc directive.
Note: language is a variable set in the config file.
Can anyone confirm whether such nested macros are even possible in asciidoc, and if so, how to do it.
Thanks!

Doxygen: Outputting Version Numbers

I would like to have Doxygen display the source code version number as part of the main page or the title header.
Presently, our code has the version defined as a text literal:
/*!
* \brief Text literal containing the build number portion of the
* ESG Application Version.
*/
static const char build_version_text[] = "105";
I have searched the internet for a method to get the 105 from the above statement into the Doxygen main page (or header) with no luck.
Background
We have a build server that updates the text string as part of a nightly build operation. The file is updated, then checked into the Software Configuration Management system. The build server is also capable of generating the documentation. We would also like to have the developers be able to check out the code, the build the Doxygen documentation at their workstations.
We are using Doxygen version 1.8.11.
What you're looking for is to set the PROJECT_NUMBER config option based on the value in your source. I don't think this can be done, but the way I would go about achieving the same result is as follows.
Since the project version is updated when a build script runs, have the build script generate an extra file, for example Doxyversion. Have the content of the file be:
PROJECT_NUMBER = "<versiontext>"
Update your main Doxyfile and replace
PROJECT_NUMBER =
with
#INCLUDE = "<pathToDoxyversion>"
Edit:
A solution I can think of that does not require duplicating the version string requires parsing the version string out from the file into an environment variable. Then you can set PROJECT_NUMBER to
PROJECT_NUMBER=$(ENV_VAR)
Another option is you can call doxygen with
( cat Doxyfile ; echo "PROJECT_NUMBER=$ENV_VAR" ) | doxygen
Both solutions would require the developers to know to do this when generating the documentation, or wrapping the entire doxygen call in a script. Also potential portability issues.
Full solution below, from a real example.
Main page
In the documentation for the main page (or anywhere, really), use special markers for the text to substitute dynamically.
Main page source:
https://github.com/mysql/mysql-server/blob/8.0/sql/mysqld.cc#L22
See the special ${DOXYGEN_GENERATION_DATE} markers
Doxygen input filters
In the doxygen configuration file, define an input filter for the file containing the special markers. For example,
FILTER_PATTERNS = "*/sql/mysqld.cc=./doxygen-filter-mysqld"
Implement the doxygen-filter-mysqld script to:
Find the dynamic value to substitute (in your case, parse the value of build_version_text)
Replace (sed) the special marker with the value
Output the result to stdout
For example:
CMD1="s/\\\${DOXYGEN_GENERATION_DATE}/"`date -I`"/g"
...
sed -e ${CMD1} -e ${CMD2} -e ${CMD3} $1
Results
Result is at
http://devdocs.no.oracle.com/mysql-server/8.0.0/
See Also
All this is a work around for that I think should be a good Doxygen feature.
See bug#769679 (Feature Request: doxygen command to expand an environment variable) that was entered for this.
https://bugzilla.gnome.org/show_bug.cgi?id=769679

How to handle citations in Ipython Notebook?

What is the best way to take care of citations in Ipython Notebook? Ideally, I would like to have a bibtex file, and then, as in latex, have a list of shorthands in Ipython markdown cells, with the full references at the end of the notebook.
The relevant material I found is this: http://nbviewer.ipython.org/github/ipython/nbconvert-examples/blob/master/citations/Tutorial.ipynb
But I couldn't follow the documentation very well. Can anyone explain it? Thanks so much!!
You can use the Document Tools of the Calico suite, which can be installed separately with:
sudo ipython install-nbextension https://bitbucket.org/ipre/calico/downloads/calico-document-tools-1.0.zip
Read the tutorial and watch the YouTube video for more details.
Warning: only the cited references are processed. Therefore, if you fail to cite an article, it won't appear in the References section. As a little working example, copy the following in a Markdown cell and press the "book" icon.
<!--bibtex
#Article{PER-GRA:2007,
Author = {P\'erez, Fernando and Granger, Brian E.},
Title = {{IP}ython: a System for Interactive Scientific Computing},
Journal = {Computing in Science and Engineering},
Volume = {9},
Number = {3},
Pages = {21--29},
month = may,
year = 2007,
url = "http://ipython.org",
ISSN = "1521-9615",
doi = {10.1109/MCSE.2007.53},
publisher = {IEEE Computer Society},
}
#article{Papa2007,
author = {Papa, David A. and Markov, Igor L.},
journal = {Approximation algorithms and metaheuristics},
pages = {1--38},
title = {{Hypergraph partitioning and clustering}},
url = {http://www.podload.org/pubs/book/part\_survey.pdf},
year = {2007}
}
-->
Examples of citations: [CITE](#cite-PER-GRA:2007) or [CITE](#cite-Papa2007).
This should result in the following added Markdown cell:
References
^ PĂ©rez, Fernando and Granger, Brian E.. 2007. IPython: a System for Interactive Scientific Computing. URL
^ Papa, David A. and Markov, Igor L.. 2007. Hypergraph partitioning and clustering. URL
Summary
This solution is largely based on Sylvain Deville's excellent blog post. It allows you to simply write [#citation_key] in markdown cells. The references will be formatted after document conversion. The only requirements are LaTeX and pandoc, which are both widely supported. While there is never a guarantee, this approach should therefore still work in many years time.
Step-by-Step Guide
In addition to a working installation of jupyter you need:
LaTeX (installation guide).
Pandoc (installation guide).
A citation style language. Download a citation style, e.g., APA. Save the .csl file (e.g., apa.csl) into the same folder as your jupyter notebook (or specify the path to the .csl file later).
A .bib file with your references. I am using a sample bib file list.bib. Save to the same folder as your jupyter notebook (or specify the path to the .bib file later).
Once you completed these steps, the rest is easy:
Use mardown syntax for references in markdown cells in your jupyter notebook. E.g., [#Sh:1] where the syntax works like this: ([#citationkey_in_bib_file]). I much prefer this syntax over other solutions because it is so fast to type [#something].
At the end of your ipython notebook, create a code cell with the following syntax to automatically convert your document (note that this is R code, use an equivalent command to system() for python):
#automatic document conversion to markdown and then to word
#first convert the ipython notebook paper.ipynb to markdown
system("jupyter nbconvert --to markdown paper.ipynb")
#next convert markdown to ms word
conversion <- paste0("pandoc -s paper.md -t docx -o paper.docx",
" --filter pandoc-citeproc",
" --bibliography="listb.bib",
" --csl="apa.csl")
system(conversion)
Run this cell (or simply run all cells). Note that the 2nd system call is simply pandoc -s paper.md -t docx -o paper.docx --filter pandoc-citeproc --bibliography=listb.bib --csl=apa.csl. I merely used paste0() to be able to spread this over multiple lines and make it nicer to read.
The output is a word document. If you prefer another document, check out this guide for alternative syntax.
Extras
1) If you do not like that your converted document includes the syntax for the document conversion, insert a markdown cell above and below the code cell with the syntax for the conversion. In the cell above enter <!-- and in the cell below enter -->. This is a regular html command for a comment, so the syntax will in between these two cells will be evaluated but not printed.
2) You can also include a yaml header in your first cell. E.g.,
---
title: This is a great title.
author: Author Name
abstract: This is a great abstract
---
I was able to run it with the following approach:
Insert the html citation as in the tutorial you mentioned.
Create ipython.bib in the "standard" bibtex format. It goes into the same file as your *.ipynb notebook file.
Create the template file as in the tutorial, also in the same directory or else in the (distribution dependent) directory with the other templates. On my system, that's /usr/local/lib/python2.7/dist-packages/IPython/nbconvert/templates/latex.
The tutorial has the template extend latex_article.tplx. On my distribution, it's article.tplx (without latex_).
Run nbconvert with --to latex; that generates an .aux file among other things. Latex will complain about missing references.
Run bibtex yournotebook.aux; this generates yournotebook.bbl. You only need to re-run this if you change references.
Re-run nbconvert either with --to latex or with --to pdf. This generates a .tex file, or else runs all the way to a .pdf.
If you want html output, you can use pandoc to assemble the references into a tidy citation page. This may require some hand-editing to make an html page you can reference from your main document.
If you know that you will be converting your notebook to latex anyway, consider simply adding a "Raw" cell (Ctrl+M R) to the end of the document, containing the bibliography just as you would put it in pure LaTeX.
For example, when I need to reference a couple of external links, I would not even care to do a proper BibTeX thing and simply have a "Raw" cell at the end of the notebook like that:
\begin{thebibliography}{1}
\bibitem{post1}
Holography in Simple Terms. K.Tretyakov (blog post), 2015.\\
\url{http://fouryears.eu/2015/07/24/holography-in-simple-terms/}
\bibtem{book1}
The Importance of Citations. J. Smith. 2010.
\end{thebibliography}
The items can be cited in other Markdown cells using the usual <cite data-cite="post1">(KT, 2015)</cite>
Of course, you can also use proper BibTeX as well. Just add the corresponding Raw cell, e.g:
\bibliographystyle{unsrt}
\bibliography{papers}
This way you do not have to bother editing a separate template file (at the price of cluttering the notebook's HTML export with raw Latex, though).
You should have a look at the latex_envs extension in https://github.com/ipython-contrib/IPython-notebook-extensions (install from this repo, it is the most recent version). This extension contains a way to integrate bibliography using bibtex files and standard latex notation, and generates a bibliography section at the end of the notebook. Style of citations can be (to some extent) customized. Some documentation here https://rawgit.com/jfbercher/latex_envs/master/doc/latex_env_doc.html

Resources