[PLUTO-ildp] Potrebbe essere un aiuto per la User's Guide ... :-))

[Hugh Hartmann]

Un saluto "collaborativo" si estende a tutti i partecipanti alla lista 
... :-)

Ho pensato di fare cosa gradita a Giulio allegando a questa mia mail le 
istruzioni sulla conversione di file gsml di debiandoc in file xml di 
Docbook, cosi da rende la guida Debian più .. moderna ... :-))

Riporto qui, di seguito le istruzioni relative ... :-)


DebianDoc-SGML Manual
Appendix B - Conversion to XML

Now debiandoc-sgml package offers conversion to Docbook XML format for 
its user to smoothly migrate to the newer well maintained tool set 
called Docbook XML.

This appendix was written by Osamu Aoki (GPL2) in 2005.

B.1 Basic conversion method

No particular preparation of debiandoc-sgml SGML source is needed to use 
the conversion tool debiandoc2xml . See debiandoc2xml(1).

To make a single XML file from valid debiandoc-sgml source, issue the 
following commands:

      $ cd path/to/sgml-source-tree/
      $ debiandoc2xml -1 foo.sgml
      $ cd foo.xml/
      $ mv index.xml foo.xml

The generated XML file is named as index.xml and let's manually rename 
as foo.xml for this time.

B.2 Advanced conversion methods

In order to make generated file manageable, you may want to have them 
split into separate files for each chapter and preserve external ENTITY 
definitions as separate file. They are quite easy.
B.2.1 Split XML file output

When issuing debiandoc2xml command, just issue it without -1 option in 
the above example. You get XML files with file names matching id values 
of chapt tags. The top page is index.xml and it will contain file 
inclusion directions.

B.2.2 Preserving external ENTITY definitions

Some SGML sources use external file to manage common information across 
the documentation source and maintain good coherence. Creating this 
ENTITY definitions in a separate file named default.ent is common 
practice. It contains entries such as:

      <!ENTITY debianhome     "http://www.debian.org/">

You probably want to preserve these remote definition after XML 
conversion. Following describes how to do this.

In order to simplify this conversion, you need to simplify default.ent 
by removing definition for conditional switching such as:

      <!ENTITY % q-ref   "IGNORE">

and

      <![%lang-fr;[
      <!ENTITY full-title "Guide de référence pour Debian">
      <!ENTITY p-debian-reference "debian-reference-fr">
      ]]>

Then, you tweak default.ent file (assuming files are normally formatted) 
as follows:

      $ mv default.ent default.ent.orig
      $ egrep "<\![[:space:]]*ENTITY[[:SPACE:]]+" <default.ent.orig | \
        perl -p -e \
           's/<\!\s*ENTITY\s+([-\w]+)\s.*$/<\!ENTITY $1 
"@#@#@#$1#@#@#@">/' \
           > default.ent

This will create alternative entries, which generate reference markers 
such as:

      <!ENTITY debianhome "@#@#@#debianhome#@#@#@">

Then use this alternative default.ent file for XML conversion. (You may 
still modify this to include missing required definitions such as lines 
containing "%" in the original default.ent file.)

For each generated XML files with this alternative default.ent file, you 
recover remote references by converting markers with:

      $ for i in *.xml ; do \
        perl -p -i -e 's/@#@#@#$([\w]+)#@#@#@/\&$1;/g' $i ; \
        done

You need to add specification of including original default.ent in the 
header area of foo.xml XML file at the top again as:

      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [

      <!ENTITY % default  SYSTEM "default.ent">  %default;

      <!-- more lines here -->

      ]>

B.3 Testing generated XML file(s)

You can test the generated XML file with Emacs and psgml, or nsgmls:

      $ nsgmls -s /usr/share/sgml/declaration/xml.decl foo.xml

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 
] [ A ] [ B ] [ next ]

DebianDoc-SGML Manual
23 June 2006

Ardo van Rangelrooij ardo a debian.org
Ian Jackson ijackson a gnu.ai.mit.edu

Ecco, così potremmo disporre anche della guida in formato xml. Sto già 
pensando di trasformarla anche in LinuxDoc, così, per completezza ... :-))

Au Revoire
Hugh Hartmann