How To Write Ehc Documentation

1 Introduction

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 (EHCHOME/text).
• 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 pdf or twiki.
• The documentation files in the documentation directory (EHCHOME/doc) are then published or used otherwise.

2 Steps

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 chunks. Of the various makefiles for producing text the makefile for text sources and variants (EHCHOME/text/files-variants.mk) must include a definition for a new variant. A new variant is added by:

1. Finding an unused number, say 88, in the comment above variable TEXT_SHUFFLE_ORDER, updating the comment with info about variant 88.
2. Adding an order dependency on variant 39 (the base for documentation) in variable TEXT_SHUFFLE_ORDER:

   TEXT_SHUFFLE_ORDER  += \
           ... \
           39 < 88, \
           ...
   

The new documentation must be given a name which can be used for making and publishing the documentation:

1. Find an unused name, say my-doc, and add it to the list in variable TEXT_DOC_VARIANTS.
2. 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 text-variant-<chosen-name>:

   text-variant-my-doc:
      $(MAKE) \
        TEXT_SHUFFLE_VARIANT=88 \
        text-variant-dflt-doc
   

Additional parameters can be passed to the recursive call to make, for example:

• TEXT_CFG_SHUFFLE_INCLUDES_CHUNK_SRC (default: empty), for specifying that all sources of EHC must be used by shuffle for extracting chunks. For example, the technical documentation has the following makefile definition:

  text-variant-ehc-technical-doc:
     $(MAKE) TEXT_CFG_SHUFFLE_INCLUDES_CHUNK_SRC=yes \
       TEXT_SHUFFLE_VARIANT=42 \
       text-variant-dflt-doc
  

• TEXT_CFG_FIGS_INCLUDES_DOT_SRC (default: yes), for specifying that figures generated by dot should be available for use.
• TEXT_CFG_FIGS_INCLUDES_XFIG_SRC (default: yes), for specifying that figures drawn with xfig should be available for use.

2.2 Adapt toplevel documentation

All documentation and papers share a common toplevel text file (EHCHOME/text/main.cltex). 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:

1. 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:

   %%[88 doclatex
   \title{My stuff}
   \author{Me}
   %%]
   

2. Content. Again search for %%[41 and copy it:

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %% My doc
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   
   %%[88 doclatex
   some content here ...
   %%]
   

2.3 Create content

Content is added according to the type of a chunk, as defined by Text2Text? . At least type doclatex is supported, a subset of LaTeX for documentation purposes. See Text2Text? for more information. We have used and will use chunk/text type doclatex for the examples in this document.

By convention the real content is placed in a text source for My documentation (EHCHOME/text/ToolDocMy.cltex) to which then is referred by name from the toplevel text file (EHCHOME/text/main.cltex). The name of the My source file (EHCHOME/text/ToolDocMy.cltex) assumes the documentation is about a tool, hence the prefix ToolDoc. General topics use prefix Topic, slides use Slides. This convention is not enforced, so choose a sensible prefix.

The following must be done:

1. 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.
2. Add content in the documentation source file (EHCHOME/text/ToolDocMy.cltex), for example by:

   %%[intro doclatex
   My is ...
   %%]
   
   %%[content doclatex
   ...
   %%]
   

   The file defines named chunks intro and content of type doclatex. These are included in the toplevel text file (EHCHOME/text/main.cltex) by referring to their names:

   %%[88 doclatex
   \section{Introduction}
   %%@ToolDocMy.intro
   
   \section{My}
   %%@ToolDocMy.content
   %%]
   

   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:

make doc/my-doc.pdf

It respectively runs the defined chunks through Shuffle, 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 (EHCHOME/www) by

make www

They are placed on the twiki by

make www-sync

This requires proper permissions.

3 Further reading

See also

• Shuffle for manipulating source chunks.
• Text2Text? for documentation formatting.