haredoc - reads and formats Hare documentation
haredoc [-at] [-F format] [identifiers...]
haredoc reads documentation for a set of identifiers from Hare source code, and optionally prepares it for viewing in various output formats. By default, haredoc will format documentation for your terminal.
See DOCUMENTATION FORMAT for details on the format.
-a
Show undocumented members (only applies to -Fhare and -Ftty).
-F format
Select output format (one of "html", "gemtext", "hare", or "tty").
-t
Disable HTML template.
-T tags
Adds additional build tags. See CUSTOMIZING BUILD TAGS in hare(1).
-X tags
Unsets build tags. See CUSTOMIZING BUILD TAGS in hare(1).
The Hare formatting markup is a very simple markup language. Text may be written normally, broken into several lines to conform to the column limit. Repeated whitespace will be collapsed. To begin a new paragraph, insert an empty line.
Links to Hare symbols may be written in brackets, like this: [[os::stdout]]. A bulleted list can be started by opening a line with "-". To complete the list, insert an empty line. Code samples may be used by using more than one space character at the start of a line (a tab character counts as 8 indents).
This markup language is extracted from Hare comments preceding exported symbols in your source code, and from a file named "README" in your module directory, if present.
// Foos the
bars. See also [[foobar]].
export fn example() int;
The TTY output format renders colors in the terminal with ANSI SGR escape sequences, behaving similarly to this shell command:
printf ’\033[0;%sm’ ’seq’
These sequences can be customised with the HAREDOC_COLORS environment variable, which follows this whitespace-delimited format:
HAREDOC_COLORS=’key=seq key=seq ...’
where each key=seq entry assigns a valid seq SGR sequence to a key syntax category. A valid seq must contain either a single underscore "_"; or digits and/or semicolons ";". Here are the initial default key=seq entries.
1. normal
"0"
2. comment "1"
3. primary "0"
4. secondary "0"
5. keyword "94"
6. type "96"
7. attribute "33"
8. operator "1"
9. punctuation "0"
10. constant "91"
11. string "91"
12. number "95"
Any number of entries can be specified. If a seq is an underscore "_", the sequence specified for "normal" is used. Otherwise, if a seq is invalid, blank, empty or absent, its corresponding default sequence is used.
For example:
HAREDOC_COLORS=’comment=3 primary=1;4 attribute=41’ haredoc -Ftty log
The following environment variables affect haredoc’s execution:
Read the documentation for io:
haredoc io
Read the documentation for hash::fnv:
haredoc hash::fnv
Prepare documentation for hare::parse as HTML:
haredoc -Fhtml hare::parse >parse.html
hare(1)