Bug#271951: debian-installer-manual: please document how to typeset manual in PDF using free tools

[Joost van Baal]

Package: debian-installer-manual
Version: 20040801
Severity: wishlist
Tags: patch

Hi,

I've typeset the installer manual in PostScript and PDF, since I like to
read big documents like this one from paper.  This required some
hacking.  It'd be cool if a note on how to do this (like this bugreport)
was shipped with the sources.  Or perhaps you'd like to ship a PDF with
the .deb itself.  Anyway, this is what I did:

 [EMAIL PROTECTED]:/usr...0040801/doc/manual/build% ./buildone.sh i386 en

The buildfop.sh script needs the fop package, which is in contrib, since
it depends on a non-free java runtime environment.  OK, let's try to use
the free jade tool.

We have to hack the .xml file, since jade seems to be more picky on the
XML syntax.

[EMAIL PROTECTED]:/usr...0040801/doc/manual/build% sed \
 's/<para\/>/<\/para><para>/' install.en.profiled.xml > \
 install.en.profiled.dbx

also:

 sed 's/<entry\/>/<entry><\/entry>/'

And also some more manual hacking: some s/sect2/sect1/ and
s/sect3/sect2/ needs to be done, complete diff is attached.

Now we can run jade and friends on it:

 % jade -t tex -o install.en.profiled.jtex \
    /usr/share/sgml/declaration/xml.dcl install.en.profiled.dbx
 % jadetex install.en.profiled.jtex
 % jadetex install.en.profiled.jtex
 % dvips -f < install.en.profiled.dvi > install.en.profiled.ps

(Alternatively, one can run

 make -f /usr/share/caspar/mk/docbook.mk install.en.profiled.ps
 make -f /usr/share/caspar/mk/docbook.mk install.en.profiled.pdf

which uses some non-default .dsl files.  This needs the caspar package.)

Results are on http://mdcc.cx/~joostvb/debian-installer-manual-20040801/
.

Thanks, Bye,

Joost



--- install.en.profiled.xml     2004-09-16 10:59:21.000000000 +0200
+++ install.en.profiled.dbx     2004-09-16 12:15:11.000000000 +0200
@@ -853,8 +853,8 @@
 <row>
   <entry>Intel ia64-based</entry>
   <entry>ia64</entry>
-  <entry/>
-  <entry/>
+  <entry></entry>
+  <entry></entry>
 </row>
 
 <row>
@@ -8223,7 +8223,7 @@
 Installation Guide</link>.
 
 </para>
-<sect2 id="howto-preliminaries">
+<sect1 id="howto-preliminaries">
 <title>Preliminaries</title>
 <para>
 
@@ -8238,9 +8238,9 @@
 on the freenode network).
 
 </para>
- </sect2>
+ </sect1>
 
- <sect2 id="howto-getting-images">
+ <sect1 id="howto-getting-images">
 <title>Booting the installer</title>
 <para>
 
@@ -8269,7 +8269,7 @@
 get for each possible means of installation.
 
 </para>
-  <sect3 id="howto-getting-images-cdrom">
+  <sect2 id="howto-getting-images-cdrom">
 <title>CDROM</title>
 <para>
 
@@ -8290,9 +8290,9 @@
 
 
 </para>
-  </sect3>
+  </sect2>
   
-  <sect3 condition="supports-floppy-boot" id="howto-getting-images-floppy">
+  <sect2 condition="supports-floppy-boot" id="howto-getting-images-floppy">
 <title>floppy</title>
 <para>
 
@@ -8328,9 +8328,9 @@
 Since you'll have more than one floppy, it's a good idea to label them.
 
 </para>
-  </sect3>
+  </sect2>
   
-  <sect3 condition="bootable-usb" id="howto-getting-images-usb">
+  <sect2 condition="bootable-usb" id="howto-getting-images-usb">
 <title>USB memory stick</title>
 <para>
 
@@ -8363,9 +8363,9 @@
 and details, see <xref linkend="usb-boot"/>.
 
 </para>
-  </sect3>
+  </sect2>
   
-  <sect3 id="howto-getting-images-netboot">
+  <sect2 id="howto-getting-images-netboot">
 <title>Booting from network</title>
 <para>
        
@@ -8382,9 +8382,9 @@
 For detailed instructions, see <xref linkend="install-tftp"/>
 
 </para>
-  </sect3>
+  </sect2>
   
-  <sect3 id="howto-getting-images-hard-disk">
+  <sect2 id="howto-getting-images-hard-disk">
 <title>Booting from hard disk</title>
 <para>
 
@@ -8399,9 +8399,9 @@
 </phrase>
 
 </para>
-  </sect3>
- </sect2>
- <sect2 id="howto-installation">
+  </sect2>
+ </sect1>
+ <sect1 id="howto-installation">
 <title>Installation</title>
 <para>
 
@@ -8412,7 +8412,7 @@
 If you want a 2.6 kernel, type "linux26" at the boot: prompt.
 </phrase>
 
-<para/>
+</para><para>
 
 After a while you will be asked to select your language. Use the arrow keys
 to pick a language and press ENTER to continue. Next you'll be asked to
@@ -8420,30 +8420,30 @@
 language is spoken. If it's not on the short list, a list of all the
 countires in the world is available.
 
-<para/>
+</para><para>
 
 You may be asked to confirm your keyboard layout. Choose the default unless
 you know better.
 
-<para/>
+</para><para>
 
 Now sit back while debian-installer detects some of your hardware, and
 loads the rest of itself from CD, floppy, USB, etc.
 
-<para/>
+</para><para>
 
 Next the installer will try to detect your network hardware and set up
 networking by DHCP. If you are not on a network or do not have DHCP, you
 will be given the opportunity to configure the network manually.
 
-<para/>
+</para><para>
 
 Now it is time to partition your disks. First you will be given the
 opportunity to automatically partition either an entire drive, or free
 space on a drive. This is recommended for new users or anyone in a hurry,
 but if you do not want to autopartition, choose manual from the menu.
 
-<para/>
+</para><para>
 
 On the next screen you will see your partition table, how the partitions
 will be formatted, and where they will be mounted. Select a partition to
@@ -8453,12 +8453,12 @@
 partition on "/". <xref linkend="partitioning"/> has more information
 about partitioning.
 
-<para/>
+</para><para>
 
 Now <classname>debian-installer</classname> formats your partitions and starts to 
install the base system, 
 which can take a while. That is followed by installing a kernel.
 
-<para/>
+</para><para>
 
 The last step is to install a boot loader. If the installer detects
 other operating systems on your computer, it will add them to the boot menu
@@ -8468,7 +8468,7 @@
 given the opportiunity to override that choice and install it elsewhere.
 </phrase>
 
-<para/>
+</para><para>
 
 <classname>debian-installer</classname> will now tell you that the installation has
 finished. Remove the cdrom or other boot media and hit <keycap 
moreinfo="none">Enter</keycap>
@@ -8481,8 +8481,8 @@
 <xref linkend="d-i-intro"/>.
 
 </para>
- </sect2>
- <sect2 id="howto-installation-report">
+ </sect1>
+ <sect1 id="howto-installation-report">
 <title>Send us an installation report</title>
 <para>
 
@@ -8501,8 +8501,8 @@
 if the install completly fails, see <xref linkend="problem-report"/>.
 
 </para>
- </sect2>
- <sect2 id="howto-installation-finally">
+ </sect1>
+ <sect1 id="howto-installation-finally">
 <title>And finally..</title>
 <para>
 
@@ -8510,7 +8510,7 @@
 useful. You might want to read <xref linkend="post-install"/>.
 
 </para>
- </sect2>
+ </sect1>
 </appendix>
 
 <!-- retain these comments for translator revision tracking -->
@@ -9844,108 +9844,108 @@
 
 <row><entry>Bulgarian:</entry><entry>George Tchavdarov</entry></row>
 <row><entry>Catalan:</entry><entry>Jordi Mallach</entry></row>
-<row><entry/><entry>Antoni Bella P&#xE9;rez</entry></row>
-<row><entry/><entry>Ingrid C. Peir&#xF3;</entry></row>
-<row><entry/><entry>Lluis Vilanova</entry></row>
-<row><entry/><entry>Pau (aka pdl)</entry></row>
-<row><entry/><entry>Xavi Drudis Ferran</entry></row>
-<row><entry/><entry>Ivan Vilata i Balaguer</entry></row>
+<row><entry></entry><entry>Antoni Bella P&#xE9;rez</entry></row>
+<row><entry></entry><entry>Ingrid C. Peir&#xF3;</entry></row>
+<row><entry></entry><entry>Lluis Vilanova</entry></row>
+<row><entry></entry><entry>Pau (aka pdl)</entry></row>
+<row><entry></entry><entry>Xavi Drudis Ferran</entry></row>
+<row><entry></entry><entry>Ivan Vilata i Balaguer</entry></row>
 <row><entry>Chinese:</entry><entry>malix</entry></row>
-<row><entry/><entry>Chuan-kai Lin</entry></row>
+<row><entry></entry><entry>Chuan-kai Lin</entry></row>
 <row><entry>Croatian:</entry><entry>Matej Vela</entry></row>
-<row><entry/><entry>Josip Rodin</entry></row>
+<row><entry></entry><entry>Josip Rodin</entry></row>
 <row><entry>Czech:</entry><entry>Pavel Makovec</entry></row>
-<row><entry/><entry>Ji&#x159;&#xED; Ma&#x161;&#xED;k</entry></row>
-<row><entry/><entry>Vil&#xE9;m Vychodil</entry></row>
-<row><entry/><entry>Miroslav Ku&#x159;e</entry></row>
-<row><entry/><entry>Petr Van&#x11B;k</entry></row>
+<row><entry></entry><entry>Ji&#x159;&#xED; Ma&#x161;&#xED;k</entry></row>
+<row><entry></entry><entry>Vil&#xE9;m Vychodil</entry></row>
+<row><entry></entry><entry>Miroslav Ku&#x159;e</entry></row>
+<row><entry></entry><entry>Petr Van&#x11B;k</entry></row>
 <row><entry>Danish:</entry><entry>Claus Hindsgaul</entry></row>
 <row><entry>Dutch:</entry><entry>Luk Claes</entry></row>
-<row><entry/><entry>Bart Cornelis</entry></row>
-<row><entry/><entry>Frans Pop</entry></row>
-<row><entry/><entry>Wouter Verhelst</entry></row>
-<row><entry/><entry>Bas Zoetekouw</entry></row>
+<row><entry></entry><entry>Bart Cornelis</entry></row>
+<row><entry></entry><entry>Frans Pop</entry></row>
+<row><entry></entry><entry>Wouter Verhelst</entry></row>
+<row><entry></entry><entry>Bas Zoetekouw</entry></row>
 <row><entry>Esperanto:</entry><entry>Edmund Grimley Evans</entry></row>
 <row><entry>Finnish:</entry><entry>Tapio Lehtonen</entry></row>
-<row><entry/><entry>Antti-Juhani Kaijanaho</entry></row>
+<row><entry></entry><entry>Antti-Juhani Kaijanaho</entry></row>
 <row><entry>French:</entry><entry>Christophe Le Bars</entry></row>
-<row><entry/><entry>Vincent Renardias</entry></row>
-<row><entry/><entry>Eric Van Buggenhaut</entry></row>
-<row><entry/><entry>Martin Quinson</entry></row>
-<row><entry/><entry>Pierre Machard</entry></row>
+<row><entry></entry><entry>Vincent Renardias</entry></row>
+<row><entry></entry><entry>Eric Van Buggenhaut</entry></row>
+<row><entry></entry><entry>Martin Quinson</entry></row>
+<row><entry></entry><entry>Pierre Machard</entry></row>
 <row><entry>Galician:</entry><entry>Jacobo Tarrio</entry></row>
 <row><entry>German:</entry><entry>Hartmut Koptein</entry></row>
-<row><entry/><entry>Martin Schulze</entry></row>
-<row><entry/><entry>Philipp Stratmann</entry></row>
-<row><entry/><entry>Joerg Friedrich</entry></row>
-<row><entry/><entry>Gerd Bavendiek</entry></row>
-<row><entry/><entry>Peter Ganten</entry></row>
-<row><entry/><entry>Michael Bramer</entry></row>
-<row><entry/><entry>Torsten Landschoff</entry></row>
+<row><entry></entry><entry>Martin Schulze</entry></row>
+<row><entry></entry><entry>Philipp Stratmann</entry></row>
+<row><entry></entry><entry>Joerg Friedrich</entry></row>
+<row><entry></entry><entry>Gerd Bavendiek</entry></row>
+<row><entry></entry><entry>Peter Ganten</entry></row>
+<row><entry></entry><entry>Michael Bramer</entry></row>
+<row><entry></entry><entry>Torsten Landschoff</entry></row>
 <row><entry>Greek:</entry><entry>Konstantinos Margaritis</entry></row>
-<row><entry/><entry>George Papamichelakis</entry></row>
+<row><entry></entry><entry>George Papamichelakis</entry></row>
 <row><entry>Hungarian:</entry><entry>Gergely Risko</entry></row>
 <row><entry>Italian:</entry><entry>Michele Dalla Silvestra</entry></row>
-<row><entry/><entry>Paolo Didon&#xE8;</entry></row>
-<row><entry/><entry>Riccardo Fabris</entry></row>
-<row><entry/><entry>Giuseppe Sacco</entry></row>
+<row><entry></entry><entry>Paolo Didon&#xE8;</entry></row>
+<row><entry></entry><entry>Riccardo Fabris</entry></row>
+<row><entry></entry><entry>Giuseppe Sacco</entry></row>
 <row><entry>Japanese:</entry><entry>Yoshizumi Endo</entry></row>
-<row><entry/><entry>Atsushi Kamoshida</entry></row>
-<row><entry/><entry>Junichi Uekawa</entry></row>
-<row><entry/><entry>Tsutomu Saito</entry></row>
-<row><entry/><entry>NAKANO, Takeo</entry></row>
-<row><entry/><entry>KISE Hiroshi</entry></row>
-<row><entry/><entry>Mitsuru Oka</entry></row>
-<row><entry/><entry>NABETANI Hidenobu</entry></row>
-<row><entry/><entry>Masayuki Hatta</entry></row>
-<row><entry/><entry>Guangcheng Wen</entry></row>
-<row><entry/><entry>Nobuhiro IMAI</entry></row>
-<row><entry/><entry>Tomohiro KUBOTA</entry></row>
-<row><entry/><entry>KURASAWA Nozomu</entry></row>
-<row><entry/><entry>SUGIYAMA Tomoaki</entry></row>
-<row><entry/><entry>TAKEI Nobumitsu</entry></row>
+<row><entry></entry><entry>Atsushi Kamoshida</entry></row>
+<row><entry></entry><entry>Junichi Uekawa</entry></row>
+<row><entry></entry><entry>Tsutomu Saito</entry></row>
+<row><entry></entry><entry>NAKANO, Takeo</entry></row>
+<row><entry></entry><entry>KISE Hiroshi</entry></row>
+<row><entry></entry><entry>Mitsuru Oka</entry></row>
+<row><entry></entry><entry>NABETANI Hidenobu</entry></row>
+<row><entry></entry><entry>Masayuki Hatta</entry></row>
+<row><entry></entry><entry>Guangcheng Wen</entry></row>
+<row><entry></entry><entry>Nobuhiro IMAI</entry></row>
+<row><entry></entry><entry>Tomohiro KUBOTA</entry></row>
+<row><entry></entry><entry>KURASAWA Nozomu</entry></row>
+<row><entry></entry><entry>SUGIYAMA Tomoaki</entry></row>
+<row><entry></entry><entry>TAKEI Nobumitsu</entry></row>
 <row><entry>Polish:</entry><entry>Piotr Pogorzelski</entry></row>
-<row><entry/><entry>Marcin Owsiany</entry></row>
+<row><entry></entry><entry>Marcin Owsiany</entry></row>
 <row><entry>Portuguese:</entry><entry>Gleydson Mazioli da Silva</entry></row>
-<row><entry/><entry>Paulo Henrique B. Oliveira</entry></row>
-<row><entry/><entry>Andr&#xE9; Lu&#xED;s Lopes</entry></row>
-<row><entry/><entry>Luis Alberto Garcia Cipriano</entry></row>
-<row><entry/><entry>Paulo Rog&#xE9;rio Ormenese</entry></row>
-<row><entry/><entry>Marcio Roberto Teixeira</entry></row>
-<row><entry/><entry>Rafael Laboissiere</entry></row>
+<row><entry></entry><entry>Paulo Henrique B. Oliveira</entry></row>
+<row><entry></entry><entry>Andr&#xE9; Lu&#xED;s Lopes</entry></row>
+<row><entry></entry><entry>Luis Alberto Garcia Cipriano</entry></row>
+<row><entry></entry><entry>Paulo Rog&#xE9;rio Ormenese</entry></row>
+<row><entry></entry><entry>Marcio Roberto Teixeira</entry></row>
+<row><entry></entry><entry>Rafael Laboissiere</entry></row>
 <row><entry>Russian:</entry><entry>Mikhail Sobolev</entry></row>
-<row><entry/><entry>Alexey Vyskubov</entry></row>
-<row><entry/><entry>Aleksey Novodvorsky</entry></row>
-<row><entry/><entry>Peter Novodvorsky</entry></row>
-<row><entry/><entry>Paul Romanchenko</entry></row>
-<row><entry/><entry>Ilgiz Kalmetev</entry></row>
-<row><entry/><entry>Max V. Kosmach</entry></row>
+<row><entry></entry><entry>Alexey Vyskubov</entry></row>
+<row><entry></entry><entry>Aleksey Novodvorsky</entry></row>
+<row><entry></entry><entry>Peter Novodvorsky</entry></row>
+<row><entry></entry><entry>Paul Romanchenko</entry></row>
+<row><entry></entry><entry>Ilgiz Kalmetev</entry></row>
+<row><entry></entry><entry>Max V. Kosmach</entry></row>
 <row><entry>Slovak:</entry><entry>Miroslav Va&#x161;ko</entry></row>
 <row><entry>Spanish:</entry><entry>Enrique Zanardi</entry></row>
-<row><entry/><entry>Fernando Herrera</entry></row>
-<row><entry/><entry>Sergio G&#xF3;mez Bachiller</entry></row>
-<row><entry/><entry>Gonzalo G. Agull&#xF3;</entry></row>
-<row><entry/><entry>Ignacio J. Alonso</entry></row>
-<row><entry/><entry>Tinguaro Barreno</entry></row>
-<row><entry/><entry>Pedro Gracia</entry></row>
-<row><entry/><entry>Angel David Rancel Mendoza</entry></row>
-<row><entry/><entry>Javier Fern&#xE1;ndez-Sanguino</entry></row>
-<row><entry/><entry>David Martinez</entry></row>
-<row><entry/><entry>Ricardo J. C&#xE1;rdenes</entry></row>
-<row><entry/><entry>Jose Carlos Garc&#xED;a</entry></row>
-<row><entry/><entry>Javier Carranza</entry></row>
-<row><entry/><entry>Miguel A. Ar&#xE9;valo</entry></row>
-<row><entry/><entry>Ferm&#xED;n Garc&#xED;a-Herreros</entry></row>
-<row><entry/><entry>Javier Linares</entry></row>
-<row><entry/><entry>Manolo Romero</entry></row>
-<row><entry/><entry>Gabriel Rodr&#xED;guez</entry></row>
-<row><entry/><entry>Santiago Vila</entry></row>
-<row><entry/><entry>Ricardo C&#xE1;rdenes</entry></row>
-<row><entry/><entry>David Moreno Garza</entry></row>
-<row><entry/><entry>Rudy Godoy</entry></row>
-<row><entry/><entry>Bruno Barrera</entry></row>
+<row><entry></entry><entry>Fernando Herrera</entry></row>
+<row><entry></entry><entry>Sergio G&#xF3;mez Bachiller</entry></row>
+<row><entry></entry><entry>Gonzalo G. Agull&#xF3;</entry></row>
+<row><entry></entry><entry>Ignacio J. Alonso</entry></row>
+<row><entry></entry><entry>Tinguaro Barreno</entry></row>
+<row><entry></entry><entry>Pedro Gracia</entry></row>
+<row><entry></entry><entry>Angel David Rancel Mendoza</entry></row>
+<row><entry></entry><entry>Javier Fern&#xE1;ndez-Sanguino</entry></row>
+<row><entry></entry><entry>David Martinez</entry></row>
+<row><entry></entry><entry>Ricardo J. C&#xE1;rdenes</entry></row>
+<row><entry></entry><entry>Jose Carlos Garc&#xED;a</entry></row>
+<row><entry></entry><entry>Javier Carranza</entry></row>
+<row><entry></entry><entry>Miguel A. Ar&#xE9;valo</entry></row>
+<row><entry></entry><entry>Ferm&#xED;n Garc&#xED;a-Herreros</entry></row>
+<row><entry></entry><entry>Javier Linares</entry></row>
+<row><entry></entry><entry>Manolo Romero</entry></row>
+<row><entry></entry><entry>Gabriel Rodr&#xED;guez</entry></row>
+<row><entry></entry><entry>Santiago Vila</entry></row>
+<row><entry></entry><entry>Ricardo C&#xE1;rdenes</entry></row>
+<row><entry></entry><entry>David Moreno Garza</entry></row>
+<row><entry></entry><entry>Rudy Godoy</entry></row>
+<row><entry></entry><entry>Bruno Barrera</entry></row>
 <row><entry>Swedish:</entry><entry>Nils-Erik Svang&#xE5;rd</entry></row>
-<row><entry/><entry>Peter Karlsson</entry></row>
+<row><entry></entry><entry>Peter Karlsson</entry></row>
 
 </tbody></tgroup></table>