chalk-bin

Generate in-source documentation

  1. chalk-bin
    1. Introduction
    2. Syntax
      1. Variables
      2. Procedures
      3. Syntax definitions
      4. Records
      5. Standalone definition documentation
      6. Top-level documentation
        1. Paragraph
        2. script
        3. == and subheadings
        4. deflist
        5. list, numlist
        6. table
      7. Inline markup
    3. Chalk program usage
      1. Release-info format
      2. Org-mode and Markdown
    4. Full Examples
      1. In source
      2. Separate docs
    5. Author
    6. Version History
    7. License

Introduction

chalk (syntax) + chalk-bin (doc generation) 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 ...)

DEFINE can be the literal symbol define or a symbol that starts with it.

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

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

Strings and options can appear in any order. Top-level strings in the docexpr are turned into separate wiki paragraphs.

As a shorthand for a single-paragraph description with no options, you can use:

@"Single-paragraph description"

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)))

Chalk will also recognize define-foreign-variable definitions as variables.

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))

Chalk can also recognize procedures defined by directly using make-parameter, lambda,and the variants of foreign-lambda.

In other cases, for example using define with bespoke macros or functions, chalk has no way of knowing they are procedures and considers them variables by default, using the function name as a signature. In any 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?
  @(procedure
    "This is definitely a procedure"
    (@sig (function? a b c)))
  (procedure-generating-macro))

You can specify that a variable is a procedure by using the symbol procedure as 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 fro 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!")))

Otherwise, you can specify that a definition 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] record
[procedure] (make-point x y)
[procedure] point?
[procedure] point-x
[procedure] point-y

A point

Standalone definition documentation

If you need to document an arbitrary definition that doesn't fit neatly into a form that chalk recognizes, you can use a "free signature" declaration:

  @(procedure (@sig "(my-special-procedure)")
              "Chalk didn't recognize this, so I inserted it manually...")

Which renders as:

[procedure] (my-special-procedure)

Chalk didn't recognize this, so I inserted it manually...

All of the definition tags documented in Editing help are supported.

Top-level documentation
Paragraph

A docexpr outside of a definition can be used to insert arbitrary text.

@("First paragraph" "Second paragraph" "Third paragraph")
@"Single paragraph"
script

Generate an enscript block, with optional highlight tag. Can contain multiple strings.

@(script
  (@highlight "scheme")
  "(print \"hello\")"
  "(print 4)")
== and subheadings

A title, with several supported variants.

@(== "A title")
@(=== "A subheading")
@(== 1 "Same level subheading")
heading, subtitle, ==
Optionally takes a number as the second element to specify heading level (0-indexed).
subheading, subtitle, ===
subsubheading, subsubtitle, ====
subsubsubheading, subsubsubtitle, =====
deflist

A definition list.

@(deflist
   (key "value")
   (definitionless-term)
   (term "definition"))
list, numlist

A list or numbered list, which may be nested! For example, the following:

@(list
  "foo"
  "bar"
  "baz"
  ("cat"
   (list "dog"
         "mouse"))
  ("frisbee"
   (numlist "Yes"
            "no")))

Produces the nested list:

table

A table with an optional header

@(table
  (@header ("A" "B" "C"))
  ("It's" "Easy" "As")
  ("1" "2" "3"))

Renderd as:

A B C
It's Easy As
1 2 3

Inline markup

Inline markup like bold, italic, code, and links can be specified using svnwiki syntax. These are converted to other formats using svnwiki-sxml

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 out to file. Repeateable, extension determines format.
 -i, --ignore-egg         Ignore .egg file
 -d, --def-heading[=LEVEL]Generate a heading for each definition
 -r, --ignore-release     Ignore .release-info file
 -n, --no-toc             Don't add a toc
 -e, --email=EMAIL        Include EMAIL with maintainer
 -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)

Release-info format

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

Org-mode and Markdown

You can specify multiple files to write output to by repeating the -o flag. Currently, the .org and .md extensions are supported to generate Org-mode and Markdown files, respectively. Svnwiki output will always go to stdout unless a file with the .svnwiki extension is specified.

Full Examples

In source

See the ICU egg source code and documentation for a full example of a project using chalk.

Separate docs

Chalk can also be used on documentation-only files without attached scheme code. For example, here is the chalk-only source for this document chalk-bin.chalk

Author

Diego A. Mundo

Version History
1.0.2
Fix inline bold/italic for Org/Markdown
1.0.1
Bug fix and revert some incompatible args
1.0.0
Initial release splitting syntax from executable

License

BSD

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.