5. Guidelines For IPCop Documentation

The Linux Documentation Project's Author Guide is as good a place as any to start. Please follow its guidelines.

We will be using CVS to maintain our documentation. The longer lines are, the harder it is to figure out what's changed. Therefore, try to keep the line length to around 70 characters or less. Also, try to start sentences on a new line.

Try to indent the source so that it's easier to follow the structure of the document. Do not use tab characters to indent. Other folk's editors may not be set up with the same tabs. In a very few cases, this indentation will not work as you might hope. For example, content inside a few elements is declared as “ verbatim ” environments. This means that in these areas white space and line breaks are significant. Thus, text within elements like <programlisting> cannot be indented to indicate their XML nesting level.

Each document should contain a copyright notice, with the author(s) as holder(s), for legal purposes in the European Union. Include a reference to the GNU Free Documentation License or FDL, also. This license states that the entire license itself should be included in any documentation licensed under it. A separate file, fdlappendix.xml, is in the IPCopDoc project and can be included as an entity.

Due to its length, you probably don't want to include the FDL in shorter documents, but you should still reference the license.

Even though all the information, such as copyright, may not appear in some or all formats of output, putting it into the source will assure that your document is copyrighted properly.

The location of illustrations on your machine will not have the same path as when the HTML resides at the IPCop web site. Please define DocBook entities to centralize specification of the paths to the files needed by your manual.

As stated in the Linux Documentation Project's Author Guide, please add an id= attribute to all major divisions of your work. Make sure that the topmost element of your work has an id="index" attribute, i.e. <book id="index"> The LDP XSL files insure that chunk HTML files have the names specified in their id= attributes. The standard starting page for browsers when a directory is referenced is index.html. Using fixed names allows other documents to directly link into yours. Without the id= attributes, random names will be chosen.