Search:

Exporting to docbook is of primary interest for the HOWTOs, because this allows the use of the old, very well tuned, toolchains for HOWTO publishing of the LDP. see LDP_data_flow

MoinMoin docbook export

Exporting

This should be done only by the Author or a seasoned LDP member and after writing to the discussion list for review. In the easier case this is:

• edit the HOWTO to remove the admonitions if you don't want them in the final document, check if the licence is included (you also can do this on the xml file);

• use the Action "Render as Docbook" to save the new source file. use the "xml" extension to name the file. Use the very exact file name you want the HOWTO to have in the LDP collection. If for any reason you change the name from an old one, it should be useful:

• to mention that in the submission mail and say if the old one have to be kept or removed;
• insert a note in the HOWTO (Revision note?) to explain why the name changed;
• submit the XML file through the submit LDP mailing list;
• restore the HOWTO wiki page to have back the admonitions. Add one or a remark to flag the submission;
• some days after check the LDP site to see if all is nice.

problem: '''`''' (used to quote) is translated to "code" in docbook and the LDP script don't like it. In html translation the result is this text in red and some spacing problems.

Managing Images

Images are not converted. HOWTOs with images are stored in the CVS in a directory with the same name as the HOWTO. The images can be stored at the same level as the HOWTO (usually if there are few of them), or in a subdirectory named "images" if there are many. The author chooses.

The author can save the images in this folder before uploading them to the wiki, but if an other people do the conversion, he have to first download all the images from the attachments page to have them at hand.

In this case, it's better to submit the HOWTO through CVS or to send an archive to the submit list. If the images are big, the archive have to be uploaded somewhere, letterboxes are not made to receive multi megabytes mails.

Manual Editing

Moin docbook export works pretty well, but some manual editing is necessary to have a good xml document for LDP use. We can do this for you, simply ask to have your HOWTO published and give us the Wiki link.

"Kate" is very good to edit the xml file. Better use tidy first, however.

Using "tidy" to pretty print the xml code can make life easier (but verify if this don't kill the code);

tidy -xml -i -o test2-ti.xml test2.xml

For example.

• The exported DTD is DTD DocBook XML V4.4# version, the ibiblio one is only 4.2. so we have to change (twice, in the beginning of the file) 4.4 to 4.2. This can be by modifying the formatter, so may be this is no more a problem (see below).

• The images have to be attached to the xml document in a folder "images", so the absolute link given by the formatter have to be changed to "images/". As all the attached images have the same initial address, a search/replace with any editor do easily the job.

• You may think that the MoinMoin revision history is ugly and ask to remove it. This is done by removing the <revhistory>...</revhistory> part at the beginning of the xml document. However, if you want to do so, you will have to add at least one revision history by hand, necessary to LDP scripts.

• The admonition used in the wiki don't fit in the static HOWTO, so one have to remove the <caution>...</caution> part in the beginning of the doc

• remove also the <section><title>Discussion Page Content if any</title></section> part.

• Do not remove the DTD line and the HOWTO title line on the very beginning.

• we need some way to add a tag "author" (needed for LDP scripts).

Adding the Author tag

<author>
      <firstname>Your Given Name</firstname>
      <surname>Your Family Name (Surname)</surname>
      <authorblurb>
        <para>A short sentence about who you are.</para>
      </authorblurb>
      <affiliation>
<!-- The name of your organization is optional. -->        <orgname>
          <ulink url="http://www.URL.com" >company name</ulink>
        </orgname>
<!-- A valid email is required. You may add a spam blocker, or get a Yahoo/Gmail/etc account. -->        <address>
          <email>youremail@domain.NOSPAM.org</email>
        </address>
      </affiliation>
    </author>

Can be added at the top of the <articleinfo> first tag. Of course you need to change what is meaning full for You.

Trying the result

On our servers we have special scripts, but they are difficult to use elsewhere. At home, you can use "xmlto" to get a result. The syntax is very simple:

xmlto html documentname or xmlto pdf documentname

and you should find it in any good distribution.

Editing the formatter

On nov 12, 2008, I (jdd) edited the formatter script to fix this problem (replaced twice 4.4 by 4.2).

The file is in moin@reggae:~$/MoinMoin/formatter/text_docbook.py. I have kept a backup in the underlying _test folder. It will probably be necessary to do it again after updates. see the source.

However, present (nov 12, 2008) ibiblio configuration don't allow for text exporting (no w3m available), but we can manage this manually.

HOWTO Name

The docbook file must have the very same name as the previous HOWTO (if any) in the LDP collection, else the HOWTO will be duplicated.

Allowed tags

We still have to list the Moin tags that are correctly translated. Right now, jade (the docbook processor) gives an un-understood "code error", but formats the HOWTO nicely.