How To Write Ehc Documentation
This document describes how to create a new documentation document, in particular the steps required for adapting makefiles and where to put newly added text.
Documentation differs from normal text used to produce (e.g.) papers in that output can be produced for various output formats.
This gives a wider range of ways of reading, but comes at the price of a restrictive language for writing documentation.
The overall infrastructure for documentation is organized as follows:
- Documentation sources are kept in the text source directory (
- Each documentation document has a name and a variant number, the name is used to identify the relevant related files, the variant number is only used internally.
- For each documentation with name
N a build directory (
EHCHOME/build/N) is used holding the intermediate files for generating documentation files (
EHCHOME/doc/N.xxx). The suffix
xxx currently can be
- The documentation files in the documentation directory (
EHCHOME/doc) are then published or used otherwise.
2.1 Allocate a variant number
First a variant number must be allocated. All papers and documentation are constructed by Shuffle
from a set of files holding Shuffle
Of the various makefiles for producing text the makefile for text sources and variants (
) must include a definition for a new variant.
A new variant is added by:
- Finding an unused number, say 88, in the comment above variable
TEXT_SHUFFLE_ORDER, updating the comment with info about variant 88.
- Adding an order dependency on variant 39 (the base for documentation) in variable
TEXT_SHUFFLE_ORDER += \
39 < 88, \
The new documentation must be given a name which can be used for making and publishing the documentation:
- Find an unused name, say my-doc, and add it to the list in variable
- Connect the name to the variant number by including a makefile target in the makefile for targets (
EHCHOME/text/files-targets.mk). The target name must be of the form
Additional parameters can be passed to the recursive call to make, for example:
2.2 Adapt toplevel documentation
All documentation and papers share a common toplevel text file (
). Each documentation uses its variant number to identify its relevant text chunks.
Chunks common to all documentation is factored out into variant 39, all others inherit from it via Shuffle
's inheritance mechanism.
For our my-doc
with variant number 88 we need to add:
- Title + author. Search in the toplevel text file (
EHCHOME/text/main.cltex) for the combination of (e.g.)
%%[41 (start of a chunk with variant nr 41, used for this documentation) and
title, copy the text and change the variant number to 88 as to obtain something like:
- Content. Again search for
%%[41 and copy it:
%% My doc
some content here ...
2.3 Create content
Content is added according to the type of a chunk, as defined by Text2Text?
. At least type
is supported, a subset of LaTeX
for documentation purposes.
for more information.
We have used and will use chunk/text type
for the examples in this document.
By convention the real content is placed in a text source for My documentation (
) to which then is referred by name from the toplevel text file (
The name of the
source file (
) assumes the documentation is about a tool, hence the prefix
General topics use prefix
, slides use
. This convention is not enforced, so choose a sensible prefix.
The following must be done:
- Create (and add it to the repository, if necessary) the documentation source file (
EHCHOME/text/ToolDocMy.cltex) and add its base name
ToolDocMy to the makefile variable
TEXT_SUBS in the makefile for text sources and variants (
EHCHOME/text/files-variants.mk). It will now be automatically used when Shuffle is invoked.
- Add content in the documentation source file (
EHCHOME/text/ToolDocMy.cltex), for example by:
My is ...
The file defines named chunks
content of type
doclatex. These are included in the toplevel text file (
EHCHOME/text/main.cltex) by referring to their names:
A reference to a chunk consists of the chosen base name
ToolDocMy and the chunk name local to the corresponding text file, separated by a dot. Section headers can be placed anywhere, but for reuse of content it is advisable to keep hierarchical structure separated from the actual text.
2.4 Generate documentation from content
A pdf file for the documentation is made by:
It respectively runs the defined chunks through Shuffle
and twice through pdflatex.
2.5 Install documentation
Installation is optional.
Documentation is usually installed in the EHC documentation twiki
. The installable files for all documentation are created in a local www directory (
They are placed on the twiki by
This requires proper permissions.
3 Further reading
- Shuffle for manipulating source chunks.
- Text2Text? for documentation formatting.