chalk

chalk

Simple hahn-style in-source documentation

Chalk attempts to be a simpler alternative to Chicken 4's hahn + hahn-utils, generating wiki output with support for procedure, variables, syntax, modules, include files, and egg files. It tries to be as basic as possible, performing almost no code analysis and no evaluation, while making it easy to generate documentation from one or more files.

The following is hahn's fibonacci example, rewritten for chalk. Note key differences: The example is simply a string (and therefore not evaluated), whith the option of a @pre or @post caption.

(define (fibonacci n)
  @("Computes the nth [[http://en.wikipedia.org/wiki/Fibonacci_number|Fibonacci]].
This naïve algorithm runs in ''O(2^n)''; using e.g. memoization, we could bring
it down to ''O(n)''."
    (n "The nth number to calculate")
    (@to "integer")
    (@example
     (@pre "For example, computing the 6th Fibonnaci number (starting from 0)")
     "(fibonacci 6) ; => 8"))
  (case n
    ((0) 0)
    ((1) 1)
    (else (+ (fibonacci (- n 1))
             (fibonacci (- n 2))))))

Which produces the following wiki output:

[procedure] (fibonacci n) → integer

Computes the nth Fibonacci. This naïve algorithm runs in O(2^n); using e.g. memoization, we could bring it down to O(n).

n: The nth number to calculate

For example, computing the 6th Fibonnaci number (starting from 0)

(fibonacci 6) ; => 8

Syntax

Most expressions of the following form can be documented to varying degrees of automation, where SIGNATURE can be a pair (as in a procedure definition).

(DEFINE SIGNATURE BODY ...)

Documentation entails inserting a docexpr of the following form before the BODY.

@("Description" ... [OPTION] ...)

Multiple top-level strings in the docexpr are turned into separate wiki paragraphs.

Variables

Variables are documented as follows, ignoring potentially disastrous rounding practices:

(define pi @("The ratio of a circle's circumference to its diameter.") 3.14)

The special tag @internal can be used to suppress output, and is useful for documenting unexported variables internally:

(define counter
  @("How many times thing has happened."
    (@internal)))

Procedures

Procedures are documented similarly, but can contain the tags, @to, and @example, as well as listing function parameters:

(define (foobar a b)
  @("Does baz."
    (a "An input")
    (b "Another input")
    (@to integer)
    (@example
     (@pre "For example, to do baz with foobar:")
     "(foobar blarg arg) ; => 4"))
  (baz))

In the case of procedures defined as variables, chalk considers them variables by default, using the function name as a signature. In either case, you can override the default signature with the tag @sig, and you can specify that it is indeed a procedure as follows:

(define function?
  @(fn "This is definitely a function"
       (@sig (function? a b c)))
  (lambda () (print "bar")))

You can specify that a variable definition is a procedure with any of fn, proc, function, or procedure in the first position of the docexpr.

Tags behave as follows:

@to: A string or expression to be inserted as {{→ expr}}
@example: A string to be enscripted with scheme highlighting, with optional @pre or @post caption.
@sig: A string or expression that override the procedure signature
@internal: Suppress output, documented for internal use.

Syntax definitions

Syntax definitions accept the same tags and are defined equivalently to procedures, provided that it they are defined using define-syntax. The @sig tag is especially useful for specifying syntax usage, since chalk won't automatically detect the signature. Here's a rather silly example:

(define-syntax hello
  @("Hello there!"
    (@sig (hello a b c)))
  (syntax-rules ()
    ((_ a b c)
     "Hello there!")))

For syntax defined otherwise, you can specify that it is syntax like so:

(define-syntax-rule (hello a b c)
  @(syntax "Hello")
  "Hello there")

You can specify that a definition is syntax with either syntax or macro in the first position of the docexpr.

Records

Currently, two types of record definitions are supported - define-record and define-record-type from chicken.base. Records can be documented internally by specifying a @internal file, and they additionally accept the tag @full. When specified, it generates a list of all of the procedures associated with that record definition. Otherwise, only the record name is documented, and procedure documentation can be added manually.

For example:

(define-record point
  @("A point"
    (@full))
  x y)

Produces the following output:

[record] point
[procedure] (make-point x y)
[procedure] point?
[procedure] point-x
[procedure] point-y

A point

Top-level documentation

A docexpr outside of a definition can be used to insert arbitrary text. Additionally, the following top-level tags are supported:

script: Generate an enscript segment, with optional highlight tag. Can contain multiple strings.

@(script
  (@highlight "scheme")
  "(print \"hello\")"
  "(print 4)")

In addition to the @highlight tag, a caption can be inserted before or after a script using the tags @pre and @post.

heading, title, ==: A title

@(== "My egg")

Various subheadings:

subheading, subtitle, ===
subsubheading, subsubtitle, ====
subsubsubsubheading, subsubsubsubtitle, =====
deflist: A definition list such as this one

@(deflist
   (key "value")
   (definitionless-term)
   (term "definition"))

Lists and tables are not currently supported, but are planned for the future. In the meantime, unsupported forms of wiki syntax can be inserted literally using a top-level docexpr.

Compiling and running programs

To compile a scheme file containing chalk special syntax, you can use -X chalk. For script usage (e.g. with csi -s), you can use import chalk.

Chalk program usage

The chalk program generates output to stdout or a specified output file based on the given input file(s), and optionally: a .egg file, a .release-info file, and/or a LICENSE file. For more info, see chalk --help:

Usage: chalk [OPTION]... [FILE]...
 -h, --help               Print usage
 -o, --output=FILE        Write to file
 -i, --ignore-egg         Ignore .egg file
 -r, --ignore-release     Ignore .release-info file
 -n, --no-toc             Don't add a toc
 -e, --email=EMAIL        Include EMAIL with author
 -H, --head=FILE          File to add to beginning of documentation
 -P, --prologue=FILE      File to add after synopsis
 -E, --epilogue=FILE      File to add before maintainer info
 -T, --tail=FILE          File to add to end of documentation
 -L, --no-license         Don't insert a license file
 -l, --license=FILE       File to use as license (defaults to LICENSE if unspecified)
 -m, --module-headers     Create === Module-name headers

A .release-info file can contain optional comments following release expressions (on the same line), which are used as version descriptions when generating a version history section of the documentation, for example:

(uri targz "https://example-url.com")
(release "0.3.1") ; Fixes bug
(release "0.3.0") ; Adds feature
(release "0.2.0")
(release "0.1.0") ; Initial version

0.3.5: Add support for define-library
0.3.4: Allow multiple strings as description
0.3.3: Reduce line spacing, change license options
0.3.2: Add multi-line script support
0.3.1: Fix bug: release-info not ignored on ignore-egg
0.3.0: Add support for records and syntax
0.2.0: Add @example, listed function parameters, script caption
0.1.0: Initial version

License

Copyright (c) 2020 Diego A. Mundo
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted (subject to the limitations in the disclaimer
below) provided that the following conditions are met:

     * Redistributions of source code must retain the above copyright notice,
       this list of conditions and the following disclaimer.

     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

     * Neither the name of the copyright holder nor the names of its
       contributors may be used to endorse or promote products derived from
       this software without specific prior written permission.

NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS
LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

chalk

Introduction

Syntax

Variables

Procedures

Syntax definitions

Records

Top-level documentation

Compiling and running programs

Chalk program usage

Full Example

Author

Repository

Version History

License