3.18. Documentation and Help System

Lush has a convenient documentation system that allows users to:

browse the Lush documentation using the GUI tool (helptool)
quickly access the documentation of a particular function or topic from the Lush prompt by typing ^Atopic or by calling (apropos "topic") .
consult HTML, LaTex, PostScript, or DjVu versions the Lush manual

The documentation system allows developers to easily include the code and its documentation in the same file. It also makes it easy to organize sections and entries into a complete manual.

3.18.0. Using the Online Manual

3.18.0.0. ^Atopic

Typing ^A (caret then A or control-A) followed by a topic at the Lush prompt is the easiest and quickest way to obtain help. This command displays a numbered list of those entries and sections of the manual that contain topic as a substring. The user is then asked to pick one of the choices by entering the corresponding number. Entering q or enter returns to the Lush prompt. If the list has only one match, the corresponding manual entry is shown right away. The first time this command is invoked, it parses and reads the manual. The ^A macro-character calls the (apropos "topic") function described below. Example:

? ^Aregex-match

------------------------------------------------------------------------
(regex-match <r> <s>)                         [DX]
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 

Returns t if regular expression r exactly matches the entire string s . 
Returns the empty list otherwise. Example: 
? (regex_match "(+|-)?[0-9]+(\\.[0-9]*)?" "-56")
= t

= ()

3.18.0.1. (apropos topic-string [force])

[DE]

This command displays a numbered list of those entries and sections of the manual that contain topic as a substring. The user is then asked to pick one of the choices by entering the corresponding number. Entering q or enter returns to the Lush prompt. If the list has only one match, the corresponding manual entry is shown right away. The first time this command is invoked, it parses and reads the manual.

If the optional boolean parameter force is non-nil, the Lush manual is re-read.

3.18.0.2. (helptool [book [title]])

[DM] (lsh/libogre/helptool.lsh)

Author(s): Yann LeCun

Helptool is a GUI-based browser and search engine for the Lush manual. It is invoked by simply typing (helptool) at the Lush prompt.

Helptool provides an "explorer-like" GUI to browse through the sections and entries of the documentation. The optional argument book can be one of the following:

if absent or nil, the default documentation book is read from lsh/lush-manual.hlp (if necessary) and displayed. This book is read only once in a session.
if equal to t, the default document book is read (or re-read if it was previsouly read), and displayed.
if equal to a string, a documentation book is read from the file passed in the string (which can be a .hlp or a .lsh file). The second optional argument is used as the title of the book. If the second argument is not present, the first argument will be used as the title. This is a convenient way of browsing the documentation of a Lush program that is not part of the standard package. It is also a convenient way to use Lush as a documentation browser for other projects.

The Helptool window is composed of an "explorer-like" area on the left that contains a hierarchical list of sections and entries, and a document display area on the right that shows the body of the selected entry. Entries can be opened and closed with a mouse click on the pink square icon. The content of an entry can be displayed by simply clicking on it.

Entering a string or a regular expression in the search tool at the top of the window will "filter" entries that contain that string or match that regular expression. Hitting the enter key or the next button (or the space key in the explorer area) will jump from matching entry to matching entry.

Most users will prefer to use the keyboard shortcuts that provide a very fast and convenient way to navigate the manual. The explorer area, the document area, and the search tool have different keyboard shortcuts. It should be noted that the various areas must be clicked on to get the keyboard focus. The most important key in the explorer area is the space bar, which allows for continuous sequential reading.

Here are the explorer area keyboard shortcuts:

down-arrow or n : move to the next entry (without displaying the document)
up-arrow or p : move to the previous entry at the same hierarchical level (without displaying the document)
right-arrow : open the current entry (show the subentries) and display the body.
left-arrow : close the current entry (hide the subentries), or move to the parent entry if the current entry is already closed (or if it has no subentries).
space : This provides a simple way to read to manual sequentially. Hitting space will display the body of the current entry in the document area if it is not already being displayed. If it is already being displayed, the document area will be scrolled down. If the document area is already at the bottom, it will go to the next entry that matches the current search string (or to the next entry if the search string is empty).
backspace : scroll up the document area.
enter : go to the next entry matching the search string (or the next entry if the search string is empty) and display the corresponding body in the document area.
c : close all open entries (collapse the entire tree) and go to the title entry.

Examples of how to invoke Helptool:

(helptool) : normal call.
(helptool t) : force re-reading of lush manual
(helptool "sdl/sdl.hlp") : read all entries in file sdl.hlp and and display as a book entitled "sdl/sdl.hlp".
(helptool "sdl/libsdl.lsh" "LibSDL") : read all entries in libsdl.lsh and display as a book entitled "LibSDL".
(helptool "/home/yann/blah.hlp" "my blah") : read all entries in /home/yann/blah.hlp and display as book entitled "my blah".

At startup, helptool only loads the title lines of each section or entry, but not the bodies. The bodies are read on demand and cached. They are re-read if the file where they reside has been modified since last time it was read.

Known bug: Reading the entire Lush manual takes several seconds.

3.18.1. Writing Documentation

Documentation is either extracted from comments in Lush files (with ".lsh" extension), or extracted from Lush documentation files (with ".hlp" extension).

Help entries can contain text, and/or can contain other help entries as subtopics. Entries can be organized hierarchically into books that can be browsed graphically using (helptool) . Entries in a file are added to the main documentation by inserting the file name at the desired location in one of the .hlp files read by (helptool) .

Looking at or at any .lsh or .hlp file in , , or is a good way to learn how to organize Lush documentation files or the comments of a Lush file in order to provide documentation.

3.18.1.0. Creating a New Section or Entry

Sections or entries are created in .lsh or .hlp files by a title line that starts with the compound macro-character #? . Title lines can create new sections, describe variables, functions, classes, and methods.

Here are a few examples of typical title lines:

```
 #? *** All about Choucroute Garnie 
```
: Add a Section
```
 #? ** << choucroute-garnie.lsh 
```
: Include .lsh file
```
 #? << choucroute-garnie.hlp 
```
: Include .hlp file
```
 #? choucroute-garnie 
```
: Describe Variable

 #? (garni-la-choucroute <saucisse> <patates>)

: Describe Function

```
 #? * choucroute 
```
: Describe Class
```
 #? * (new choucroute) 
```
: Describe Constructor

 #? (==> <choucroute> garni <saucisse> <patates>)

: Describe Method

As shown above, the #? of each entry can optionally be followed by one or more asterisks. The number of asterisks specifies the hierarchical level of the entry in the manual relative to the other entries in the same file. Entries with fewer asterisks than a previous entry in the same file will become subtopics of that previous entry:

      #? *** My Section Title.
      my section text goes here
      #? ** My Subsection Title 1
      my subsection 1 text goes here
      #? ** My Subsection Title 2
      my subsection 2 text goes here

Entries that document functions, classes, methods, and variables, should be written according to the following convention:

Function: Function description entries indicate how to call the function. Arguments are indicated by angle brackets. Here are a few examples:
```
      #? (car <list>)
      #? (+ <n_1> ... <n_n>)
      #? (new-window [<w> <h>] <name>)
  
```
Variable: Description of variables should simply include the variable name on the title line. It is recommended that the text include a
```
 {<type> VAR} 
```
directive.
Class: Class descriptions are usually associated with an entry for its constructor, indicating how to create an instance. Method documentation entries show how to call the method and should be subheadings of the constructor entry:
```
      #? * (new helpinfo <record>)
      #? (==> <helpinfo> tty-print)
   
```

A special directive in .hlp files indicate that entries at that location should be read from another file. The following example inserts all toplevel entries from file "toto.hlp" as a section marked with two stars (the stars of the entries in the file "toto.hlp" are only used to place the those entries relative to each other).

     #? ** << toto.hlp

3.18.1.1. Document Body: Introduction

The body (text) of an entry or section can be written following the title line.

In a .hlp file, the body of an entry is whatever text is found until the end-of-file or the next entry title line (i.e. the next #? at the beginning of a line). An empty line is interpreted as a paragraph boundary (but a line with only spaces is not).

In a .lsh file, the body of an entry is whatever bloc of consecutive comment lines (i.e. lines that begin with one or more semicolons) that follow the title line. By convention, the lines should begin with two semicolons. A lines with only semicolons is intepreted as a paragraph boundary.

The body of an entry or section can be written acording to two different syntaxes. The "normal" syntax comprises a set of curly-brace-enclosed tags that have the same name and more or less the same function as the corresponding HTML tags. The "old" syntax (present for backward compatibility) comprises TROFF/NROFF-like tags that must be at the beginning of a line and begin with a dot. Blank lines indicate paragraph boundaries in both syntaxes

Debugging a documentation file or a Lush file with documentation entries can be done easily by calling (helptool "the-file-to-be-debugged") . The entry bodies are re-read whenever the file is modified, but the entries themselves (the title lines) are not.

3.18.1.2. Document Body: the Brace Syntax

The brace document format consists of segments of text enclosed between curly braces with a tag immediately following the opening brace. In this syntax, the following characters or character sequences have a special meaning:

two carriage returns (blank line) : paragraph break
{tag...} : a brace tag expression
,(...) : read Lush expression in paren and insert it in the document. It will be evaluated at rendering time. If the result is a string, it will be inserted in the text.
\(...) : same as above
,$expr : read Lush object following dollar sign and insert it in the document. Unlike with the comma/paren construct, this allows to insert symbols and string literals. The Lush object will be evaluated at rendering time. If the result is a string, it will be inserted in the text.
\$expr : same as above
,,expr : read and evaluate the Lush expression and substitute the result (preferably a string) in the text. Unlike with with the single comma constructs, the evaluation is performed at read time.
... : display content of bracket as bold/highlighted (mainly used for short Lush code snippets or arguments of the function being described).

To insert text that contain the above combinations requires escaping. This can be done with the ,$"any legal Lush string" construct.

A brace expression is an expression of the form:

  {<tag1> word1 {<tag2> word21 word22} word3 .... wordn}

A brace expression is read by the Lush reader just like a regular Lush expression. The reader translates the above example into a list like this:

  (<tag1> -1 1 "word1" 1 
          (<tag2> -1 1 "word21" 1 "word22") 
          1 "word3" 1 "...." 1 "wordn")

Such brace lists produce the appropriate document when evaluated in the right context.

Here are the tags. Three dots indicate that text or other brace expression can be inserted.

Basic text formatting tags:

{br} : line break
{p} : paragraph break
{li ... } : list item. Preferrably (though not necessarily) appears within a ul tag.
{ul {li ...} ...}
: unstructured list with list items
{div ...} : does nothing, just groups its arguments
{pre ... /pre} : preformatted text (no need to escape special characters)
{code ... /code} : preformatted code displayed in blue (no need to escape special characters)
{img ... } : insert image

Text attribute tags :

{b ...} : turn to bold font
{i ...} : set font to italic
{c ...} : highlight, and turn bold (for code and arguments)

Metatags: The content of these tags is not displayed in the main document but is displayed in the header:

{author ...} : author
{symbol ...} : which Lush symbol does this entry describe.
{location ...} : override the name of the file in which this function/entry is defined. By default, this is automatically set to file being read.
{keywords ...} : keywords for searching this entry
{date ...} : date of creation/modification of the object being described. By default, this is automatically set to the last modification time of the file in which the entry is defined (if this file is known).
{title ...} : override for the name of the entry. By default this is set to the entry title line.
{type ...} : type of object being described. By default this is guessed from the entry title whenever possible.

Special Tags:

{ex lush-expression } : insert a demonstration of typing the lush-expression at the Lush prompt and getting the result.
{hlink } : hyperlink to URL or other entry in the document
{see } : hyperlink to URL or other entry in the document

Conditional tags:

{if-html ...} : insert only if rendering to HTML
{if-latex ...} : insert only if rendering to LaTeX
{if-ogre ...} : insert only if rendering to helptool
{if-text ...} : insert only if rendering to plain text

Tags that are legal but not yet implemented: these tags are legal but are not functional at the moment and and reserved for future implementations (they currently act as div):

{desc ... } : short one-line description of the entry
{u ...} : underlined text
{tt ...} : typewriter font
{font ...} : select font
{center ...} : center text
{h1 ...} : big title
{h2 ...} : medium title
{h3 ...} : small title

3.18.1.3. Document Body: the "Dot-Tag" Legacy Syntax

Predecessors to Lush (SN and TL3) used a format for documentation inspired by TROFF/NROFF with formatting tags that begin with a dot and are placed at the beginning of the line. Much of the Lush documentation is still in this format, which is why we document it here.

Within the text, strings enclosed in angled brackets are displayed in boldface and highlighted in a color different from the regular text. This should be used for short segments of Lush code, file names, arguments of the function being documented, and other litterals.

Tags are divided in three categories: tags with no argument, tags whose argument is on the same line as themselves, and tags whose "argument" (or scope) is the text until the next tag.

Formatting tags that take no arguments:

.P or .PP : paragraph break (blank line plays the same role), or return to paragraph fill mode
.BR : line break (without paragraph skip).

Formatting tags whose argument is on the same line:

.HLINK : hyperlink to another entry of a URL.
.SEE : reference/hyperlink to another entry.
.EX : example, a Lush expression that will be evaluated and whose result is displayed in the document.
.IMG ir .EPS : the path to an image file (in any format that ImageMagick understands).

Formatting tags whose argument is whatever text is between it and the next tag:

.LI or .IP : list item.
.PRE or .VP : pre-formatted text.
.CODE : displayed code.
.DIV : switch to paragraph mode (without a paragraph skip like .P

Conditional inclusion tags (active until the next tag):

.IFOGRE or .IFHELP or IFHLP : include only in helptool output.
.IFTEX : include only in LaTeX output.
.IFTXT : include only in plain text output.
.IFHTML : include only in HTML output

Metadata tags (whose argument is on the same line):

.TYPE : type of entry (e.g. DX, DE, CLASS, MSG....)
.DESC : short one-line description.
.FILE : file where the definition for the entry resides.
.AUTHOR or .AUTH : author(s)
.DATE : date of last modification.

Directive .EX lets you run a lisp expression and display it as an example. It is preferable that the expression carries no side effect.

Directive IMG allows to include a picture (in any format):

  .IMG toto.png

3.19. Word Processor

The help system is built around a rudimentary word processor system. This system can be used in Lush programs to format and display formatted text on various devices.

The basic structure manipulated by the word processing system is the brace expression as described in the section describing the help syntax.

A brace expression is an expression of the form:

  {<tag1> word1 {<tag2> word21 word22} word3 .... wordn}

A brace expression is read by the Lush reader just like a regular Lush expression. The reader translates the above example into a list like this:

  (<tag1> -1 1 "word1" 1 
          (<tag2> -1 1 "word21" 1 "word22") 
          1 "word3" 1 "...." 1 "wordn")

Such brace lists can be rendered appropriately when evaluated in the right context.

Brace lists can be rendered to plain text, to HTML, to LaTeX, or to a graphic device. A set of high level functions to do so is provided as described below. The typical syntax is as follows:

  (render-brace-XXX arg1 arg2 ... '{<p> this is the text to be rendered})

where XXX is the device (text, html, latex, or graphics) and arg1 ... argn are the arguments as described in the following sections. The above brace expression is equivalent to:

  (render-brace-XXX arg1 arg2 ... '(<p> "this" "is" "the" "text" "to" "be" "rendered"})

A brace expression can span multiple lines and contain other brace expressions. Here is an example:

  (render-brace-XXX arg1 arg2 ... 
   '{<p> this is the text to be rendered
     {<ul>
      {<li> first item}
      {<li> second item}
     }
     some more text.})

3.19.0. (render-brace-text left-margin right-margin brace)

[DE]

Renders the brace brace to the current output as plain text. The lines are wrapped at the right-margin . This is quite useful for producing formatted text from within a Lush script (e.g. to display a help text). Here is an example:

  #!/bin/sh
  exec lush "$0" "$@"
  !#
  (cond
    ((or (member "-h" argv) (member "--help" argv))
      (render-brace-text 0 72
       '{<p> This script does blah blah {<br>}
         The options are as follows:
         {<ul>
          {<li> "-h" or "--help": show this text}
          {<li> "-w" or "--wrong": produce the wrong output}}}))
    ((or (member "-w" argv) (member "--wrong" argv))
       (printf "wrong\n"))
    (t (printf "right\n"))))

3.19.1. (render-brace-html left-margin right-margin brace)

[DE]

Renders the brace brace to the current output as HTML. The lines are wrapped at the right-margin .

3.19.2. (render-brace-latex section brace)

[DE]

Renders the brace brace to the current output as LaTeX source. section is a string containing the section number of the brace within the LaTeX document.

3.19.3. (render-brace-graphics x y w brace)

[DE]

Renders the brace brace to the current graphic window at location x , y setting the width of a text line to w pixels.