mirror of https://github.com/tLDP/LDP
738 lines
33 KiB
XML
738 lines
33 KiB
XML
<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
|
|
<H1> 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>
|
|
<xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
|
|
<xml_dtd_pth>/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>
|
|
<?xml version='1.0' encoding='ISO-8859-1'?>
|
|
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'>
|
|
</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 [
|
|
<!ELEMENT test - - (#PCDATA)>
|
|
]</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 [
|
|
<!ELEMENT test - - (#PCDATA)>
|
|
]</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>
|