AutodocFs

The Problem

One of the very time consuming parts of writing source documentation is gathering all the project definitions, adding the section/subsection/ in-text-formatting and so on before the actual content can be composed. This can be a contributing factor for why it never gets done.

My doc sites use the very capable py.sphinx program to produce HTML pages for the viewer. While py.sphinx is very easy to use, automation by way of shell scripts, Makefiles and methods as described here can drastically shorten the effort needed.

The less time I need to spend creating documentation, the more time I can spend designing/prototyping/building hardware and writing crap Forth code!

My Solution

AutodocFs

AutodocFs is a system I’m working on which can parse a complete Forth project source-file into formatted HTML documentation.

Source to HTML

  1. View the Forth source-code.

  2. View the ReST documentation template generated by AutodocFs.

  3. View the HTML view of the documentation generated by py.sphinx.

Features

  • Adds a unique page label: “$(OUTFILE).link” to the first line of the $(OUTFILE).

  • Inserts the DAY and DATE to the $(OUTFILE)

  • Adds an INDEX for every Word. If you click on Index then on ‘-usb’ you will see it’s one of the allsource.fs.rst links.

  • Auto subsection formatting: Counts the number of characters in each Word then adds the subsection formatting character “-” of the correct length underneath it.

  • Displays the ( Stack Comment ) contents.

  • NEW: Duplicate Word alert and list.

Bugs

A few minor annoyances, nothing serious.

How AutodocFs Work?

Using Gema, a text preprocessor, the Forth Source code is parsed for definitions of the form below:

\:\S*\S(\SX--Y\S)\S*\S\;

In other words for a definition to be recognised it must :

  1. start with a COLON. This can be the first character in a line or preceded by one or more SPACES.

  2. the COLON must be followed by one or more SPACES

  3. the definition name can be any character(s) but must be followed by one or more SPACES

  4. next is the LEFT BRACE followed by one or more SPACES

  5. X can be null or any character(s) and is the STACK COMMENT INPUT

  6. next, a pair of hyphens are required

  7. Y can be null or any character(s) and is the STACK COMMENT OUTPUT followed by one or more SPACES.

  8. A RIGHT BRACE followed by one or more SPACES.

  9. any character(s) followed by one or more SPACES.

  10. finally, a SEMI COLON to terminate the definition.

Everything after the SEMI COLON (item 10) is discarded. If definitions do not conform to this pattern exactly, they are ignored.

Note

before Gema processing, the source file is stripped of all comments denoted by a leading backslash.

Gema

http://sourceforge.net/projects/gema/

Note

Gema parses each line with the syntax on the left of the “=” and replaces it with the string on the right.

AutodocFs Makefile

For FreeBSD, should work on Linux etc.

all: create

.PHONY:
create:
  echo .. _$(SRCFILE).link: > $(OUTFILE)
  echo $(BLANKLINE) >> $(OUTFILE)
  echo $(TITLE) >> $(OUTFILE)
  echo $(TITLE1) >> $(OUTFILE)
  date >> $(OUTFILE)
  echo $(BLANKLINE) >> $(OUTFILE)
  gema -t -nobackup -line $(SRCFILE) -f delcomments.pat > $(INTERMEDIATE)
  gema -t -nobackup -line -match $(INTERMEDIATE) -f dup.pat > $(WORDSONLY)
  sort $(WORDSONLY) > $(SORTED)
  uniq -d $(SORTED) $(DUPLICATES)
  gema -t -nobackup  -match $(INTERMEDIATE) -f main.pat >> $(OUTFILE)
  sh duplicates-detected.sh

AutodocFs Gema Pattern Files

delcomments.pat

! Removes comments, Words only
\\ *\n=\n

dup.pat

List just the Word names to be used for finding duplicates

\:\S*\S(\S*\S)\S=$1\n

main.pat

The heavy lifter.

\:\S*\S(\S*--*\S)\S*\S\;=.. index:: $1\n\n$1\n @repeat{@length{$1};-} \n::\n\n  ( $2--$3 )\n\n\n\n

duplicates-detected.sh

#!/bin/sh
if [ -s 'duplicates.fs' ]
then echo "
  DUPLICATE WORDS DETECTED !!!
  DUPLICATE WORDS DETECTED !!!
  DUPLICATE WORDS DETECTED = !!!"
  cat 'duplicates.fs'
fi

Note

Any duplicate Word names will be listed in duplicates.fs