← Index

x/doc/emit-man

roff (man page) emitter for the documentation generator.

Class DocMan

Extends DocEmit.

roff emitter: one man page per module, section 3x, plus .so alias stubs for every documented name.

Section 3x, not 3: Doxygen’s C reference already occupies section 3, and the two namespaces should not collide.

Alias names ride out as ." X-ALIAS comment lines for the sweep to harvest; roff ignores them.

(DocMan esc s)

Escape a string for roff.

Three rules: a backslash becomes \e, a hyphen becomes - (roff renders a bare - as a typographic hyphen, which is wrong for an identifier and breaks copy-paste), and a leading . or ‘ is protected with \& so roff does not read the line as a request.

Parameters:

• s : STRING — Text to escape

Returns: STRING — Text safe to emit in a man page

(DocMan page-name mod)

Flatten a module path into its man page name.

Parameters:

• mod : STRING — Module name, e.g. x/type/base

Returns: STRING — The page name, e.g. x-type-base

Examples:

(DocMan page-name "x/type/base") => "x-type-base"

(DocMan page-header mod desc notes depth declared?)

Emit the .TH header, the NAME section man’s apropos database reads, and DESCRIPTION.

Unlike Markdown, roff gets a header even for an undeclared file: without .TH the file is not a man page, and man renders it with no header at all. The title then comes from the source path.

Parameters:

• mod : STRING — Module name, e.g. x/type/base
• desc : STRING — Module description, or “”
• notes : LIST — Note strings
• depth : INT — Directory depth – unused; man pages have no relative links
• declared? : BOOL — Whether the file declared (provide …) – unused; a man page needs a .TH either way

(DocMan section title)

Emit a top-level section heading.

Parameters:

• title : STRING — Section title

(DocMan class-head cname parent)

Emit a class as its own section, naming the parent when it extends one.

Parameters:

• cname : STRING — Class name
• parent : STRING — Parent class name, or “”

(DocMan interface-line names)

Emit the class’s (interface …) contract.

Parameters:

• names : LIST — Operation name strings

(DocMan entry-head name)

Emit one entry as a subsection heading.

Parameters:

• name : STRING — Entry name or rendered signature

(DocMan alias name)

Record a lookup name as a roff comment for the sweep to harvest into a .so stub.

Emitted UNESCAPED: this is a file name for the sweep, not display text.

Parameters:

• name : STRING — Lookup name for the entry that follows

(DocMan text s)

Emit a description paragraph.

Parameters:

• s : STRING — Paragraph text

(DocMan note s)

Emit a note as an indented block, the roff answer to Markdown’s blockquote.

Parameters:

• s : STRING — Note text

(DocMan params ps)

Emit the parameter list as tagged paragraphs – the shape man readers expect for arguments.

Parameters:

• ps : LIST — List of (name type desc) string triples

(DocMan returns type desc)

Emit the return type and its description.

Parameters:

• type : STRING — Return type name
• desc : STRING — Return description, or “”

(DocMan examples exs)

Emit the worked examples as a no-fill block, so the transcript keeps its own line breaks and spacing.

Parameters:

• exs : LIST — List of (input output) string pairs

(DocMan see-also names)

Emit the cross-references.

Parameters:

• names : LIST — Referenced name strings