2.4 How to organize your documents

Here is described how to create and organize any kind of documents. This includes man pages, info files, html-docs printed output and output of programs.

2.4.1 Snippets

Snippets are Texinfo files which are intended to be included into other Texinfo documents. They are building blocks of text.

So they do not include standard Texinfo header information. An example of a snippet is authors.snippet.texinfo which can look like this:

     The following persons have contributed to this package:
     
     @itemize
     
     @item
     @email{joerg@@siliconbrain.com, Joerg Kunze}
     
     @end itemize
     
     @c $siliconBrainRelease: 0.2.3 $
     @c $Id: siliconBrain.main.texinfo,v 1.55 2004/12/14 23:31:27 joerg Exp $
     @c $siliconBrainSaveStamp: 2004/12/14 22:37:42, Joerg Kunze$
     

The revision control information like $siliconBrainRelease is just held in comments. They are not inside @set commands so they don't overwrite settings done in the main document, which includes snippets.

Snippet files are named with the two level extension .snippet.texinfo. This is that make knows what to do with it. The extension .texinfo indicates that they are Texinfo files and that emacs should highlight them accordingly, and that they are processed with for example makefinfo. The part .snippets indicates make that they are snippets.

One common way to use snippets as the building blocks of your documents is just to include them in your main Texinfo files:

     @include authors.snippet.texinfo

In that way you avoid redundancies in your Texinfo documents. But what distinguishes snippets form other Texinfo included files is, that out of them, siliconBrain's makefile automatically generates a text and a html version into temporary/data. So in our example we will have the two files:

     distribution/data/authors.snippet.html
     distribution/data/authors.snippet.text

Using these files in your application program, by reading and displaying them, the application programs output can be based on the same Texinfo files. This further reduces the redundancy of document information.

So for example we have the line

     cat "distribution/data/longDescription.snippet.html"

inside the webify.bash to reuse the same documentation part in the creation of your projects web page.

If you will use the snippet not while making a package, but while you run it should write:

     cat "$siliconBrainPath/data/longDescription.snippet.html"

if you reuse document parts from siliconBrain or

     cat "$yourPackagePath/data/longDescription.snippet.html"

if its a part of your package.

There is the special case of standard snippets, which are used to create the capital files like AUTHORS. The capital files are created by copying the generated text version of the corresponding snippet into the projects root directory.

AUTHORS

Created from authors.snippet.texinfo. Here you should describe the authors, which have contributed to your package.

INSTALL

Created from install.snippet.texinfo. Here you find the description of how to install your package. Normally you can leave this file as it has been created by siliconBrain' makefile.

INTRODUCTION

Created from introduction.snippet.texinfo. Here you should put a short introduction into your package.

NEWS

Created from news.snippet.texinfo. Describe, what is new to your project.

README

Created from readme.snippet.texinfo. This file should be read first by someone, who is new to your package.

TODO

Created from todo.snippet.texinfo. Open issues in your package.

When you create a new project these snippets are automatically copied into your projects root directory from templates. You never should edit the capital files by your self (except RELEASE, which is not generated out of Texinfo snippets). Always edit the corresponding Texinfo snippet.

There are other snippets, which are copied into your project from templates:

longDescription.snippet.texinfo

This file contains a long (one paragraph) description of your package. This is included in the readme and other docs.

shortCopyingDoc.snippet.texinfo

This is a short version of the GNU Free Documentation License. This is included in a lot of docs, because all docs of a siliconBrain project should be published under that license.

shortDescription.snippet.texinfo

A one liner to describe your package. It is included in longDescription and many others. This can be used in the startup message of your programs as well.

standardFiles.snippet.texinfo.template

A list of the standard files in your distribution: the capital files. This file is included in readme and normally should not be changed.

All these files are also included in your main Texinfo document, which is used for printed output and as manual on your web site.

Using snippets thus guarantees, that the capital files (like README), your web pages, the printed manual and your programs output, contain the same information. And this with no redundancy and no double work.