Glosara   README

Description

Glosara is a glosser for Forth sources, though it could be used with other programming languages as well. Its goal is to extract the glossary and modules documentation out of the sources and build the documents in Asciidoctor format, with cross references.

Current status

Glosara is very stable. It’s being used to build the documentation of Solo Forth, Galope and other Forth projects of the author, and it’s being completed and improved during the process.

Requirements

Glosara uses some modules from the following libraries:

Usage

Usage: glosara  { [option...] { <input-file> | <-i file> } [option...] ...}

Note: both `input-file` and the `-i` option start the program
immediately with the currently parsed options.

  -?, --help     Show this help.
  -V, --version  Show version info.
  -i, --input    Set a file containing a list of input files (one per line).
                 This option, as well as an explicit input file, starts the
                 program immediately, using only the options that were
                 specified before it.
  -l, --level    Set the headings level (1..6).
  -o, --output   Set the output file.
  -u, --unique   Flag: reject the duplicated entries.
  -v, --verbose  Flag: activate the verbose mode.
  -m, --markers  Set the glossary entry markers used in the source code;
                 default: "doc{ }doc".
  -a, --annex    Flag: set the annex mode, i.e. just convert the links of the
                 given file, but don't extract glossary entries from it.
  -s, --sections Flag: add a section heading before every glossary entry that
                 starts with a new initial.
  -d, --dir      Set the temp directory; default: /tmp/glosara/.

Brief history of the code

2015-09: The code was started as part of Solo Forth in order to build its documentation, but a few months later it became an independent project.

2016-04-28: A Git repository was created from the development backups and uploaded to GitHub in order to preserve its evolution from the start and resume the development.

2020-12-03: The Git repository was converted to a Fossil repository, keeping GitHub as a mirror.