hare

[hare] The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

haredoc.scd (3108B)

      1 haredoc(1)
      2 
      3 # NAME
      4 
      5 haredoc - reads and formats Hare documentation
      6 
      7 # SYNOPSIS
      8 
      9 *haredoc* [-at] [-F _format_] [_identifiers_...]
     10 
     11 # DESCRIPTION
     12 
     13 *haredoc* reads documentation for a set of identifiers from Hare source code,
     14 and optionally prepares it for viewing in various output formats. By default,
     15 *haredoc* will format documentation for your terminal.
     16 
     17 See *DOCUMENTATION FORMAT* for details on the format.
     18 
     19 # OPTIONS
     20 
     21 *-a*
     22 	Show undocumented members (only applies to -Fhare and -Ftty).
     23 
     24 *-F* _format_
     25 	Select output format (one of "html", "hare", or "tty").
     26 
     27 *-t*
     28 	Disable HTML template.
     29 
     30 *-T* _tags_
     31 	Adds additional build tags. See *CUSTOMIZING BUILD TAGS* in *hare*(1).
     32 
     33 *-X* _tags_
     34 	Unsets build tags. See *CUSTOMIZING BUILD TAGS* in *hare*(1).
     35 
     36 # DOCUMENTATION FORMAT
     37 
     38 The Hare formatting markup is a very simple markup language. Text may be written
     39 normally, broken into several lines to conform to the column limit. Repeated
     40 whitespace will be collapsed. To begin a new paragraph, insert an empty line.
     41 
     42 Links to Hare symbols may be written in brackets, like this: [[os::stdout]]. A
     43 bulleted list can be started by opening a line with "-". To complete the list,
     44 insert an empty line. Code samples may be used by using more than one space
     45 character at the start of a line (a tab character counts as 8 spaces).
     46 
     47 This markup language is extracted from Hare comments preceding exported symbols
     48 in your source code, and from a file named "README" in your module directory, if
     49 present.
     50 
     51 ```
     52 // Foos the bars. See also [[foobar]].
     53 export fn example() int;
     54 ```
     55 
     56 # TTY COLORS
     57 
     58 The TTY output format renders colors in the terminal with ANSI SGR escape
     59 sequences, behaving similarly to this shell command:
     60 
     61 	printf '\\033[0;%sm' '_seq_'
     62 
     63 These sequences can be customised with the *HAREDOC_COLORS* environment
     64 variable, which follows this whitespace-delimited format:
     65 
     66 	HAREDOC\_COLORS='_key_=_seq_ _key_=_seq_ _..._'
     67 
     68 where each _key_=_seq_ entry assigns a valid _seq_ SGR sequence to a _key_
     69 syntax category. A valid _seq_ must contain either a single underscore "\_"; or
     70 digits and/or semicolons ";". Here are the initial default _key_=_seq_ entries.
     71 
     72 . normal        "0"
     73 . comment       "1"
     74 . primary       "0"
     75 . secondary     "0"
     76 . keyword       "94"
     77 . type          "96"
     78 . attribute     "33"
     79 . operator      "1"
     80 . punctuation   "0"
     81 . constant      "91"
     82 . string        "91"
     83 . number        "95"
     84 
     85 Any number of entries can be specified. If a _seq_ is an underscore "\_", the
     86 sequence specified for "normal" is used. Otherwise, if a _seq_ is invalid,
     87 blank, empty or absent, its corresponding default sequence is used.
     88 
     89 For example:
     90 
     91 	HAREDOC\_COLORS='comment=3 primary=1;4 attribute=41' haredoc -Ftty log
     92 
     93 # ENVIRONMENT
     94 
     95 The following environment variables affect *haredoc*'s execution:
     96 
     97 |[ *HAREDOC_COLORS*
     98 :< Customizes TTY format color rendering. See *TTY COLORS*.
     99 
    100 # EXAMPLES
    101 
    102 Read the documentation for _io_:
    103 
    104 	haredoc io
    105 
    106 Read the documentation for _hash::fnv_:
    107 
    108 	haredoc hash::fnv
    109 
    110 Prepare documentation for _hare::parse_ as HTML:
    111 
    112 	haredoc -Fhtml hare::parse >parse.html
    113 
    114 # SEE ALSO
    115 
    116 *hare*(1)