There are a few manners and rules that should be followed in writing Momonga Linux documents as mentioned below.
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.
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 wil be created.
It stands for article 1 section ??.
??.html
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.
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 <, 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:
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.
An entry definition like "&svnsaba; -> svn.momonga-linux.org" can easily modified to update when your svn server for web contents is moved.
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.
Currently under discussion.
Finalized decision will be written here. :)
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