7. Adding a new document

Let's use Hoge-HOWTO as our sample here.

7.1. Preparing a storing location

Create a directory in the same name as the document under docs. Then do

          $ svn add new directory
to put it under the control of svn.

Then do svn commit as required.

7.2. Preparing source

In the directory you prepared at Section 7.1, “Preparing a storing location”, create an xml file in the same name as the directory name. [5]

Perhaps in creating this xml file mere copying one from another document directory might be a quick fix but let me write some rules to apply at the beginning of the file.

         <?xml version="1.0" encoding="EUC-JP"?>1
         <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"2
         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [3
         <!ENTITY % kent SYSTEM "../../momonga.ent">4
         <article id="index" lang="ja">6

A declaration that this file is an xml file. Xml has UTF-8 as default encoding. When another encoding is used, it should be declared as well.


A declaration to use XML DocBook DTD Version 4.1.2.


URL where DTD is actually located. This is mandatory since it is not DocBook sgml.


Reading in momonga.ent file.


Take this as a declaration to use references defined in momonga.ent file.


This is an root element of this document,article. From its id character the output file would be index.html.

Since it is in Japanese, lang character is set as ja. As a result of this, output html files would have ja as language type, would be encoded in EUC-JP, and have "Table of Contents" translated to the appropriate term in the language.

7.3. Preparing a omf file

Omf stands for Open Source Metadate Framework. For details, refer to metalab.

Create as docs/Hoge-HOWTO/C/Hoge-HOWTO-C.omf. Its contents should be

     <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
     <format mime="text/xml"/>
     <identifier url="Hoge-HOWTO.xml"/>
     <language code="C"/>
Something like that.

7.4. Adding Makefile.am

In docs/Hoge-HOWTO/Makefile.am, list up directories specific to available languages like below:

       SUBDIRS = C ja

In docs/Hoge-HOWTO/C/Makefile.am, it should have something like the following:

       docname = Hoge-HOWTO
       lang = en
       omffile = Hoge-HOWTO-C.omf
       xml_ents =
        include $(top_srcdir)/xmldocs.make
       dist-hook: app-dist-hook
       figs = \
       figures/hoge1.jpg \

7.5. Executing checknew.rb

Next go to docs and do

     ruby checknew.rb
Then an entry for Hoge-HOWTO is added in docs/configure.in and docs/Makefile.am.

7.6. Executing make

In docs do

     $ ./autogen.sh
     $ make
to sythesize html and txt under docs/Hoge-HOWTO/ja. If you confirm that there has not been any errors doing make then do svn commit.

[5] I know that there is a subtle discrepancy between Section 7.1, “Preparing a storing location” and Section 7.2, “Preparing source” but hope readers can pick up what we mean ...