LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

updated

This commit is contained in:
gferg 2000-05-19 14:08:50 +00:00
parent ebd2297948
commit 618e78c2cf
1 changed files with 116 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
LDP/howto/docbook/HOWTO-HOWTO.sgml
View File

@ -10,10 +10,10 @@
HOWTO-HOWTO
</title>
<date>
v1.6 3 May, 2000
v1.8 17 May, 2000
</date>
<author>
<firstname>Mark</firstname><surname>Komarinski</surname>
<firstname>Mark</firstname> <surname>Komarinski</surname>
</author>
<abstract>
<para>
@ -54,22 +54,27 @@
Version History
</title>
<para>
v1.6 (May 3, 2000)
v1.8 (May 17, 2000)
</para>
<itemizedlist>
<listitem>
<para>
Updated tools section thanks to Greg Ferguson
Corrected errors in LinuxDoc section that didn't render properly.
</para>
</listitem>
<listitem>
<para>
No more updates on LinuxDoc documentation. Sorry.
Added content about Cygnus tools - thanks to Dan Scott
</para>
</listitem>
<listitem>
<para>
More LyX documentation
Added OpenJade information and link
</para>
</listitem>
<listitem>
<para>
More DocBook rendering information - thanks to Greg Ferguson
</para>
</listitem>
</itemizedlist>
@ -141,7 +146,7 @@
Why SGML instead of HTML or other formats?
</title>
<para>
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The sgmltools package also lets you export (I'll call it render from here on) SGML to LaTeX, info, text, HTML, and RTF. From these basic formats, you can then create other formats such as MS Word, PostScript, PDF and so on. Programs like LyX allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose. In the end, SGML is more concerned about the way elements work instead of the way they look. A big distinction, and one that will let you write faster, since you don't have to worry about placement of paragraphs, font sizes, font types, and so on.
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The Jade and OpenJade packages also lets you export (I'll call it render from here on) SGML to LaTeX, info, text, HTML, and RTF. From these basic formats, you can then create other formats such as MS Word, PostScript, PDF and so on. Programs like LyX allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose. In the end, SGML is more concerned about the way elements work instead of the way they look. A big distinction, and one that will let you write faster, since you don't have to worry about placement of paragraphs, font sizes, font types, and so on.
</para>
</sect2>
<sect2>
@ -162,6 +167,17 @@
Jade is the front-end processor for SGML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML into the target format.
</para>
</sect3>
<sect3>
<title>
OpenJade
</title>
<para>
Replacement for Jade - <ulink url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink>
</para>
<para>
An extension of Jade written by the DSSSL community (see below for what a DSSSL is). Some applications require jade, but are being updated to support either software package.
</para>
</sect3>
<sect3>
<title>
DSSSL
@ -203,7 +219,7 @@
Optional
</para>
<para>
TeX (rhymes with blech!) is the markup language of choice for many, including those in the mathematics world. I still remember many Calculus exams that were actually written in TeX. It is also one of the first markup languages that is still around (the other being the *roff formats used in man pages). TeX actually follows some of the same concepts that SGML does. However, TeX renders its files into DVI (Device Independent) that can then be rendered into another format. Unfortunately, DVI can't be easily converted into anything other than printer languages (PostScript, PCL), making it hard to use to generate HTML. TeX is installed or is available with most Linux distributions. TeX is available on almost all distributions as LaTeX or TeTeX. Either should work for you.
TeX (rhymes with blech!) is the markup language of choice for many, including those in the mathematics world. I still remember many Calculus exams that were written in TeX. It is also one of the first markup languages that is still around (the other being the *roff formats used in man pages). TeX actually follows some of the same concepts that SGML does. However, TeX renders its files into DVI (Device Independent) that can then be rendered into another format. Unfortunately, DVI can't be easily converted into anything other than printer languages (PostScript, PCL), making it hard to use to generate HTML. TeX is installed or is available with most Linux distributions. TeX is available on almost all distributions as LaTeX or TeTeX. Either should work for you.
</para>
</sect3>
<sect3>
@ -261,6 +277,17 @@
This spell checking application can work around SGML tags, and only spell check the content within the tags. Default spell checkers like ispell will try to spellcheck the tags, causing errors at every new tag.
</para>
</sect3>
<sect3>
<title>
Cygnus DocBook Tools
</title>
<para>
Optional (may be Red Hat specific) - <ulink url="http://www.redhat.com/">http://www.redhat.com/</ulink>
</para>
<para>
Red Hat distributes three packages, possibly starting with 6.2, that include DocBook support and some tools. They provide for only rendering to HTML and PDF, but they're easily installed if you have Red Hat, allowing you to focus more on writing than wrestling with the tools. TeTex 0.9, Jade, and Jadetex must be installed first.
</para>
</sect3>
</sect2>
</sect1>
<sect1>
@ -290,6 +317,41 @@
<title>
Downloading and installing the tools
</title>
<sect3>
<title>
Manual using jade/openjade
</title>
<para>
This is the quick and dirty way that should work for all distributions, no matter what distribution you're using.
</para>
<orderedlist>
<listitem>
<para>
Create a base directory to store everything such as <emphasis>/usr/local/sgml</emphasis>. We'll call this <emphasis>&dollar;_toolroot</emphasis> form here on.
</para>
</listitem>
<listitem>
<para>
Install Jade, DocBook DTD, and DSSSL such that the base of each is under <emphasis>&dollar;_toolroot</emphasis> (creating <emphasis>&dollar;_toolroot/jade-1.2.1</emphasis>, <emphasis>&dollar;_toolroot/dtd</emphasis>, <emphasis>&dollar;_toolroot/dssl</emphasis>)
</para>
</listitem>
<listitem>
<para>
You'll need to set the <emphasis>SGML_CATALOG_FILES</emphasis> environment variable to the catalogs that you have under <emphasis>&dollar;_toolroot</emphasis>. You can do this with the command: <emphasis>&dollar;ENV&lcub;'SGML_CATALOG_FILES'&rcub; = &ldquo;&dollar;_toolroot/dtd/docbook.cat;&dollar;_toolroot/dsssl/docbook/catalog;&dollar;_toolroot/jade-1.2.1/dsssl/catalog&rdquo;</emphasis>
</para>
</listitem>
<listitem>
<para>
Now you can start using Jade. To create individual HTML files: <emphasis>&dollar;_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d &dollar;_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml</emphasis>
</para>
</listitem>
<listitem>
<para>
To create one large HTML file, add <emphasis>-V nochunks</emphasis> to the jade command.
</para>
</listitem>
</orderedlist>
</sect3>
<sect3>
<title>
sgmltools
@ -312,7 +374,7 @@ make
make install
</programlisting>
<para>
to install sgmltools. For RedHat-based systems (using RPM) you can use the rpmfind command to get the latest sgmltools. The rpmfind program is available at http://www.rpmfind.net/. Make sure you get sgmltools and not sgml-tools, as the latter is sgml-tools 1.0.9. For Debian-based systems, apt-get will retrieve the right package for you:
to install sgmltools. For Red Hat-based systems (using RPM) you can use the rpmfind command to get the latest sgmltools. The rpmfind program is available at http://www.rpmfind.net/. Make sure you get sgmltools and not sgml-tools, as the latter is sgml-tools 1.0.9. For Debian-based systems, apt-get will retrieve the right package for you:
</para>
<programlisting>
# apt-get install sgmltools
@ -321,6 +383,49 @@ make install
As with the RedHat, be sure to get sgmltools and not sgml-tools.
</para>
</sect3>
<sect3>
<title>
Cygnus DocBook Tools
</title>
<para>
These tools are provided with Red Hat 6.2. Make sure the following packages are installed:
</para>
<itemizedlist>
<listitem>
<para>
sgml-common
</para>
</listitem>
<listitem>
<para>
docbook
</para>
</listitem>
<listitem>
<para>
stylesheets
</para>
</listitem>
</itemizedlist>
<para>
Red Hat has the latest version on their web site: <ulink url="http://www.redhat.com/support/errata/RHBA-2000022-01.html">http://www.redhat.com/support/errata/RHBA-2000022-01.html</ulink>.
</para>
<para>
Download/get/sneakernet the RPMs to your machine and install in the usual manner (become root, then rpm -Uvh <emphasis>filename</emphasis>). Once the RPMs are installed, you can use the following commands to render DocBook:
</para>
<programlisting>
db2html <emphasis>filename</emphasis>
</programlisting>
<para>
Renders DocBook into HTML. A subdirectory with the filename (minus the .sgml extension) is created and the HTML files are placed there.
</para>
<programlisting>
db2pdf <emphasis>filename</emphasis>
</programlisting>
<para>
Renders DocBook into a PDF file.
</para>
</sect3>
</sect2>
<sect2>
<title>
@ -629,12 +734,12 @@ make install
</listitem>
<listitem>
<para>
Use &amp;tilde; for a tilde (&bsol; &lcub;&rcub;)
Use &amp;tilde; for a tilde (&tilde;)
</para>
</listitem>
<listitem>
<para>
Use &quot; and &quot; for quotes, or use &amp;dquot for &bsol;&quot;&lcub;&rcub;
Use &quot; and &quot; for quotes, or use &amp;dquot for
</para>
</listitem>
<listitem>
@ -886,4 +991,3 @@ v1.0, 21 April 2000
</article>