Howto Style

Philippe Martin

  feloy@free.fr

v0.4, 18 Jun 2000

Revision History
Revision v0.418 Jun 2000Revised by: pm
Beginning of classification of DocBook elements
Revision History
Revision v0.218 Jun 2000Revised by: pm
Added main body plan and copyright

This article gives to the author of a Linux HOWTO some style rules, for readers to easily find information in, and computer programs to correctly process, index and search.


Table of Contents
Document type and general structure
Header structure
Main Body
Introduction
Function and Command Synopsis
Function Synopsis
Command Synopsis
Keyboard, mouse and GUI related elements
Keyboard and mouse
Graphical User Interface
Marking words and short phrases
Special paragraphs
Index

Document type and general structure

The document format for the sources of a Linux HOWTO is Docbook, version 3.1, and the document type is article. Here is the declaration, to insert at the very beginning of the document source:
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

The article begins with an article header, which includes the title, authors, publication date, revision history and abstract of the document. This article header is followed by the body of your document, composed of a hierarchy of sections. The document then ends with an index.

Note: The processed document can contain a table of contents after the article header and before the body of the document, but you do not need to take care of it, as it will automatically be added.

Example 1. Document general structure

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity index SYSTEM "indice.sgml">
]>

<article>
    
    <artheader>
	<title></title>
	
	<author></author>
	<author></author>
	
	<pubdate></pubdate>
	
	<revhistory></revhistory>
	
	<abstract></abstract>
    </artheader>
    
    <sect1>
	<sect2>
	    <sect3></sect3>
	    <sect3></sect3>
	</sect2>
	<sect2></sect2>
    </sect1>  
    <sect1></sect1>
    <sect1>
	<sect2></sect2>
    </sect1>
        
    &index;
    
</article>

Note: Because the index contents is generated by an external program, Example 1 defines the entity index, which is included at the end of the document with &index;.