Valid Asciidoc to convert to Manpage (with a2x)

Question

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?

Answer 1

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!)

Answer 2

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.