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

Moved the Tools section into the appendix the writing sections. Documents 

are NOT finished.
This commit is contained in:
emmajane 2003-08-13 06:46:59 +00:00
parent 451f13127e
commit 811ff2d196
3 changed files with 760 additions and 741 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

744
LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml
View File

@ -23,6 +23,8 @@
<!ENTITY authoring-writing SYSTEM "authoring-writing.xml">
<!ENTITY cvs SYSTEM "cvs.xml">
<!-- Appendix B. Editors, Validation and System Setup -->
<!ENTITY tools SYSTEM "tools.xml">
<!ENTITY using-docbook SYSTEM "using-docbook.xml">
@ -271,746 +273,10 @@
This chapter includes:
-->
&authoring-writing;
<!-- Appendix B: Editors, Validation and System Setup -->
&tools;
<chapter id="tools">
<title>The tools</title>
<para>In this section, we will cover some of the tools that you will
need or want to use to create your own LDP documentation. I'll
describe them here, and better define them later on, along with
how to install them. If you use some other tool to assist in
writing LDP, please let me know and I'll add a blurb here for
it.</para>
<section id="dsssl">
<title>DSSSL</title>
<para>The Normal Walsh version is required, the LDP is
optional but recommended.</para>
<section id="nwdsssl">
<title>Norman Walsh DSSSL</title>
<para><ulink
url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink></para>
<para>The <indexterm><primary>DSSSL</primary></indexterm>
Document Style Semantics and Specification Language
tells jade (see <xref linkend="jade"/>) how to render a DocBook document
into print or online
form. The DSSSL is what converts a title tag into an
&lt;H1&gt; tag in HTML, or to 14 point bold Times Roman for RTF,
for example. Documentation for DSSSL is located at the same
site. Note that modifying the DSSSL doesn't modify DocBook
itself. It merely changes the way the rendered text looks. The
LDP uses a modified DSSSL (see below).</para>
</section>
<section id="ldpdsssl">
<title>LDP DSSSL</title>
<para><ulink
url="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink></para>
<para>The LDP DSSSL requires the Norman Walsh version (see
above) but is a slightly modified DSSSL to provide things like
a table of contents.</para>
</section>
</section>
<section id="dtd">
<title>DocBook DTD (version 4.1 or 3.1)</title>
<para>Required - <ulink
url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip</ulink> or <ulink
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</ulink></para>
<para>The XML DTD is available from <ulink url="http://www.oasis-open.org/docbook/xml/4.1.2">http://www.oasis-open.org/xml/4.1.2/</ulink>.
</para>
<para>
The <indexterm><primary>DocBook DTD</primary></indexterm>
DocBook DTD defines the tags and structure of a
DocBook document. Modifying the DTD, such as adding a new
tag, means that this DTD is no longer DocBook.
</para>
</section>
<section id="jade">
<title>Jade</title>
<para>
<indexterm><primary>jade</primary></indexterm>
Jade and OpenJade are two of the programs that do most of
the rendering and validation of code based on the DTD and
DSSSL. One of the following is required and should be installed
after the DTD and DSSSL have been installed.
</para>
<section>
<title>Jade</title>
<para><ulink
url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink></para>
<para>Jade is the front-end processor for SGML and XML. It uses the
DSSSL and DocBook DTD to perform the verification and
rendering from SGML and XML into the target format.</para>
<section id="usingjade">
<title>Using Jade</title>
<para>This is the quick and dirty way that should work for all
distributions, no matter what one you are using.
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Create a base directory to store everything such as
<filename moreinfo="none"
class="directory">/usr/local/sgml/</filename>. We'll call
this <envar>$_toolroot</envar> from here on.</para>
</listitem>
<listitem>
<para>Install Jade, DocBook DTD, and DSSSL such that the
base of each is under <envar>$_toolroot</envar>, creating:
</para>
<itemizedlist>
<listitem>
<para><filename class="directory">$_toolroot/jade-1.2.1</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dtd</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dsssl</filename>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>You'll need to set the
<envar>SGML_CATALOG_FILES</envar> environment variable to
the catalogs that you have under<filename moreinfo="none"
class="directory">$_toolroot</filename>. You can do this
with the command:
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command moreinfo="none">export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog</command>
</screen>
</para>
</listitem>
<listitem>
<para>Now you can start using Jade. To create individual
HTML files: </para>
<screen format="linespecific">
<command moreinfo="none">$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml</command>
</screen>
</listitem>
<listitem>
<para>To create one large HTML file, add <emphasis>-V
nochunks</emphasis> to the jade command.</para>
</listitem>
</orderedlist>
</section>
<section id="jadexml">
<title>Jade in XML mode</title>
<para>
Once configured for XML, jade and openjade will work
the same way as for SGML DocBook.
</para>
<para>
After extracting the XML DTD, you will want to make
a symlink from the docbook.cat file to "catalog", the
default filename for jade/openjade catalogs. Replace
$_xml_root with the location of your XML DTD.
</para>
<informalexample>
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command>cd $_xml_root</command>
<prompt moreinfo="none">bash$</prompt> <command>ln -s docbook.cat catalog</command>
<prompt moreinfo="none">bash$</prompt> <command>export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<prompt moreinfo="none">bash$</prompt> <command>jade -t sgml -i html -d <replaceable>style</replaceable> $_jade_path/pubtext/xml.dcl foo.xml</command> <co id="jadexmlcmd"/>
</screen>
<calloutlist>
<callout arearefs="export">
<para>
You'll need the catalogs for XML, the DSSSL, and DocBook,
respectively. $_toolroot was defined above.
</para>
</callout>
<callout arearefs="jadexmlcmd">
<para>
Replace <replaceable>style</replaceable> with the DSSSL
(ldp.dsl) you wish to use. The pointer to xml.dcl is
required for jade to work, and it has to be listed
immediately before the pointer to your XML document.
This file may be in a different directory.
Check your distribution.
</para>
<para>
You may get the following warnings when processing XML
documents. They don't impact the output, and the cause
is being looked into.
</para>
<screen>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
</screen>
</callout>
</calloutlist>
</informalexample>
<para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines at the
very start of your document).
</para>
<screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
&lt;!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen>
<para>
If you have followed LDP guidelines, there should be no
other changes required to your document. Note that there
are changes between DocBook 3.x and 4.x that you may
also have to take into account. You can get more information
at this in <xref linkend="differences3040"/>.
</para>
</section>
</section>
<section id="openjade">
<title>OpenJade</title>
<para><ulink
url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink></para>
<para>An extension of Jade written by the DSSSL
community. Some applications require jade, but are being
updated to support either software package.</para>
</section>
</section>
<section id="jadewrappers">
<title>Jade wrappers</title>
<para>These tools are optional and may be installed after Jade,
the DSSSL, and DTD have been installed.</para>
<section id="sgmltools-lite">
<title>sgmltools-lite</title>
<para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project, which
acts as a wrapper to the jade SGML processor. It hides much of
the ugliness of the syntax. This author was able to install the
old sgmltools package followed by the sgmltools-lite and could
format this document quite easily. There's even a man page for
sgmltools showing syntax.</para>
</section>
<section id="cygnus">
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the
6.2 release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more on
writing than wrestling with the tools. TeTex, Jade, and
JadeTeX must be installed first. All three of these packages
are available on the installation CD.
</para>
<section id="usingcygnus">
<title>Using the Cygnus 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-0.1-8.noarch </para></listitem>
<listitem><para> docbook-3.1-4.noarch </para></listitem>
<listitem><para> stylesheets-1.54.13rh-1.noarch </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/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the RPMs
are installed, you can use the following commands to render
DocBook: </para>
<screen>
<prompt>bash$</prompt> <command>db2html</command> <option>filename</option>
</screen>
<para> Renders DocBook into HTML. A subdirectory with the
filename (minus the .sgml extension) is created and the HTML
files are placed there. </para>
<screen>
<prompt>bash$</prompt> <command>db2pdf</command> <option>filename</option>
</screen>
<para>Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
<ulink url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section>
</section>
</section>
<section id="editing">
<title>Editing tools</title>
<para>The following tools may be used to create, edit, or
validate your HOWTO.</para>
<section id="psgml">
<title>Emacs (PSGML)</title>
<para>Optional - <ulink
url="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</ulink></para>
<indexterm>
<primary>Emacs</primary>
</indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>emacs</secondary>
</indexterm>
<para>Emacs has an SGML writing mode called psgml that is a
major mode designed for editing SGML and XML documents. It
provides <quote>syntax highlighting</quote> or <quote>pretty
printing</quote> features that make SGML tags stand out, a way
to insert tags other than typing them by hand, and the ability
to validate your document while writing.</para>
<para>For users of Emacs, it's a great way to go, and many
believe it to allow more versatility than any other SGML
documentation tool. It works with DocBook, LinuxDoc and other
DTDs equally well.</para>
<section>
<title> Writing SGML using PSGML </title>
<section><title> Introduction </title>
<para> If you have installed a recent distribution, you may
already have PSGML installed for use with Emacs. To check,
start Emacs and look for the PSGML documentation (<keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">h</keycap></keycombo><keycap
moreinfo="none">i</keycap><keycap
moreinfo="none">m</keycap><keycap
moreinfo="none">psgml</keycap>).</para>
<para> From here on, we assume you have PSGML installed for
use with a recent version of GNU Emacs. If that all went by
too fast for you, see the free chapter from Bob Ducharme's
SGML CD book: <ulink
url="http://www.snee.com/bob/sgmlfree/psgmqref.html">http://www.snee.com/bob/sgmlfree/psgmqref.html</ulink>.</para>
</section>
<section>
<title> Updating your .emacs to use PSGML </title>
<para> If you want GNU Emacs to enter PSGML mode when you open
a <emphasis>.sgml</emphasis> file and be ready for SGML
editing, make sure PSGML can find the DocBook DTD. If your
distribution already had PSGML set up for use with GNU Emacs,
you probably do not have to do anything to get this to
work. Otherwise, you may need to set an environment variable
that tells PSGML where to look for the SGML catalog (the list
of DTDs). </para>
<para> For example: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>export SGML_CATALOG_FILES=/usr/lib/sgml/catalog</command>
</screen>
<para> Then add something like the following to your .emacs
file: </para>
<programlisting>
;; *******************************************************************
;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode
;;
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist
(append
(list
'("\\.sgm$" . sgml-mode)
'("\\.sgml$" . sgml-mode)
)
auto-mode-alist))
;; set some psgml variables
(setq sgml-auto-activate-dtd t)
(setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-live-element-indicator t)
(setq sgml-indent-step nil)
;; create faces to assign to markup categories
(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start
(make-face 'sgml-ms-end-face) ; end of marked section
(make-face 'sgml-pi-face) ; processing instructions
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references
;; view a list of available colors with the emacs-lisp command:
;;
;; list-colors-display
;;
;; please assign your own groovy colors, because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral")
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")
;; assign faces to markup categories
(setq sgml-markup-faces '
(
(comment . sgml-comment-face)
(start-tag . sgml-start-tag-face)
(end-tag . sgml-end-tag-face)
(entity . sgml-entity-face)
(doctype . sgml-doctype-face)
(ignored . sgml-ignored-face)
(ms-start . sgml-ms-start-face)
(ms-end . sgml-ms-end-face)
(pi . sgml-pi-face)
(sgml . sgml-sgml-face)
(shortref . sgml-shortref-face)
))
;; tell PSGML to pay attention to face settings
(setq sgml-set-face t)
;; ...done setting up psgml-mode.
;; *******************************************************************
</programlisting>
<para> Then restart Emacs </para>
</section>
<section>
<title> SGML Smoke Test </title>
<para> Try the following smoke test. Start a new file,
<filename moreinfo="none">/tmp/test.sgml</filename> for
example, and enter the following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo>. If Emacs
manages to parse your DTD, you will see <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. Try
<emphasis>C-c C-e RETURN</emphasis> to insert a
<emphasis><sgmltag
class="starttag">test</sgmltag></emphasis> element. If
things are working correctly, you should see the following
in Emacs: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
<sgmltag class="starttag">test</sgmltag><sgmltag class="endtag">test</sgmltag>
</programlisting>
</section>
<section>
<title> Writing a New HOWTO in DocBook </title>
<para> Start a new file for your HOWTO and enter the
following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap><keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo> and hold
your breath. If everything goes as planned, you will see
Emacs chewing for a few seconds and then <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. </para>
<para> At this point, enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">e</keycap></keycombo><keycap
moreinfo="none">RETURN</keycap> to insert an
<emphasis><sgmltag
class="starttag">article</sgmltag></emphasis> element and
proceed to write your HOWTO. </para>
</section>
<section>
<title> Quick Reference for Emacs with PSGML </title>
<para> See Nik Clayton's primer for FreeBSD documentation:
<ulink
url="http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html">http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html</ulink>
</para>
</section>
</section>
</section>
<section id="vim">
<title>VIM</title>
<para><ulink
url="http://www.vim.org">http://www.vim.org</ulink></para>
<para>No mention of Emacs is complete without talking about
vi. The <indexterm><primary>vim</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>vim</secondary>
</indexterm>
VIM (Vi IMproved) editor has the functionality of
regular vi, but also has an SGML mode that will
color-coordinate your screen to show where tags are.</para>
<section id="usingvim">
<title>Getting Started</title>
<para>The vim program comes in many parts. There is
the plain vim program, which is compatibile with the
vi program and its commands. Red Hat users will want the vim-common
and vim-minimal packages. Next is the enhanced
<command>vim</command>, which includes the highlighting and other
features of vim over regular vi. Red Hat
users will want vim-enhanced. Last, but certainly not least, is the
X interface, which gives a graphical interface, menus, and mouse
control. To separate this from vim or vi, the command for graphical
access is called <command>gvim</command>.</para>
</section>
<section>
<title>Loading or starting new documents</title>
<para>In both <command>vim</command> and <command>gvim</command> modes,
<filename>.sgml</filename> files will be automatically recognized and
enter into <quote>sgml mode</quote>. A series of known DocBook tags
have been entered into <command>vim</command> and will he highlighted
in brown if a tag is known. If it isn't, it will appear in light blue.
attributes to known tags are in light blue, and values for the
attributes are in pink. From here on, you can use regular <command>vi</command>
commands to navigate and edit.</para>
<para>
While VIM has an XML mode, this mode will not highlight known
and unknown DocBook tags. You can still force VIM into
SGML mode if you like using the <command>:set ft=sgml</command>
command. Note that this will not have any affect on the file
or its contents, only the highlighting within VIM.
</para>
</section>
</section>
<section id="wordperfect">
<title>WordPerfect 9 (Corel Office 2000)</title>
<para><ulink
url="http://www.corel.com/">http://www.corel.com/</ulink></para>
<para>WordPerfect 9 for the MS Windows platform has support
for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML
capabilities.</para>
<para>This is the least expensive of the commercial
applications that support SGML.</para>
</section>
<section id="epcEdit">
<title>epcEdit</title>
<para><ulink
url="http://www.tksgml.de/">http://www.tksgml.de/</ulink></para>
<para>The <indexterm><primary>epcEdit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>epcEdit</secondary>
</indexterm>
epcEdit program allows you to visually edit SGML
files. It has the advantages of not needing to know Emacs or
vi before starting, and is cross-platform, working in both
Windows and Linux. This is a commercial application, and
pricing can be found at
<ulink url="http://www.tksgml.de/pricing.html">http://www.tksgml.de/pricing.html</ulink>
</para>
<para>Along with visual editing, epcEdit will also validate
documents on loading, and on demand by using the <menuchoice
moreinfo="none"><guimenu
moreinfo="none">Document</guimenu><guimenuitem
moreinfo="none">Validate</guimenuitem></menuchoice>
command.</para>
<figure>
<title>epcEdit screen shot</title>
<mediaobject>
<imageobject>
<imagedata format="EPS" fileref="sgeditscreenshot.eps"/>
</imageobject>
<imageobject>
<imagedata format="JPG" fileref="sgeditscreenshot.jpg"/>
</imageobject>
<textobject>
<phrase>The screen shot of the epcEdit program shows a
tree on the left side that has the SGML document in a
hierarchy, while the right side shows the document.
Tags are shown with a grey background.</phrase>
</textobject>
</mediaobject>
</figure>
</section>
<section id="nedit">
<title>nedit</title>
<para><ulink
url="http://nedit.org">http://nedit.org</ulink></para>
<para>To be fair,
<indexterm><primary>nedit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>nedit</secondary>
</indexterm>
nedit is more
for programmers, so it might seem a bit of overkill for new
users and especially non-programmers. All that aside, it's
extremely powerful, allowing for color coding of tags. Unlike
epcEdit, nedit doesn't allow you to automatically insert tags
or automatically validate your code. However, it does allow
for shell commands to be run against the contents of the
window (as opposed to saving the file, then checking). In a
few minutes, I was able to set up <command>nsgmls</command> to
validate the SGML and <command>aspell</command> to do my spell
checking.
<figure>
<title>nedit screen shot</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditscreenshot.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditscreenshot.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>The nedit program can provide line numbers
across the left side of the screen, handy for when
<command>nsgmls</command> complains of errors</phrase>
</textobject>
</mediaobject>
</figure>
</para>
<section id="usingnedit">
<title>Using nedit</title>
<para>For writing new documentation, it is recommended that
you download and use the LDP DocBook template. Once you have
the file, you can start up nedit and begin editing. If the
file is saved with a .sgml extension, nedit will load the file
up with SGML/HTML tags enabled. You can turn this on
explicitly using the
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Language
Mode</guimenuitem><guimenuitem>SGML
HTML</guimenuitem></menuchoice> command. </para>
</section> <!-- New Documents -->
<section id="tipsandtricksnedit">
<title>Tips and tricks with nedit</title>
<para>Since you can feed the contents of your window to
outside programs, you can easily extend nedit to perform
repetitive functions. The example you'll see here is to
validate the SGML code using <command>nsgmls</command>.</para>
<para> Select
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Default
Settings</guimenuitem><guimenuitem>Customize
Menus</guimenuitem><guimenuitem>Shell
Menu...</guimenuitem></menuchoice>. This will bring up the
Shell Command dialog box, with all the shell commands nedit
has listed under the
<menuchoice><guimenu>Shell</guimenu></menuchoice> menu. Under
Menu Entry, enter "SGML Validate". This will be the entry
you'll see on the screen. Under Accelerator, press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
Once this menu item is set up, you can press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>
to have the SGML Validate automatically run. Under Command
Input, select window, and under Command Output, select
dialog. Under Command to Execute, enter nsgmls -sv. Note
that <command>nsgmls</command> has to be in your
<envar>PATH</envar> for this to work properly. </para>
<figure>
<title>Adding shell commands to nedit</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditshellcommand.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditshellcommand.jpg" format="JPG"/>
</imageobject>
</mediaobject>
</figure>
<para> Click <guibutton>OK</guibutton> and you'll now be back
at the main nedit screen. Load up an SGML file, and select
<menuchoice><guimenu>Shell</guimenu><guimenuitem>SGML
Validate</guimenuitem></menuchoice> or press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
The <command>nedit</command> program will fire up and check
the contents of the window. The reason for using -sv is that
the -v tells <command>nsgmls</command> to output the version
of the program, so you'll always get output and know that
<command>nsgmls</command> has run. If all you get is a
version number, then there are no errors with the document.
If there are errors, then they'll be listed in the separate
window for you to see. If you have line numbers turned on
(using
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
Line Numbers</guimenuitem></menuchoice>) then finding the
errors is much simpler, as <command>nsgmls</command> will list
errors by their line number.</para>
<figure>
<title>nsgmls output on success</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditsuccess.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditsuccess.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>If nsgmls reports success, it merely reports the version of nsgmls</phrase>
</textobject>
</mediaobject>
</figure>
</section>
</section>
<section id="morphoneditor">
<title>Morphon XML editor</title>
<para> <ulink url="http://www.morphon.com/xmleditor/index.shtml">http://www.morphon.com/xmleditor/index.shtml</ulink></para>
<para>This is a commerical application that has a free 30 day
license available for download. It is written in Java, allowing
it to run on any platform that has a JVM (that is, works in both
Windows and Linux). The cost is $150USD for a single user
license, and $75USD for a student license.</para>
<para>On the plus sides of XMLEditor is the left side of the
screen shows the heirarchy of the document (starting with Book
and so on). Selecting an item in the list brings you to that
part of the document so you can edit it. The right part of the
screen shows the text without any markup or tags being shown.
If you have external files as ELEMENTS (as the LDP Author Guide
does), XMLEditor will follow the links and load the files, so
you always work on the entire work. On the minus side of this,
you will get errors if a file (like index.xml) is
missing.</para>
</section>
</section>
&cvs;
<section id="other">
<title>Other/Reference</title>
<para>The items in this section are reference books or other

20
LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml
View File

@ -233,8 +233,24 @@
&cvs;
<section id="tools-other">
<title>Spell Check</title>
<section id="aspell">
<title>Aspell</title>
<para>Optional - <ulink
url="http://aspell.sourceforge.net/">http://aspell.sourceforge.net/</ulink></para>
<para>This spell checking application can work around XML tags. By
distinguishing between content and markup aspell is able to check
your content and ignore the bits it shouldn't be looking at. If you
are getting spelling errors in your markup tags you may be using an
old version and should upgrade.
</para>
</section>
<section id="ispell">
<title>ispell</title>
<para>Optional - <ulink url="http://www.cs.hmc.edu/~geoff/ispell.html">http://www.cs.hmc.edu/~geoff/ispell.html</ulink></para>
<para>The ispell program is distributed with RedHat (and possibly other
distros) and also ignores markup tags.</para>
</section>
</section>
</section> <!-- end writing-tools -->

737
LDP/guide/docbook/LDP-Author-Guide/tools.xml Normal file
View File

@ -0,0 +1,737 @@
<chapter id="tools">
<title>The tools</title>
<para>In this section, we will cover some of the tools that you will
need or want to use to create your own LDP documentation. I'll
describe them here, and better define them later on, along with
how to install them. If you use some other tool to assist in
writing LDP, please let me know and I'll add a blurb here for
it.</para>
<section id="dsssl">
<title>DSSSL</title>
<para>The Normal Walsh version is required, the LDP is
optional but recommended.</para>
<section id="nwdsssl">
<title>Norman Walsh DSSSL</title>
<para><ulink
url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink></para>
<para>The <indexterm><primary>DSSSL</primary></indexterm>
Document Style Semantics and Specification Language
tells jade (see <xref linkend="jade"/>) how to render a DocBook document
into print or online
form. The DSSSL is what converts a title tag into an
&lt;H1&gt; tag in HTML, or to 14 point bold Times Roman for RTF,
for example. Documentation for DSSSL is located at the same
site. Note that modifying the DSSSL doesn't modify DocBook
itself. It merely changes the way the rendered text looks. The
LDP uses a modified DSSSL (see below).</para>
</section>
<section id="ldpdsssl">
<title>LDP DSSSL</title>
<para><ulink
url="http://www.tldp.org/authors/tools/ldp.dsl">http://www.tldp.org/authors/tools/ldp.dsl</ulink></para>
<para>The LDP DSSSL requires the Norman Walsh version (see
above) but is a slightly modified DSSSL to provide things like
a table of contents.</para>
</section>
</section>
<section id="dtd">
<title>DocBook DTD (version 4.1 or 3.1)</title>
<para>Required - <ulink
url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip</ulink> or <ulink
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</ulink></para>
<para>The XML DTD is available from <ulink url="http://www.oasis-open.org/docbook/xml/4.1.2">http://www.oasis-open.org/xml/4.1.2/</ulink>.
</para>
<para>
The <indexterm><primary>DocBook DTD</primary></indexterm>
DocBook DTD defines the tags and structure of a
DocBook document. Modifying the DTD, such as adding a new
tag, means that this DTD is no longer DocBook.
</para>
</section>
<section id="jade">
<title>Jade</title>
<para>
<indexterm><primary>jade</primary></indexterm>
Jade and OpenJade are two of the programs that do most of
the rendering and validation of code based on the DTD and
DSSSL. One of the following is required and should be installed
after the DTD and DSSSL have been installed.
</para>
<section>
<title>Jade</title>
<para><ulink
url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink></para>
<para>Jade is the front-end processor for SGML and XML. It uses the
DSSSL and DocBook DTD to perform the verification and
rendering from SGML and XML into the target format.</para>
<section id="usingjade">
<title>Using Jade</title>
<para>This is the quick and dirty way that should work for all
distributions, no matter what one you are using.
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>Create a base directory to store everything such as
<filename moreinfo="none"
class="directory">/usr/local/sgml/</filename>. We'll call
this <envar>$_toolroot</envar> from here on.</para>
</listitem>
<listitem>
<para>Install Jade, DocBook DTD, and DSSSL such that the
base of each is under <envar>$_toolroot</envar>, creating:
</para>
<itemizedlist>
<listitem>
<para><filename class="directory">$_toolroot/jade-1.2.1</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dtd</filename>
</para>
</listitem>
<listitem>
<para><filename class="directory">$_toolroot/dsssl</filename>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>You'll need to set the
<envar>SGML_CATALOG_FILES</envar> environment variable to
the catalogs that you have under<filename moreinfo="none"
class="directory">$_toolroot</filename>. You can do this
with the command:
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command moreinfo="none">export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\
$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog</command>
</screen>
</para>
</listitem>
<listitem>
<para>Now you can start using Jade. To create individual
HTML files: </para>
<screen format="linespecific">
<command moreinfo="none">$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \
-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml</command>
</screen>
</listitem>
<listitem>
<para>To create one large HTML file, add <emphasis>-V
nochunks</emphasis> to the jade command.</para>
</listitem>
</orderedlist>
</section>
<section id="jadexml">
<title>Jade in XML mode</title>
<para>
Once configured for XML, jade and openjade will work
the same way as for SGML DocBook.
</para>
<para>
After extracting the XML DTD, you will want to make
a symlink from the docbook.cat file to "catalog", the
default filename for jade/openjade catalogs. Replace
$_xml_root with the location of your XML DTD.
</para>
<informalexample>
<screen format="linespecific">
<prompt moreinfo="none">bash$</prompt> <command>cd $_xml_root</command>
<prompt moreinfo="none">bash$</prompt> <command>ln -s docbook.cat catalog</command>
<prompt moreinfo="none">bash$</prompt> <command>export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\
$_toolroot/dtd/docbook/catalog</command> <co id="export"/>
<prompt moreinfo="none">bash$</prompt> <command>jade -t sgml -i html -d <replaceable>style</replaceable> $_jade_path/pubtext/xml.dcl foo.xml</command> <co id="jadexmlcmd"/>
</screen>
<calloutlist>
<callout arearefs="export">
<para>
You'll need the catalogs for XML, the DSSSL, and DocBook,
respectively. $_toolroot was defined above.
</para>
</callout>
<callout arearefs="jadexmlcmd">
<para>
Replace <replaceable>style</replaceable> with the DSSSL
(ldp.dsl) you wish to use. The pointer to xml.dcl is
required for jade to work, and it has to be listed
immediately before the pointer to your XML document.
This file may be in a different directory.
Check your distribution.
</para>
<para>
You may get the following warnings when processing XML
documents. They don't impact the output, and the cause
is being looked into.
</para>
<screen>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
</screen>
</callout>
</calloutlist>
</informalexample>
<para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines at the
very start of your document).
</para>
<screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
&lt;!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen>
<para>
If you have followed LDP guidelines, there should be no
other changes required to your document. Note that there
are changes between DocBook 3.x and 4.x that you may
also have to take into account. You can get more information
at this in <xref linkend="differences3040"/>.
</para>
</section>
</section>
<section id="openjade">
<title>OpenJade</title>
<para><ulink
url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink></para>
<para>An extension of Jade written by the DSSSL
community. Some applications require jade, but are being
updated to support either software package.</para>
</section>
</section>
<section id="jadewrappers">
<title>Jade wrappers</title>
<para>These tools are optional and may be installed after Jade,
the DSSSL, and DTD have been installed.</para>
<section id="sgmltools-lite">
<title>sgmltools-lite</title>
<para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project, which
acts as a wrapper to the jade SGML processor. It hides much of
the ugliness of the syntax. This author was able to install the
old sgmltools package followed by the sgmltools-lite and could
format this document quite easily. There's even a man page for
sgmltools showing syntax.</para>
</section>
<section id="cygnus">
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the
6.2 release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more on
writing than wrestling with the tools. TeTex, Jade, and
JadeTeX must be installed first. All three of these packages
are available on the installation CD.
</para>
<section id="usingcygnus">
<title>Using the Cygnus 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-0.1-8.noarch </para></listitem>
<listitem><para> docbook-3.1-4.noarch </para></listitem>
<listitem><para> stylesheets-1.54.13rh-1.noarch </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/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the RPMs
are installed, you can use the following commands to render
DocBook: </para>
<screen>
<prompt>bash$</prompt> <command>db2html</command> <option>filename</option>
</screen>
<para> Renders DocBook into HTML. A subdirectory with the
filename (minus the .sgml extension) is created and the HTML
files are placed there. </para>
<screen>
<prompt>bash$</prompt> <command>db2pdf</command> <option>filename</option>
</screen>
<para>Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
<ulink url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section>
</section>
</section>
<section id="editing">
<title>Editing tools</title>
<para>The following tools may be used to create, edit, or
validate your HOWTO.</para>
<section id="psgml">
<title>Emacs (PSGML)</title>
<para>Optional - <ulink
url="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</ulink></para>
<indexterm>
<primary>Emacs</primary>
</indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>emacs</secondary>
</indexterm>
<para>Emacs has an SGML writing mode called psgml that is a
major mode designed for editing SGML and XML documents. It
provides <quote>syntax highlighting</quote> or <quote>pretty
printing</quote> features that make SGML tags stand out, a way
to insert tags other than typing them by hand, and the ability
to validate your document while writing.</para>
<para>For users of Emacs, it's a great way to go, and many
believe it to allow more versatility than any other SGML
documentation tool. It works with DocBook, LinuxDoc and other
DTDs equally well.</para>
<section>
<title> Writing SGML using PSGML </title>
<section><title> Introduction </title>
<para> If you have installed a recent distribution, you may
already have PSGML installed for use with Emacs. To check,
start Emacs and look for the PSGML documentation (<keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">h</keycap></keycombo><keycap
moreinfo="none">i</keycap><keycap
moreinfo="none">m</keycap><keycap
moreinfo="none">psgml</keycap>).</para>
<para> From here on, we assume you have PSGML installed for
use with a recent version of GNU Emacs. If that all went by
too fast for you, see the free chapter from Bob Ducharme's
SGML CD book: <ulink
url="http://www.snee.com/bob/sgmlfree/psgmqref.html">http://www.snee.com/bob/sgmlfree/psgmqref.html</ulink>.</para>
</section>
<section>
<title> Updating your .emacs to use PSGML </title>
<para> If you want GNU Emacs to enter PSGML mode when you open
a <emphasis>.sgml</emphasis> file and be ready for SGML
editing, make sure PSGML can find the DocBook DTD. If your
distribution already had PSGML set up for use with GNU Emacs,
you probably do not have to do anything to get this to
work. Otherwise, you may need to set an environment variable
that tells PSGML where to look for the SGML catalog (the list
of DTDs). </para>
<para> For example: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>export SGML_CATALOG_FILES=/usr/lib/sgml/catalog</command>
</screen>
<para> Then add something like the following to your .emacs
file: </para>
<programlisting>
;; *******************************************************************
;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode
;;
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist
(append
(list
'("\\.sgm$" . sgml-mode)
'("\\.sgml$" . sgml-mode)
)
auto-mode-alist))
;; set some psgml variables
(setq sgml-auto-activate-dtd t)
(setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-live-element-indicator t)
(setq sgml-indent-step nil)
;; create faces to assign to markup categories
(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start
(make-face 'sgml-ms-end-face) ; end of marked section
(make-face 'sgml-pi-face) ; processing instructions
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references
;; view a list of available colors with the emacs-lisp command:
;;
;; list-colors-display
;;
;; please assign your own groovy colors, because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral")
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")
;; assign faces to markup categories
(setq sgml-markup-faces '
(
(comment . sgml-comment-face)
(start-tag . sgml-start-tag-face)
(end-tag . sgml-end-tag-face)
(entity . sgml-entity-face)
(doctype . sgml-doctype-face)
(ignored . sgml-ignored-face)
(ms-start . sgml-ms-start-face)
(ms-end . sgml-ms-end-face)
(pi . sgml-pi-face)
(sgml . sgml-sgml-face)
(shortref . sgml-shortref-face)
))
;; tell PSGML to pay attention to face settings
(setq sgml-set-face t)
;; ...done setting up psgml-mode.
;; *******************************************************************
</programlisting>
<para> Then restart Emacs </para>
</section>
<section>
<title> SGML Smoke Test </title>
<para> Try the following smoke test. Start a new file,
<filename moreinfo="none">/tmp/test.sgml</filename> for
example, and enter the following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo>. If Emacs
manages to parse your DTD, you will see <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. Try
<emphasis>C-c C-e RETURN</emphasis> to insert a
<emphasis><sgmltag
class="starttag">test</sgmltag></emphasis> element. If
things are working correctly, you should see the following
in Emacs: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
<sgmltag class="starttag">test</sgmltag><sgmltag class="endtag">test</sgmltag>
</programlisting>
</section>
<section>
<title> Writing a New HOWTO in DocBook </title>
<para> Start a new file for your HOWTO and enter the
following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap><keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo> and hold
your breath. If everything goes as planned, you will see
Emacs chewing for a few seconds and then <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. </para>
<para> At this point, enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">e</keycap></keycombo><keycap
moreinfo="none">RETURN</keycap> to insert an
<emphasis><sgmltag
class="starttag">article</sgmltag></emphasis> element and
proceed to write your HOWTO. </para>
</section>
<section>
<title> Quick Reference for Emacs with PSGML </title>
<para> See Nik Clayton's primer for FreeBSD documentation:
<ulink
url="http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html">http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html</ulink>
</para>
</section>
</section>
</section>
<section id="vim">
<title>VIM</title>
<para><ulink
url="http://www.vim.org">http://www.vim.org</ulink></para>
<para>No mention of Emacs is complete without talking about
vi. The <indexterm><primary>vim</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>vim</secondary>
</indexterm>
VIM (Vi IMproved) editor has the functionality of
regular vi, but also has an SGML mode that will
color-coordinate your screen to show where tags are.</para>
<section id="usingvim">
<title>Getting Started</title>
<para>The vim program comes in many parts. There is
the plain vim program, which is compatibile with the
vi program and its commands. Red Hat users will want the vim-common
and vim-minimal packages. Next is the enhanced
<command>vim</command>, which includes the highlighting and other
features of vim over regular vi. Red Hat
users will want vim-enhanced. Last, but certainly not least, is the
X interface, which gives a graphical interface, menus, and mouse
control. To separate this from vim or vi, the command for graphical
access is called <command>gvim</command>.</para>
</section>
<section>
<title>Loading or starting new documents</title>
<para>In both <command>vim</command> and <command>gvim</command> modes,
<filename>.sgml</filename> files will be automatically recognized and
enter into <quote>sgml mode</quote>. A series of known DocBook tags
have been entered into <command>vim</command> and will he highlighted
in brown if a tag is known. If it isn't, it will appear in light blue.
attributes to known tags are in light blue, and values for the
attributes are in pink. From here on, you can use regular <command>vi</command>
commands to navigate and edit.</para>
<para>
While VIM has an XML mode, this mode will not highlight known
and unknown DocBook tags. You can still force VIM into
SGML mode if you like using the <command>:set ft=sgml</command>
command. Note that this will not have any affect on the file
or its contents, only the highlighting within VIM.
</para>
</section>
</section>
<section id="wordperfect">
<title>WordPerfect 9 (Corel Office 2000)</title>
<para><ulink
url="http://www.corel.com/">http://www.corel.com/</ulink></para>
<para>WordPerfect 9 for the MS Windows platform has support
for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML
capabilities.</para>
<para>This is the least expensive of the commercial
applications that support SGML.</para>
</section>
<section id="epcEdit">
<title>epcEdit</title>
<para><ulink
url="http://www.tksgml.de/">http://www.tksgml.de/</ulink></para>
<para>The <indexterm><primary>epcEdit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>epcEdit</secondary>
</indexterm>
epcEdit program allows you to visually edit SGML
files. It has the advantages of not needing to know Emacs or
vi before starting, and is cross-platform, working in both
Windows and Linux. This is a commercial application, and
pricing can be found at
<ulink url="http://www.tksgml.de/pricing.html">http://www.tksgml.de/pricing.html</ulink>
</para>
<para>Along with visual editing, epcEdit will also validate
documents on loading, and on demand by using the <menuchoice
moreinfo="none"><guimenu
moreinfo="none">Document</guimenu><guimenuitem
moreinfo="none">Validate</guimenuitem></menuchoice>
command.</para>
<figure>
<title>epcEdit screen shot</title>
<mediaobject>
<imageobject>
<imagedata format="EPS" fileref="sgeditscreenshot.eps"/>
</imageobject>
<imageobject>
<imagedata format="JPG" fileref="sgeditscreenshot.jpg"/>
</imageobject>
<textobject>
<phrase>The screen shot of the epcEdit program shows a
tree on the left side that has the SGML document in a
hierarchy, while the right side shows the document.
Tags are shown with a grey background.</phrase>
</textobject>
</mediaobject>
</figure>
</section>
<section id="nedit">
<title>nedit</title>
<para><ulink
url="http://nedit.org">http://nedit.org</ulink></para>
<para>To be fair,
<indexterm><primary>nedit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>nedit</secondary>
</indexterm>
nedit is more
for programmers, so it might seem a bit of overkill for new
users and especially non-programmers. All that aside, it's
extremely powerful, allowing for color coding of tags. Unlike
epcEdit, nedit doesn't allow you to automatically insert tags
or automatically validate your code. However, it does allow
for shell commands to be run against the contents of the
window (as opposed to saving the file, then checking). In a
few minutes, I was able to set up <command>nsgmls</command> to
validate the SGML and <command>aspell</command> to do my spell
checking.
<figure>
<title>nedit screen shot</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditscreenshot.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditscreenshot.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>The nedit program can provide line numbers
across the left side of the screen, handy for when
<command>nsgmls</command> complains of errors</phrase>
</textobject>
</mediaobject>
</figure>
</para>
<section id="usingnedit">
<title>Using nedit</title>
<para>For writing new documentation, it is recommended that
you download and use the LDP DocBook template. Once you have
the file, you can start up nedit and begin editing. If the
file is saved with a .sgml extension, nedit will load the file
up with SGML/HTML tags enabled. You can turn this on
explicitly using the
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Language
Mode</guimenuitem><guimenuitem>SGML
HTML</guimenuitem></menuchoice> command. </para>
</section> <!-- New Documents -->
<section id="tipsandtricksnedit">
<title>Tips and tricks with nedit</title>
<para>Since you can feed the contents of your window to
outside programs, you can easily extend nedit to perform
repetitive functions. The example you'll see here is to
validate the SGML code using <command>nsgmls</command>.</para>
<para> Select
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Default
Settings</guimenuitem><guimenuitem>Customize
Menus</guimenuitem><guimenuitem>Shell
Menu...</guimenuitem></menuchoice>. This will bring up the
Shell Command dialog box, with all the shell commands nedit
has listed under the
<menuchoice><guimenu>Shell</guimenu></menuchoice> menu. Under
Menu Entry, enter "SGML Validate". This will be the entry
you'll see on the screen. Under Accelerator, press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
Once this menu item is set up, you can press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>
to have the SGML Validate automatically run. Under Command
Input, select window, and under Command Output, select
dialog. Under Command to Execute, enter nsgmls -sv. Note
that <command>nsgmls</command> has to be in your
<envar>PATH</envar> for this to work properly. </para>
<figure>
<title>Adding shell commands to nedit</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditshellcommand.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditshellcommand.jpg" format="JPG"/>
</imageobject>
</mediaobject>
</figure>
<para> Click <guibutton>OK</guibutton> and you'll now be back
at the main nedit screen. Load up an SGML file, and select
<menuchoice><guimenu>Shell</guimenu><guimenuitem>SGML
Validate</guimenuitem></menuchoice> or press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
The <command>nedit</command> program will fire up and check
the contents of the window. The reason for using -sv is that
the -v tells <command>nsgmls</command> to output the version
of the program, so you'll always get output and know that
<command>nsgmls</command> has run. If all you get is a
version number, then there are no errors with the document.
If there are errors, then they'll be listed in the separate
window for you to see. If you have line numbers turned on
(using
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
Line Numbers</guimenuitem></menuchoice>) then finding the
errors is much simpler, as <command>nsgmls</command> will list
errors by their line number.</para>
<figure>
<title>nsgmls output on success</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditsuccess.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditsuccess.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>If nsgmls reports success, it merely reports the version of nsgmls</phrase>
</textobject>
</mediaobject>
</figure>
</section>
</section>
<section id="morphoneditor">
<title>Morphon XML editor</title>
<para> <ulink url="http://www.morphon.com/xmleditor/index.shtml">http://www.morphon.com/xmleditor/index.shtml</ulink></para>
<para>This is a commerical application that has a free 30 day
license available for download. It is written in Java, allowing
it to run on any platform that has a JVM (that is, works in both
Windows and Linux). The cost is $150USD for a single user
license, and $75USD for a student license.</para>
<para>On the plus sides of XMLEditor is the left side of the
screen shows the heirarchy of the document (starting with Book
and so on). Selecting an item in the list brings you to that
part of the document so you can edit it. The right part of the
screen shows the text without any markup or tags being shown.
If you have external files as ELEMENTS (as the LDP Author Guide
does), XMLEditor will follow the links and load the files, so
you always work on the entire work. On the minus side of this,
you will get errors if a file (like index.xml) is
missing.</para>
</section>
</section>
</chapter>