6. Momonga Linux document manners and rules

There are a few manners and rules that should be followed in writing Momonga Linux documents as mentioned below.

6.1. Root element of document

Considering the amount of documents placed on Momonga Linux, we assume "article" to be used for root element of a document.

docbook-style-xsl style sheet package is DocBook's a generic style sheet so it should be ok to use [4] but we haven't tried it on anything other than article.

Also the process to create changelog.html with docbook.xsl driver is relying on article. Somebody please write up a cool code for this.

6.2. Names of files that are linked from index.html.

Among the style sheets used for Momonga Linux documents,docbook.xsl is set to produce individual html files for each <sect1>. In this case, a file name is created with an id character name of each <sect1>. For example, a section with the following

          <sect1 id="kakikata">
will be created as kakikata.html.

If a section has no id character is specified, ar01s??.html wil be created. It stands for article 1 section ??.

With this manner, the file name would change depending on the order of the section in the article. If this section needs to be linked from other web site, add id character to have a fixed file name for the link.

However, avoid using "changelog" for id character since a style sheet in docbook.xsl is set to create changelog.html from the contents of <revhistory> section.

The same goes for anchors to <sect2>. If it needs to be linked from other web site, put some unique id character.

6.3. Use of Entry Definition

Momonga Linux documents use entry definition for frequently appearing words and expressions in the document. In the actual documents, the references from the definition is written.

This may sound a bit hard to understand but in short, it means to define something like &lt;, often seen in html, and use it.

For example, we write

        definitions of frequently appearing expressions in the
        &molong; documents.
or something similar.

The reasons behind doing this way are:

Prevention of typographical errors

Definitions for "&molong; -> Momonga Linux" can avoid an error too common among the "Momomga Linux".

Also if there is a mistake like &morong; which is not defined, xml parser may let you know that there is an error.

Easy to change definition reference

An entry definition like "&svnsaba; -> svn.momonga-linux.org" can easily modified to update when your svn server for web contents is moved.

Easy to make

Using a definition like "&dora; -> Shingo Akagaki <dorami@bu.iij4u.or.jp>" can save you a lot of typing. It can also contribute to less typograhical errors.

And things like rpm changelog go wild ... It amazes me that sometimes you can't even type your own name right ...

The entry definition file for Momonga Linux document is docs/momonga.ent.

        <!ENTITY molong       "Momonga Linux">
        <!ENTITY moshort      "Momonga">
Definitions are made in this way so you can add up when necessary.

6.4. Format for Revision History

Currently under discussion.

       Finalized decision will be written here. :)

6.5. xmllint

If there is a syntax error in your document, updating the actual contents of http://www.momonga-linux.org/ may be stopped, or OmoiKondara may be halted from the error when your document is being created in Momonga-Docs package(as planned). To avoid such a situation, perform as below to check locally before you commit to svn.

         $ xmllint --noout --valid Hoge-HOWTO.xml

[4] Perhaps "books"?