Generating Man Pages

Generating Man Pages

Apex can convert Markdown to roff (man page source) or to styled HTML that looks like a man page. You do not need Pandoc or go-md2man; the built apex binary generates man pages directly from your Markdown source.

Output formats

Use -t or --to to select the format:

Format	Description
man	Groff/troff roff source (.TH, .SH, .TP, etc.). Use this to produce .1, .5, .7 files for man(1).
man-html	Styled HTML that resembles a man page (single document with man-like sections and typography).

Examples:

# Generate roff (man page source) - write to a file
apex -t man man/apex.1.md > man/apex.1

# View with man (after installing or from build dir)
man ./man/apex.1
# or: groff -man -Tutf8 man/apex.1 | less

# Generate styled HTML man page
apex -t man-html man/apex.1.md > apex-man.html

Example source and rendered output: apex.1.md (Markdown source), apex.1.html (man-html with -s, view in browser).

Output is written to stdout; redirect to a file or pipe to man/groff as needed.

Source Markdown format

Man page source is typically written in Markdown with:

1. Pandoc-style metadata at the top (optional but useful for .TH):

   % TITLE(SECTION)
   % Author
   % Date

2. Top-level headings for sections: # NAME, # SYNOPSIS, # DESCRIPTION, # OPTIONS, etc. Apex turns # into .SH and ## into .SS.

3. Definition lists for options: put the option name on one line and the description on the next line starting with : or :::

   **-o** *FILE*, **--output** *FILE*
   : Write output to *FILE* instead of stdout.
   
   **--standalone**
   : Generate complete HTML document with doctype and body tags.

4. Inline formatting: use **bold** and *italic* for option names and arguments; they are converted to roff \f[B] and \f[I].

Code in backticks is emitted as roman in roff (for compatibility with all groff devices). Definition list blocks are converted to roff .TP (tagged paragraph) style so each option appears with its description.

Generating from the Apex repo

If you are building Apex from source:

Using the Makefile:

make build   # ensure apex is built
make man     # generate man/apex.1, man/apex-config.5, man/apex-plugins.7 from their .md sources

make man depends on build, so it will build the apex binary first if needed, then run apex -t man on each .md file and write the result to the corresponding man file (e.g. man/apex.1.md -> man/apex.1).

Using CMake directly:

When you run cmake --build build (or make in the build directory), the man_pages target is built by default. CMake runs apex -t man on each man Markdown source and writes the roff into the build directory. Those files are used at install time (cmake --install build) and installed under share/man/man1, etc.

You can also generate a single page by hand:

./build/apex -t man man/apex.1.md > man/apex.1

Viewing generated roff

• man(1): If the man file is installed (e.g. under /usr/local/share/man), run:

  man apex

• From file: To view a roff file without installing:

  man ./man/apex.1
  # or
  groff -man -Tutf8 man/apex.1 | less

Related

• Command Line Options - All -t/--to formats and other flags.
• Rendering Markdown in the Terminal - Terminal output formats.