LDP DocBook

From Gentoo Wiki
Jump to:navigation Jump to:search

LDP DocBook

The Linux Documentation Project utilizes DocBook (ie. SGML) for their HowTo's.

There's already documentation on how to use the DocBook tools for creating the SGML files. There's one problem, a default install of Gentoo DocBook tools do not install a few required packages. Without installing these packages, users will be presented with many errors during conversion. Additionally, most on the LDP mailing list might not understand these errors as they're using other Linux Distributions, Distributions likely having meta packages for automatically setting up their environment.

An example initialerror, followed by 200+ stylesheet errors.

Cannot generate system identifier for public text "-//OASIS//DTD DocBook V4.1//EN"

Install Required Additional Packages

root #emerge -pv app-text/docbook-sgml-utils

This should also pull in these additional packages. If for some reason after installing docbook-sgml-utils you still do not have a functioning LDP DocBook utilities or incanatations, ensure the following packages currently pulled in are not being omitted:

[ebuild  NS    ] app-text/docbook-sgml-dtd-4.1-r3:4.1 [3.0-r3:3.0, 3.1-r3:3.1, 4.4:4.4] 56 kB
[ebuild  NS    ] app-text/docbook-sgml-dtd-4.0-r3:4.0 [3.0-r3:3.0, 3.1-r3:3.1, 4.4:4.4] 55 kB
[ebuild  N     ] app-text/docbook-xml-simple-dtd-  35 kB
[ebuild  N     ] dev-perl/SGMLSpm-1.03-r6  92 kB
[ebuild  N     ] app-text/docbook-xml-simple-dtd-1.0-r1:1.0  31 kB
[ebuild  N     ] app-text/docbook-sgml-utils-0.6.14-r1  USE="-jadetex" 123 kB

Verify Utilities for LDP Documentation

You should now be able to perform something of the following, with very few to no errors displayed within the console.

Make sure you have the ldp.dsl and any example programs included within the documentation extracted within the current folder!

This will convert SGML (ie. DocBook) to HTML

user $openjade -t html -d ./ldp.dsl\#html NCURSES-Programming-HOWTO.sgml

This will convert SGML (ie. DocBook) to XML

user $osx NCURSES-Programming-HOWTO.sgml > NCURSES-Programming-HOWTO.xml

Importing Tex files into Lyx

The following might be necessary to enable importing Tex into Lyx.

root #USE="jadetex" emerge -q app-text/sgmltools-lite