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

commit 122eb279d1a13ec0b38dde408d12be43b7a7d7ac
parent 8ba4ede1175f7a8cf775c03dd1ad645183d73081
Author: Drew DeVault <sir@cmpwn.com>
Date:   Tue, 20 Apr 2021 13:22:10 -0400

Add haredoc(1) man page

MMakefile | 3++-
Adocs/haredoc.scd | 69+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile @@ -80,8 +80,9 @@ $(TESTCACHE)/hare.ssa: $(hare_srcs) $(hare_testlib_deps) @env HAREPATH=. ./.bin/hare build -o .bin/haredoc ./cmd/haredoc docs/hare.1: docs/hare.scd +docs/haredoc.1: docs/haredoc.scd -docs: docs/hare.1 +docs: docs/hare.1 docs/haredoc.1 clean: @rm -rf .cache .bin diff --git a/docs/haredoc.scd b/docs/haredoc.scd @@ -0,0 +1,69 @@ +haredoc(1) + +# NAME + +haredoc - reads and formats Hare documentation + +# SYNOPSIS + +*haredoc* [-t] [-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 + +*-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; +``` + +# 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)