Version 1 Primary contributors: Brad Eckert brad1NO@SPAMtinyboot.com
DexH is a simple literate programming tool inspired by MPE's DOCGEN. DexH can also be used to write articles about Forth featuring a mixture of documentation and source code. DexH is a standalone program that processes a Forth source file. The following command does the conversion:
HTML input_filename
Commands are embedded within comments. You can use the following formats, with either starting at the first column.
You can append HTML to created files by HTMLing any number of source files but you should use a *Z command to complete the HTML.
| Command | Effect |
| ** | continuation of G, E or P |
| *! | create and select a new output file |
| *> | select an existing file to add text to |
| *T | Title |
| *S | Section |
| *N | Sub-section |
| *P | Paragraph |
| *E | Paragraph which is a code example |
| *B | Bullet entry |
| *G | Glossary entry for the previous line |
| *W | raw HTML |
| *Z | End output |
| *+ | Include source code as document text |
| *- | Turn off source code inclusion |
DexH is ANS Forth except for the need for BOUNDS, SCAN, SKIP and LCOUNT. They are commonly used words but redefined here for completeness.
\ : BOUNDS OVER + SWAP ; \ : SCAN ( addr len char -- addr' len' ) \ >R BEGIN DUP WHILE OVER C@ R@ <> WHILE 1 /STRING REPEAT THEN R> DROP ; \ : SKIP ( addr len char -- addr' len' ) \ >R BEGIN DUP WHILE OVER C@ R@ = WHILE 1 /STRING REPEAT THEN R> DROP ; : LCOUNT ( addr -- addr' len ) DUP CELL+ SWAP @ ;
Some files use very long lines, which is desirable for long sections of documentation. You can allocate buffers for lines longer than 2000 chars by changing the following line:
10000 CHARS CONSTANT max$
HTML needs some canned boilerplate. This is created by ,| since HTML doesn't use | characters.
: (,$) ( a len -- ) DUP C, 0 ?DO COUNT C, LOOP DROP ; \ text to dictionary
: ,| ( <text> -- ) [CHAR] | WORD COUNT -TRAILING (,$) ; \ compile string
CREATE HTMLheader
,| <?xml version="1.0"?> |
,| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
,| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
,| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
,| <head> |
,| <meta http-equiv="Content-Type" content="text/xml; charset=iso-8859-1" />|
,| <meta name="GENERATOR" content="DexH v0.0" /> |
,| <style type="text/css"> |
,| body {background: #FFFFFF;} |
,| </style> |
,| <title> |
0 C,
All output is via OUT and OUTLN, which can be sent to the screen for debugging purposes.
0 VALUE testing \ screen is for testing : werr ( n -- ) ABORT" Error writing file" ; : out ( a len -- ) testing IF TYPE ELSE outfile WRITE-FILE werr THEN ; : outln ( a len -- ) testing IF TYPE CR ELSE outfile WRITE-LINE werr THEN ;
Some characters are replaced by special strings so they can't be interpreted as tags. Also, runs of blanks need special treatment.
: outh ( a n -- ) \ HTMLized text output 999 bltally ! BOUNDS ?DO I C@ CASE [CHAR] & OF S" &" out ENDOF [CHAR] < OF S" <" out ENDOF [CHAR] > OF S" >" out ENDOF [CHAR] " OF S" "" out ENDOF [CHAR] © OF S" ©" out ENDOF BL OF bltally @ 0= IF S" " ELSE S" " THEN out 1 bltally +! ENDOF I 1 out 0 bltally ! ENDCASE LOOP S" " outln ;
The fields in a table are separated by | (vertical bar) and end in |.
: HTML ( <filename> -- )
Convert a file or files to HTML. Output filenames are included in the source file.
: q ( <string> -- )
Test a single line of text, outputting to the screen.