haredoc(1)

NAME

haredoc - reads and formats Hare documentation

SYNOPSIS

haredoc [-at] [-F format] [identifiers...]

DESCRIPTION

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.

OPTIONS

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

DOCUMENTATION FORMAT

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;

TTY COLORS

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

ENVIRONMENT

The following environment variables affect haredoc's execution:

HAREDOC_COLORS | Customizes TTY format color rendering. See TTY COLORS.

EXAMPLES

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

SEE ALSO

hare(1)