Addons/docs/joxygen
Joxygen
Html pages are built by Pandoc from comments in J scripts. Pandoc should be installed before running Joxygen.
Documentation is read from comments that start with an arithmetic character, i.e. from the set +-*% . These indicate:
NB.% script documentation
NB.* definition documentation
NB.- continuation as ordinary text
NB.+ continuation as verbatim text
A J program reads the script and generates a file with pandoc markdown. Pandoc is then called to build the html file. This method allows most pandoc markdown to be included in the documentation itself.
A documentation entry starts with NB.% or NB.*, and continues with any number of NB.- or NB.+ lines. On each line, the entry begins immediately after the comment characters, so leading blanks are relevant.
Script documentation
A sequence of lines beginning NB.% is the script title and description. Only one such sequence is read, and can be anywhere in the script.
The first line is the title and is required. It has the form: scriptname - caption.
Subsequent lines are the description and are optional.
For example:
NB.%mywork.ijs - my work script NB.-Description NB.-more description... NB.-last line of description
Definition documentation
A sequence of lines beginning NB.* documents a definition. The first line has the form: name type caption, where type is one of acvmdn for adverb, conjunction, verb, monad, dyad and noun. Subsequent lines are the definition body.
Definitions with only one line are shown first in a table. The remaining definitions are then shown one by one in alphabetic order.
Each definition must match a global assignment in the script. Any mismatches cause error messages to be written to the J terminal.
For example:
NB.*LF n linefeed NB. NB.*foo v this is the caption for verb foo NB.-Description NB.-more description...
Continuation as ordinary text
Ordinary text lines are a markdown which is essentially that supported by pandoc, see below.
Three subtags are recognized. These create separate sections of the definition:
NB.-syntax: Syntax section
NB.-example: Example section
NB.-note: Note section
Note that the subtags end in : and are on lines by themselves.
Lines before any subtag are the description. If none given, the caption is used as the description, with first letter capitalized.
NB.*foo v This is the caption for foo NB.-This is a description of the verb foo. NB.-It can continue over multiple lines. NB.- NB.-syntax: NB.-res=. [option] foo args NB.- args description NB.- option is boolean NB.- res is ... NB.-no: NB.-Here are extra details for foo ...
Continuation as verbatim text
Lines beginning NB.+ are rendered in <pre> tags, and should be used for code.
Pandoc Markdown
Most pandoc markdown is supported, e.g. *emphasis* and **bold**.
Any lines beginning with a space are treated as line blocks, i.e. as if the lines begin with |.
For verbatim code, use the NB.+ tag.
For hard line breaks, use \ at the end of the line.
Urls are in the form [name](url), for example:
[Folders and Projects](http://www.jsoftware.com/jwiki/Guides/Folders%20and%20Projects)
Tables can be entered with cells separated by pipes. In the following example, the first (header) line is optional, while the second line is required. Here, the colon (:) indicates the justification, in this case right, center, left. The pipe characters need not line up vertically.
NB.-|price|item |description| NB.-|----:|:----:|:----------| NB.-|2.05 |apple |singles | NB.-|1.37 |nuts |per 100gm | NB.-|13.09|orange|per dozen |
Example
The script ~addons/docs/joxygen/test.ijs builds docs from source in the ~addons/docs/joxygen/testscripts directory, with output to ~temp/joxygen. The output should match the example output in ~addons/docs/joxygen/testdocs.
Contributed by Ric Sherlock and Chris Burke.