1.10 Usage

All GNU philosophy essays are promptly available for inclusion in another package’s documentation. To exemplify how to do it, consider the following hypothetical situation: your target documentation main file is gnu-3.0/doc/manual.texi and you want to include the original, English version, of The GNU Project essay. Supposing GNU philosophy source tree is under philosophy directory, you can find the correspondent essay file in philosophy/src/essays directory named as the-gnu-project.texi. As a general rule, for an essay, whose title in lowercase, with all non-alphanumeric and non-blank characters removed, all blank characters collapsed to a single one, and then transliterated to ‘-’, is essay-title, one can find the correspondent Texinfo source as philosophy/src/essays/essay-title.

After locating the desired essay file, the next step is to copy it from the GNU philosophy source tree to the desired target main documentation file directory, in this illustration case the following command suffices:

cp philosophy/src/essays/the-gnu-project.texi gnu-3.0/doc

There is another required file, which is included by every essay file, namely essay-header.texi. That file contains all aggregate type specific settings, the definition of several Texinfo helper macros, huge conditional processing, among other things, whose aim is to make essay’s Texinfo source perfectly portable between the various use cases, therefore not requiring the modification of a single line of code in the essay file properly. You must copy it also:

cp philosophy/src/essay-header.texi gnu-3.0/doc

Now you are just a couple of changes in your documentation main file from achieving the desired goal. For that end, edit the file gnu-3.0/doc/manual.texi and put somewhere inside its header the Texinfo command:

@set GNUphiThird

That will inform essay-header.texi about our specific use case, and thence make the the-gnu-project.texi essay file to behave properly when included. Now, wherever you want an entry for the essay in the documentation main file, you can put an include for the essay file, like:

@node The GNU Project
@appendix The GNU Project
@include the-gnu-project.texi

If the documentation is supposed to generate also Info files, do not forget to put a menu entry for it:

@menu
[...]
GNU philosophy:
* The GNU Project::
[...]
@end menu

You are done. Simple isn’t it?