mirror of https://github.com/tLDP/LDP
updated
This commit is contained in:
gferg
parent
db233f0228
commit
505c50f61f
|
|
@ -18,8 +18,8 @@
|
|||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v1.1</revnumber>
|
||||
<date>2001-01-01</date>
|
||||
<revnumber>v1.2</revnumber>
|
||||
<date>2001-01-03</date>
|
||||
<authorinitials>rbe</authorinitials>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
|
@ -61,13 +61,20 @@
|
|||
DocBook tags are used to create books and articles. Within these
|
||||
documents, the <chapter>, <sect1>, and <para>
|
||||
tags are used. DocBook SGML files are stored in text files with a sgml
|
||||
or gml suffix. When processed, a single DocBook SGML file can
|
||||
or gml suffix.
|
||||
</para>
|
||||
<para>
|
||||
When processed, a single DocBook SGML file can
|
||||
output html, pdf, ps, txt and other formats for both
|
||||
online and printed publication. The processing is governed by
|
||||
stylesheets that can automatically generate a table of contents,
|
||||
page numbering, chapter & section numbering, and other
|
||||
features.
|
||||
</para>
|
||||
<para>
|
||||
DocBook is also designed for authoring unix manpages using
|
||||
<refentry>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
|
|
@ -134,13 +141,26 @@
|
|||
</FormalPara>
|
||||
|
||||
<FormalPara>
|
||||
<title>htmldoc</title>
|
||||
<title>HTMLdoc</title>
|
||||
<para>
|
||||
HTMLdoc is a free program for converting a website into a
|
||||
HTMLdoc is a free program for converting html files into a
|
||||
pdf or ps file.
|
||||
</para>
|
||||
</FormalPara>
|
||||
|
||||
<FormalPara>
|
||||
<title>SGMLSpm and docbook2X</title>
|
||||
<para>
|
||||
Together, these two are used to generate manpages. SGMLSpm is a perl5 module
|
||||
library for processing parsed output from <filename>onsgmls</filename>, a program
|
||||
included with OpenJade. SGMLSpm includes an application called <filename>sgmlspl</filename>
|
||||
to use the SGMLSpm library. <filename>Sgmlspl</filename> requires "spec files",
|
||||
which are available from various other sources on the Internet, for each
|
||||
type of document transformation to be performed. DocBook2X is a package that
|
||||
provides the spec files for transforming DocBook files into manpages.
|
||||
</para>
|
||||
</FormalPara>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -241,7 +261,7 @@ In this section, we will locate and download the software on the Internet.
|
|||
<para>
|
||||
The Document Style Semantics and Specification Language (DSSSL) files for the DocBook DTD (SGML/XML)
|
||||
is provided by <ulink url="http://www.nwalsh.com/">Norm Walsh</ulink>. These files, called the
|
||||
<ulink url="http://nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>, tell openjade what
|
||||
<ulink url="http://nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>, tell <filename>openjade</filename> what
|
||||
to do when converting your DocBook SGML file into other formats. A dsl file specifies things such as the
|
||||
mappings from one DTD's tags to another DTD's tags and other programmatic conversions, programmed in a
|
||||
language called the <ulink url="http://www.nwalsh.com/">Core Expression Language</ulink> which is derived from
|
||||
|
|
@ -265,7 +285,8 @@ In this section, we will locate and download the software on the Internet.
|
|||
<sect2>
|
||||
<title>Sgmltools-lite</title>
|
||||
<para>
|
||||
Sgmltools is a frontend for openjade, jadetex, pdfjadex, dvips, and other programs. It
|
||||
Sgmltools is a frontend for openjade, <filename>jadetex</filename>, <filename>pdfjadex</filename>,
|
||||
<filename>dvips</filename>, and other programs. It
|
||||
provides a single command for generating all the formats possible with these tools. The
|
||||
lastest release, v1.3 as of writing, can be downloaded at:
|
||||
</para>
|
||||
|
|
@ -282,10 +303,22 @@ In this section, we will locate and download the software on the Internet.
|
|||
Htmldoc is a free program for converting websites into Portable Document Format (pdf)
|
||||
or Postscript (ps). For pdf, it creates a tree of bookmarks that make navigation easy.
|
||||
Both htmldoc and pdfjadetex output pdf files, but in slightly different formats. Try
|
||||
both and see which turns out best for a particular docbook file.
|
||||
both and see which turns out best for a particular docbook file. See quick links
|
||||
below for download site.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>DocBook2X</title>
|
||||
<para>
|
||||
DocBook2X requires perl5 and the SGMLS.pm perl module, available at CPAN. SGMLS.pm
|
||||
provides libraries and a program called <filename>sgmlspl</filename> which translates DocBook files into other
|
||||
formats by using specification files. The specification files are perl files that
|
||||
provide the logic for the translation to a particular format.
|
||||
</para>
|
||||
<para><ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink></para>
|
||||
<para><ulink url="http://docbook2x.sourceforge.net/">http://docbook2x.sourceforge.net/</ulink></para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Quick Download Links</title>
|
||||
|
|
@ -335,11 +368,23 @@ In this section, we will locate and download the software on the Internet.
|
|||
need for your platform. Binaries are recommended. To find a binary,
|
||||
you can download it directly from ftp with the link above. If which to choose
|
||||
is not obvious, then try to going to the EasySw website:
|
||||
</para>
|
||||
</FormalPara>
|
||||
<para>
|
||||
<ulink url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>
|
||||
</para>
|
||||
</FormalPara>
|
||||
|
||||
<FormalPara>
|
||||
<title><ulink url="http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz">http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz</ulink></title>
|
||||
<para>
|
||||
SGMLS.pm 1.03ii at CPAN. (sgmlspl)
|
||||
</para>
|
||||
</FormalPara>
|
||||
|
||||
<FormalPara>
|
||||
<title><ulink url="http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz">http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz</ulink></title>
|
||||
<para>
|
||||
DocBook2X 0.6.0 (provides docbook2man-spec.pl for use with sgmlspl above)
|
||||
</para>
|
||||
</FormalPara>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -774,6 +819,63 @@ In this section, we will locate and download the software on the Internet.
|
|||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>DocBook2X and SGMLS.pm (sgmlspl)</title>
|
||||
<sect3>
|
||||
<title>sgmlspl</title>
|
||||
<para>
|
||||
Before the spec files from DocBook2X are of any use, the SGMLS.pm module
|
||||
for perl5 has to be installed, assuming that perl5 is installed. The
|
||||
installation of this module is not as automated as most perl module
|
||||
installs. It uses a Makefile that has to be edited first before
|
||||
running make.
|
||||
<screen>
|
||||
cd /usr/src
|
||||
tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
|
||||
cd SGMLSpm
|
||||
-- Edit Makfile
|
||||
vi Makefile
|
||||
-- In the user options of the Makefile
|
||||
-- set everything correct for
|
||||
-- your system.
|
||||
-- Example:
|
||||
-- PERL = /usr/bin/perl
|
||||
-- BINDIR = /usr/local/bin
|
||||
-- PERL5DIR = /usr/lib/perl5/site_perl
|
||||
-- MODULEDIR = ${PERL5DIR}/SGMLS
|
||||
-- SPECDIR = ${PERL5DIR}
|
||||
-- HTMLDIR= /usr/local/apache/htdocs
|
||||
make install
|
||||
</screen>
|
||||
sgmlspl gets copied to /usr/local/bin.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>docbook2X (docbook2man-spec.pl)</title>
|
||||
<para>
|
||||
DocBook2X contains no program to compile or install,
|
||||
though it has some scripts you might want to look at,
|
||||
so all there is to do is unpack it somwhere.
|
||||
<screen>
|
||||
cd /usr/local/share/sgml
|
||||
tar -xvzf ~/docbook2X-0.6.0.tar.gz
|
||||
cd docbook2X
|
||||
</screen>
|
||||
In the unpacked directory is the docbook2man-spec.pl and
|
||||
a patch file for it that corrects a few things.
|
||||
Applying the patch is optional but recommended.
|
||||
<screen>
|
||||
patch docbook2man-spec.pl docbook2man-spec.pl.patch
|
||||
</screen>
|
||||
Later, in Using DocBook, you will see how to use
|
||||
sgmlspl and docbook2man-spec.pl to generate a manpage from
|
||||
a refentry docbook document.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2>
|
||||
<title>$SGML_CATALOG_FILES</title>
|
||||
|
|
@ -917,6 +1019,7 @@ Test section 2.
|
|||
</figure>
|
||||
For a guide to DocBook and a reference of DocBook elements, go to:
|
||||
</para>
|
||||
|
||||
<FormalPara>
|
||||
<title>DocBook: The Definitive Reference</title>
|
||||
<para>
|
||||
|
|
@ -1215,10 +1318,7 @@ bash$ ls -l
|
|||
bash$
|
||||
</Screen>
|
||||
</figure>
|
||||
Notice the html filenames. This naming is good in this situation
|
||||
because when running htmldoc, the *.html sorts them in the
|
||||
proper order. Notice also, the use of htmldoc.dsl, the
|
||||
customized dsssl stylesheet for this task.
|
||||
Notice the use of htmldoc.dsl, the customized dsssl stylesheet for this task.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -1286,7 +1386,9 @@ bash$ ls -l
|
|||
bash$
|
||||
</Screen>
|
||||
</figure>
|
||||
This is just like using htmldoc to make a pdf.
|
||||
This is nearly the same command as used to generated a ps file with htmldoc but
|
||||
with just a different filename. Htmldoc understands what you want based on
|
||||
the filename extension.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -1349,7 +1451,8 @@ distclean: clean
|
|||
|
||||
package:
|
||||
rm -f $(BASENAME).tgz
|
||||
tar -C .. -czf $(BASENAME).tgz $(BASENAME)
|
||||
tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
|
||||
mv /tmp/$(BASENAME).tgz .
|
||||
|
||||
dist: clean package
|
||||
|
||||
|
|
@ -1410,15 +1513,279 @@ $(PS_FILE): $(DVI_FILE)
|
|||
Notice the commented compile rules for pdf and ps which
|
||||
provide alternative means of generating those files.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<para>
|
||||
That's all, folks!
|
||||
</para>
|
||||
<sect2>
|
||||
<title>Generating a manpage</title>
|
||||
<para>
|
||||
During the section on installing everything, we installed
|
||||
the perl5 module SGMLSpm. Then we installed docbook2X
|
||||
which provides the spec.pl files for transforming
|
||||
DocBook RefEntry documents into nroff (manpage) format
|
||||
with sgmlspl.
|
||||
</para>
|
||||
<para>
|
||||
An example Docbook RefEntry document, for the
|
||||
<filename>foo</filename> command, is given below.
|
||||
</para>
|
||||
<para>
|
||||
<figure>
|
||||
<title>foo manpage, docbook refentry source (foo-ref.sgml)</title>
|
||||
<screen>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
<date>2001-01-01</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>
|
||||
<application>foo</application>
|
||||
</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refmiscinfo>foo 1.0</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>
|
||||
<application>foo</application>
|
||||
</refname>
|
||||
<refpurpose>
|
||||
Does nothing useful.
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>2001-01-01</date>
|
||||
</refsynopsisdivinfo>
|
||||
<cmdsynopsis>
|
||||
<command>foo</command>
|
||||
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
|
||||
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
|
||||
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1>
|
||||
<refsect1info>
|
||||
<date>2001-01-01</date>
|
||||
</refsect1info>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<command>foo</command> does nothing useful.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>OPTIONS</title>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>-f <replaceable class="parameter">bar</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Takes <filename>bar</filename> as it's run
|
||||
control file. If this were a real program,
|
||||
there might be more to say here about what
|
||||
bar is and how it will be used.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>-d<replaceable class="parameter">n</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Do something, where integer
|
||||
<replaceable class="parameter">n</replaceable>
|
||||
specifies how many times.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><replaceable class="parameter">file...</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Processes the files in the order listed,
|
||||
sending all output to stdout.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>USAGE</title>
|
||||
<para>
|
||||
<command>foo</command> -f foo.conf -d2 foodata.foo
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>CAVEATS</title>
|
||||
<para>
|
||||
Other programs named <command>foo</command> may exist and actually
|
||||
do something!
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>BUGS</title>
|
||||
<para>
|
||||
None. Program does nothing.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>AUTHOR</title>
|
||||
<para>
|
||||
<author>
|
||||
<firstname>Foo</firstname>
|
||||
<othername role="mi">E</othername>
|
||||
<surname>Bar</surname>
|
||||
<contrib>Original author</contrib>
|
||||
</author>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
</screen>
|
||||
</figure>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<figure>
|
||||
<title>Generating a manpage with onsgmls, sgmlspl, and docbook2man-spec.pl</title>
|
||||
<screen>
|
||||
bash$ ls -l
|
||||
-rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml
|
||||
bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
|
||||
onsgmls:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
|
||||
bash$ ls -l
|
||||
-rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml
|
||||
-rw-r--r-- 1 reaster users 1129 Jan 3 04:03 foo.1
|
||||
-rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.links
|
||||
-rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.log
|
||||
-rw-r--r-- 1 reaster users 15 Jan 3 04:03 manpage.refs
|
||||
bash$ groff -mandoc -Tascii foo.1
|
||||
|
||||
FOO(1) FOO(1)
|
||||
|
||||
|
||||
NAME
|
||||
foo - Does nothing useful.
|
||||
|
||||
SYNOPSIS
|
||||
foo [ -f bar ] [ -dn ] [ file... ]
|
||||
|
||||
DESCRIPTION
|
||||
foo does nothing useful.
|
||||
|
||||
OPTIONS
|
||||
-f bar Takes bar as it's run control file. If this were a
|
||||
real program, there might be more to say here about
|
||||
what bar is and how it will be used.
|
||||
|
||||
-dn Do something, where integer n specifies how many
|
||||
times.
|
||||
|
||||
file...
|
||||
Processes the files in the order listed, sending
|
||||
all output to stdout.
|
||||
|
||||
USAGE
|
||||
foo -f foo.conf -d2 foodata.foo
|
||||
|
||||
CAVEATS
|
||||
Other programs named foo may exist and actually do some-
|
||||
thing!
|
||||
|
||||
BUGS
|
||||
None. Program does nothing.
|
||||
|
||||
AUTHOR
|
||||
Foo E Bar (Original author)
|
||||
|
||||
[snip - several extra blank lines that man would not show]
|
||||
foo 1.0 2001-01-01 1
|
||||
bash$ groff -mandoc -Tascii foo.1 | less
|
||||
bash$ less foo.1
|
||||
</screen>
|
||||
</figure>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The manpage, <filename>foo.1</filename>, is generated as a Section 1 page. The
|
||||
groff command is used to give a quick look at its formatted
|
||||
appearance.
|
||||
</para>
|
||||
<para>
|
||||
To install this manpage, it belongs in any man/man1 directory,
|
||||
where the directory man/ is added to <envar>$MANPATH</envar>
|
||||
in the environment. The standard location is
|
||||
<filename>/usr/local/man/man1</filename>.
|
||||
The standard sections in the manpages system are 1 though 9.
|
||||
Each is for holding specific catagories of documentation.
|
||||
</para>
|
||||
|
||||
<table>
|
||||
<title>Manpage Sections</title>
|
||||
<tgroup cols="2" align="center">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Section</entry>
|
||||
<entry>Purpose</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>man1</entry>
|
||||
<entry>User programs</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man2</entry>
|
||||
<entry>System calls</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man3</entry>
|
||||
<entry>Library functions and subroutines</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man4</entry>
|
||||
<entry>Devices</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man5</entry>
|
||||
<entry>File formats</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man6</entry>
|
||||
<entry>Games</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man7</entry>
|
||||
<entry>Miscellaneous</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man8</entry>
|
||||
<entry>System administration</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>man9</entry>
|
||||
<entry>Kernel internal variables and functions</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<tip>
|
||||
<para>
|
||||
The source file for a manpage, like <filename>foo-ref.sgml</filename>,
|
||||
can be processed into all the other formats just like any other
|
||||
DocBook file. So using the same commands discussed earlier to generate
|
||||
html and print output types, a manpage can be made into html and rtf, tex,
|
||||
pdf, dvi, and ps. This can really save a lot of conversion work!
|
||||
</para>
|
||||
</tip>
|
||||
|
||||
<para>
|
||||
Have fun!
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="misc">
|
||||
<title>Copyright</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue