Easy Help

Tuesday, June 13, 2023

One of the challenges with any software platform, and particularly for programming languages, is having enough well-written documentation to onboard new users as well as providing assistance to those that have been using the platform for longer.

In previous versions of Factor, the help system – which provides for writing documentation and browsing the documentation in the command-line as well as in the UI browser – required somewhat verbose syntax needing, for example, all text to be defined as literal strings. This became both hard to write and hard to read as source code.

In the upcoming release of Factor 0.99, we have a kind of “easy help” syntax that allows some smart interpretation of documentation syntax so that the following example is now possible:

HELP: do-the-thing
{ $values
    word: word
    n: number
    quot: { $quotation ( x -- y ) }
    seq: { $sequence "things" }
    seq: { $sequence fixnum }
    obj/f: { $maybe object }
    this: "that other thing"
}
{ $description
    Does the thing. Words which \ execute an input
    parameter must be declared \ inline so
    that a caller which passes in a literal word can have a
    static stack effect.

    A second paragraph should work also. And we should be 
    able to refer to markup { $snippet "text" } .
}
{ $notes
    To execute a non-literal word, you can use
    \ execute( to check the stack effect before
    calling at runtime.
}
{ $examples
    [=[
        USING: kernel io words ;
        IN: scratchpad : twice ( word -- ) dup execute execute ; inline
        : hello ( -- ) "Hello" print ;
        \ hello twice
        "Hello\nHello"
    ]=]
} ;

This also applies to articles, which can now be written much more clearly:

ARTICLE: "roman" "Roman numerals"
The { $vocab-link "roman" } vocabulary can convert numbers to and from the
Roman numeral system and can perform arithmetic given Roman numerals as input.

A parsing word for literal Roman numerals:
{ $subsections POSTPONE: ROMAN: }

Converting to Roman numerals:
{ $subsections
    >roman
    >ROMAN
}

Converting Roman numerals to integers:
{ $subsections roman> }

Roman numeral arithmetic:
{ $subsections
    roman+
    roman-
    roman*
    roman/i
    roman/mod
} ;

We have periodically found some edge cases that don’t quite format as expected, but likely most of these cases have been resolved.

Give it a try and let us know what you think!