Clone wiki

camelforth / Sources

CamelForth Sources Layout & Conventions

The layout of the sources is straightforward. There is a generic directory plus a target-specific directory for each of the existing targets:

  • speccy, Sinclair ZX Spectrum +3/+3e
  • sprinter, PetersPlus Sprinter
  • z88, Cambridge Z88

Source files are named according to the following conventions:

  • .hi, High-level (Forth) definitions
  • .low, Low-level (assembly) definitions
  • .dep, Target-dependent definitions (may mix Forth and assembly)
  • .zx, Spectrum-specific definitions
  • .spr, Sprinter-specific definitions
  • .z88, Z88-specific definitions
  • .frg, code fragments
  • .asm, z80asm assembly files
  • .def, z80asm definition files
  • .fth, Forth files
  • .sh, Shell scripts

For proper automatic glossary generation, each word should be documented within the sources on a single line, laid out as follows:

  • Columns 1-2: semicolon, definition class, space:
  • ;C definitions from main wordsets (eg core, file, search-order)
  • ;X definitions from extension wordsets (eg core extension, file extension, search-order extension)
  • ;Z definitions not present in the ANS standard wordsets
  • ;- headerless words
  • Columns 4-19: word name
  • Columns 21-47: stack picture
  • Columns 49 onwards: description

All other comment lines within the sources should contain a space directly after the semi-colon, to avoid them being erroneously selected for inclusion in the glossary.