# *Hereinafter*'s Documentation Scheme

To keep track of all of the documentation for this package, a somewhat complex
scheme of literate programming is used in the source code. This file explains
that scheme.

## Generating the User Manual

The user manual is generated by calling `make manual` (or `make` with no
arguments as it is the default recipe). This first compiles `hicite.ins` with a
flag indicating that the manual source code is to be constructed. That generated
source file is then compiled into a PDF document.

Compiling the manual and other documentation requires the fonts Libertinus
Serif, Source Sans 3, and Source Code Pro. These are all freely available.

## Individual Module Documentation

In addition to the user manual, each source code module (in the `src` directory)
can be individually compiled into its own documentation. The module
documentation files contain more implementation details in a literate
programming style.

To compile the documentation for a particular module file `src/[module].dtx`,
run `make doc/[module].pdf`. Alternately, run `make doc` to regenerate all of
the module documentation.

## File Structure and Conventions

### Background: Doc and Docstrip

(This section is here mostly to refresh the package author's own memory.)

This documentation uses the LaTeX *doc* and *docstrip* utilities for separating
the documentation from code. Relevant information on those programs may be found
here:

- [Doc](http://mirrors.ctan.org/macros/latex/base/doc.pdf)
- [Ltxdoc class](https://mirrors.ctan.org/macros/latex/base/ltxdoc.pdf)
- [Docstrip](https://mirrors.ctan.org/tex-archive/macros/latex/base/docstrip.pdf)
- [Tutorial](https://tug.org/TUGboat/tb29-2/tb92pakin.pdf) on writing package
  files

Briefly, the *doc* tool compiles `.dtx` files as LaTeX documents, ignoring
leading comment markers. The *docstrip* tool removes commented lines, and
furthermore permits conditional output: Code between flags like `%<*flag>` and
`%</flag>` will be ignored by *docstrip* unless the tool is told to keep
`flag` code. *Docstrip* calls these flags "guards," and this package uses guards
extensively.


### Source Code File Structure

Files use the `doc` and `docstrip` tools for compilation, and follow the
conventions laid out for those programs. They further follow several
conventions particular to this documentation.

First, two guards are used: `doc` and `package`. Any content meant for the user
documentation should be bracketed with `doc`, and any source code and
implementation comments are surrounded by `package`. Thus, instructions of
general use to package users should go into `doc` sections, while explanations
of internal implementation details should be comments in `package` sections.

Second, a common preamble is included in all module files:
```tex
%%
%% \iffalse filename: [module].dtx \fi
%%
%<*doc>
\input driver
\thisis{[module]}{[Section Heading for Module]}
```
The meta-comment is just helpful for identifying different files. More important
are the last three lines. The file `driver.tex` will define the `\thisis`
command to produce either a section heading when the file is compiled as part of
user manual, and a document title when compiled as a standalone
documentaiton file. Since these lines are within a `%<*doc>` guard, they will be
ignored for producing the package code file.


### Additional Files

In addition to the module `.dtx` files, there are a few other files to note:

- `intro.dtx`: Introductory text for the user manual and the package code
- `conclusion.dtx`: Conclusory text (adds `\end{document}` to files)
- `parts.dtx`: Headings for the parts of the user manual
- `helpers/`: Contains macros other definitions used in the documentation