mirror of https://github.com/tLDP/LDP
Lots of new files--I doubt anything validates, but it's good
to have backups. Eventually these little messages will say something meaningful when the updates are a little more tangible.
This commit is contained in:
parent
33aab5c0a8
commit
2bb56893f9
|
@ -0,0 +1,61 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="aboutthisguide">
|
||||||
|
<title>About this Guide</title>
|
||||||
|
<section id="purpose">
|
||||||
|
<title>About this Guide</title>
|
||||||
|
<para>This document was started on Aug 26, 1999 by Mark
|
||||||
|
F. Komarinski after two day's worth of frustration getting tools
|
||||||
|
to work. If even one LDP author is helped by this, then I did my
|
||||||
|
job.</para>
|
||||||
|
<para>
|
||||||
|
The newest version of this document can be found at the LDP
|
||||||
|
homepage
|
||||||
|
<ulink url="http://www.tldp.org/">http://www.tldp.org</ulink>.
|
||||||
|
The original DocBook, HTML, and other formats can be found there.
|
||||||
|
</para>
|
||||||
|
<para>There are many ways to contribute to the Linux movement
|
||||||
|
without actually writing code. One of the most important is
|
||||||
|
writing documentation, allowing each person to share their
|
||||||
|
knowledge with thousands of others around the world. This Guide
|
||||||
|
is designed to help you get familiar with how the LDP works, and
|
||||||
|
what tools you'll need to write your own HOWTO.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- Because I haven't decided where to put it, the
|
||||||
|
About The LDP
|
||||||
|
section has become an entity. Currently the file starts with a
|
||||||
|
<section>
|
||||||
|
-->
|
||||||
|
&tldp;
|
||||||
|
<!-- End of section about The LDP -->
|
||||||
|
|
||||||
|
<section id="feedback">
|
||||||
|
<title>Feedback</title>
|
||||||
|
<para>Comments on this Guide may be directed to the
|
||||||
|
LDP Author Guide coordinator
|
||||||
|
(<email>mkomarinski@wayga.org</email>).</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="copyrights">
|
||||||
|
<title>Copyrights and Trademarks</title>
|
||||||
|
<para>Copyright 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy</para>
|
||||||
|
<para>
|
||||||
|
Permission is granted to copy, distribute and/or modify this document
|
||||||
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
||||||
|
any later version published by the Free Software Foundation; with no
|
||||||
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||||||
|
Texts. A copy of the license is included in the appendix entitled "GNU
|
||||||
|
Free Documentation License".
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<!-- The Acknowledgements section should be moved to the end according
|
||||||
|
to the LDP Author Guide Text -->
|
||||||
|
&thankyous;
|
||||||
|
|
||||||
|
<!-- Document conventions -->
|
||||||
|
&conventions;
|
||||||
|
|
||||||
|
</chapter>
|
|
@ -0,0 +1,180 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="distribution">
|
||||||
|
<title> Distributing your documentation </title>
|
||||||
|
|
||||||
|
<section id="beforeyoudistribute">
|
||||||
|
<title> Before you distribute </title>
|
||||||
|
<para> Before you distribute your code to millions of potential
|
||||||
|
readers there are a few things you should do. </para>
|
||||||
|
<para> First, be sure to spell-check your document. Most
|
||||||
|
utilities that you would use to write SGML have plug-ins to
|
||||||
|
perform a spell check. If not, there's always the aspell
|
||||||
|
program. </para>
|
||||||
|
<para> Second, get someone to review your documentation for
|
||||||
|
factual correctness. You can also ask for general
|
||||||
|
comments. The documentation that is
|
||||||
|
published by the LDP needs to be as factually correct as
|
||||||
|
possible, as there are millions of Linux users that may be
|
||||||
|
reading it. If you're part of a larger mailing list talking
|
||||||
|
about the subject, ask others from the list to help you
|
||||||
|
out. </para>
|
||||||
|
<para> Third, create a web site where you can distribute your
|
||||||
|
documentation. This isn't required, but is helpful for people to
|
||||||
|
find the original location of your document. </para>
|
||||||
|
|
||||||
|
<section id="validatecode">
|
||||||
|
<title>Validate Your Document</title>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="makingcopyright">
|
||||||
|
<title> Copyright and Licensing issues </title>
|
||||||
|
<para> In order for an LDP document to be accepted by the LDP,
|
||||||
|
it must be licensed to conform to the "LICENSE REQUIREMENTS"
|
||||||
|
section of the LDP Manifesto located at <ulink
|
||||||
|
url="http://www.tldp.org/manifesto.html">http://www.tldp.org/manifesto.html</ulink>.
|
||||||
|
As an author, you may retain the copyright and add other
|
||||||
|
restrictions (for example, you must approve any translations or
|
||||||
|
derivative works). </para>
|
||||||
|
|
||||||
|
<para> We recommend using the <ulink
|
||||||
|
url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation
|
||||||
|
License (GFDL)</ulink> or the <ulink
|
||||||
|
url="http://opencontent.org/openpub/">Open Publication License
|
||||||
|
(OPL)</ulink> <emphasis>without</emphasis> options A and B. If
|
||||||
|
you choose, you can get DocBook markups of both the GNU GPL
|
||||||
|
and the GNU FDL from <ulink url="http://developer.gnome.org/projects/gdp/licenses.html">
|
||||||
|
the GNOME Documentation Project</ulink>. You can then merely
|
||||||
|
include the license in its entirety in your document. Due
|
||||||
|
to its length, you may just want to provide a link
|
||||||
|
to the source.</para>
|
||||||
|
|
||||||
|
<para>If you choose to use a boilerplate copyright, simply copy it
|
||||||
|
into your source code under a section called <quote>Copyright
|
||||||
|
and Licenses</quote> or similar. Also include a copyright
|
||||||
|
statement of your own (since you still own it). If you are a new
|
||||||
|
maintainer of an already-existing HOWTO, you must include the
|
||||||
|
previous copyright statements of the previous author(s) and the
|
||||||
|
dates they maintained that document. </para>
|
||||||
|
|
||||||
|
<para>You'll note that the licensing for the LDP Author Guide
|
||||||
|
requires notification to the author of any derivative works or
|
||||||
|
translations. I also explicitly place any source code (aside
|
||||||
|
from the SGML the Guide was written in) under the GPL. If your
|
||||||
|
HOWTO includes bits of source code that you want others to use,
|
||||||
|
you may do the same.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="submission">
|
||||||
|
<title> Submission to LDP </title>
|
||||||
|
<para> Once your LDP document has been carefully reviewed, you
|
||||||
|
can release your document to the LDP. Send an e-mail with the
|
||||||
|
SGML source code as an attachment (you may gzip it if you like)
|
||||||
|
to <email>submit@en.tldp.org</email>. </para>
|
||||||
|
|
||||||
|
<para> Be sure to include the name of your HOWTO in the subject
|
||||||
|
line, and use the body to outline changes you've made and attach
|
||||||
|
your HOWTO. This allows the maintainers to do their jobs faster,
|
||||||
|
so you will not have to wait for your HOWTO to be updated on the
|
||||||
|
LDP web site. If you don't hear anything in 5 calendar days,
|
||||||
|
please follow up with an e-mail to make sure things are still in
|
||||||
|
process. </para>
|
||||||
|
|
||||||
|
<para>If your HOWTO contains extras, such as graphics or a
|
||||||
|
special catalog, create a.tar.gz file with all the files in it
|
||||||
|
including the .xml source code and mail it as an attachment to
|
||||||
|
the submit list.</para>
|
||||||
|
|
||||||
|
<para>If you are using the LDP CVS tree while developing
|
||||||
|
your document, the LDP will still need to be notified when your
|
||||||
|
document is ready to be published. E-mail should be sent to
|
||||||
|
<email>submit@en.tldp.org</email>. Indicate
|
||||||
|
the title of your document and the relative path to the
|
||||||
|
file(s) in the LDP CVS tree within your message. </para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
To get a CVS account please refer to: ...
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="compilations">
|
||||||
|
<title>Publishing Compilations of LDP Documents</title>
|
||||||
|
<para>
|
||||||
|
If you are interested in publishing a collection of
|
||||||
|
LDP documents, please visit <ulink
|
||||||
|
url="http://www.tldp.org/manifesto.html#pub">http://www.tldp.org/manifesto.html#pub</ulink>
|
||||||
|
for more information.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="crediting-ack">
|
||||||
|
<title>The <quote>Acknowledgements</quote> section</title>
|
||||||
|
|
||||||
|
<para>Your document should have an <quote>Acknowledgements</quote> section,
|
||||||
|
in which you mention everyone who has contributed to your document in
|
||||||
|
any meaningful way. You should include translators and converters, as well as
|
||||||
|
people who have sent you lots of good feedback, perhaps the person who taught
|
||||||
|
you the knowledge you are now passing on, and anybody else who was instrumental
|
||||||
|
in making the document what it is. Most authors put this section at the end
|
||||||
|
of their document.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<para>When someone else assists in the production of an
|
||||||
|
LDP document,
|
||||||
|
you should give them proper attribution, and there are DocBook tags
|
||||||
|
designed to do this. This section will show you the tags you should
|
||||||
|
use, as well as other ways of giving credit where credit is due.
|
||||||
|
Crediting editors is easy - there is already an
|
||||||
|
<sgmltag class="starttag">editor</sgmltag>tag in DocBook.
|
||||||
|
But there are two special cases where you need to credit someone,
|
||||||
|
but DocBook doesn't provide a special tag. These are <emphasis>translators</emphasis>
|
||||||
|
and <emphasis>converters</emphasis>.</para>
|
||||||
|
|
||||||
|
<para>A <emphasis>converter</emphasis> is someone
|
||||||
|
who performs a source code conversion, e.g., from HTML to DocBook SGML.
|
||||||
|
Source code conversions help the LDP achieve long term goals for meta-data,
|
||||||
|
and allow us to produce documentation in many different output formats.</para>
|
||||||
|
|
||||||
|
<para>Translators take your original document and translate it into other
|
||||||
|
human-readable languages, e.g., from English to Japanese, or from German
|
||||||
|
to English. Each translation allows many more people all over the world
|
||||||
|
to make use of your document, and helps Linux achieve the ultimate goal -
|
||||||
|
Total World Domination(tm)!</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
We recommend that
|
||||||
|
you acknowledge converters in the comment for the
|
||||||
|
initial version released in the new format, and
|
||||||
|
we recommend that you credit translators in each
|
||||||
|
version which they have translated.</para>
|
||||||
|
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para> I found an error in an LDP document. Can I fix it? </para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para> Contact the author of the document, or the LDP
|
||||||
|
coordinator at <email>feedback@en.tldp.org</email> and
|
||||||
|
mention the problem and how you think it needs to be
|
||||||
|
fixed. </para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question>
|
||||||
|
<para>But I don't know SGML/Can't get the tools working/Don't
|
||||||
|
like SGML</para>
|
||||||
|
</question>
|
||||||
|
<answer>
|
||||||
|
<para> That's okay. You have the option of writing your first
|
||||||
|
draft of the HOWTO in the format of your choice, then submit
|
||||||
|
that to the LDP. An LDP volunteer will review the document,
|
||||||
|
then convert it into DocBook for you. Once that's done,it will
|
||||||
|
be easier for you to maintain the HOWTO. If you have
|
||||||
|
questions, you can always drop a line to the LDP volunteer or the
|
||||||
|
LDP Docbook list
|
||||||
|
at <email>docbook@en.tldp.org</email>.</para>
|
||||||
|
</answer>
|
||||||
|
</qandaentry>
|
||||||
|
</qandaset>
|
||||||
|
</chapter>
|
|
@ -0,0 +1,49 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="ag-maintain">
|
||||||
|
<title>Maintain</title>
|
||||||
|
|
||||||
|
<section id="sg-maintaining">
|
||||||
|
<title>Maintaining Your HOWTO</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Just because your HOWTO has now been published doesn't mean your
|
||||||
|
job is done. HOWTOs need regular maintenance, to make sure they
|
||||||
|
are up to date, and to improve them in response to readers' ideas
|
||||||
|
and suggestions. A HOWTO is a living, growing body of knowledge,
|
||||||
|
not just a publish-and-forget-it static document.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Add relevent mailing lists to your HOWTO where people
|
||||||
|
can get support. If you have the time, follow these
|
||||||
|
mailing lists yourself to stay up-to-date on the
|
||||||
|
latest information.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Put your email address in the HOWTO, and politely request
|
||||||
|
feedback from your readers. Once you are officially published,
|
||||||
|
you will begin to receive notes with suggestions.
|
||||||
|
Some of these emails will be very valuable. Create a
|
||||||
|
folder in your mail program for
|
||||||
|
incoming suggestions--when the time is right review
|
||||||
|
the folder and make updates to your document. If you
|
||||||
|
are following a related mailing list you may also
|
||||||
|
choose to save a copy of important emails from the list to your
|
||||||
|
this folder.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note><para>
|
||||||
|
Some people who email you will request personal
|
||||||
|
assistance. You should feel free to decline personal
|
||||||
|
assistance if you cannot spare the time. Writing a
|
||||||
|
HOWTO for the LDP does not commit you to a lifetime
|
||||||
|
of free support for anyone on the net; however, do try
|
||||||
|
to reply to all requests and suggest a mailing list that
|
||||||
|
will (hopefully) be able to provide support to your reader.
|
||||||
|
</para></note>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
</chapter>
|
|
@ -0,0 +1,266 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="docbook">
|
||||||
|
<title>DocBook</title>
|
||||||
|
<para>
|
||||||
|
To explain what DocBook is, we must first take a look
|
||||||
|
at what SGML and XML are, and their relationship to DocBook.
|
||||||
|
</para>
|
||||||
|
<para>The Standard Generalized Markup Language (SGML) is a
|
||||||
|
way of embedding information about a document
|
||||||
|
into the text of the document. SGML is not a markup language
|
||||||
|
itself, it is a <quote>metalanguage</quote> from which other markup
|
||||||
|
languages are created (e.g. HTML and DocBook). Documents are stored
|
||||||
|
in SGML format using a specific Document Type Definition--a
|
||||||
|
controlled vocabulary. These documents may then be
|
||||||
|
<quote>transformed</quote> into a variety of other types of documents
|
||||||
|
such as PDFs, HTML pages, plain text (etc!). The advantage of using
|
||||||
|
SGML means you can use an automated transformation to convert your
|
||||||
|
document into whatever format you may need.</para>
|
||||||
|
|
||||||
|
<para>Instead of defining things like colors, font sizes and other specific
|
||||||
|
formatting rules you define the structure of the document. This is
|
||||||
|
done with a series of tags which are wrapped around content.
|
||||||
|
The controlled vocabulary consists of <quote>elements</quote> which
|
||||||
|
describes what the content is. This block
|
||||||
|
of text, for example, is a paragraph. In DocBook notation I have
|
||||||
|
wrapped the block of text with the start tag <para> and then
|
||||||
|
the end tag </para>. In HTML, a sub-set of SGML, this would be
|
||||||
|
done with the element <p>. Although there are many similarities
|
||||||
|
between DocBook and HTML, DocBook contains hundreds of elements and
|
||||||
|
is considered a much more descriptive vocabulary.</para>
|
||||||
|
|
||||||
|
<note><para>Steve
|
||||||
|
Champeon does a great job of explaining this (from an HTML
|
||||||
|
perspective but with an example of DocBook markup) in his article
|
||||||
|
<ulink url="http://hotwired.lycos.com/webmonkey/02/42/index4a.html">The
|
||||||
|
Secret Life of Markup</ulink>.</para></note>
|
||||||
|
|
||||||
|
<para>There are really three parts to an SGML document:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
First there is the content. As a TLDP author it is good to remember
|
||||||
|
that this is the most important piece. Many authors will write the
|
||||||
|
content first and add their markup later. Content may include both
|
||||||
|
plain text and graphics. For more information about writing your
|
||||||
|
content read: FIXME
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
To describe the structure of the content a controlled vocabulary
|
||||||
|
added on top of the content. It is used to distinguish different
|
||||||
|
kinds of content: paragraphs, lists, tables, warnings (and so on).
|
||||||
|
This is also known as document <quote>markup</quote> and is typically
|
||||||
|
what people are referring to when they talk about SGML, XML and HTML.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The rules that
|
||||||
|
define the structure of a document are known as a Document Type
|
||||||
|
Definition (DTD). Depending on what kind of document you are writing,
|
||||||
|
you will use a different set of rules. The rules include the required
|
||||||
|
elements (tagset) and the order in which they must appear.
|
||||||
|
This document was written in
|
||||||
|
DocBook version 4.2 (although that version will likely change over
|
||||||
|
time).
|
||||||
|
For more information about marking up your document read: FIXME
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
Finally the document is transformed to another type of
|
||||||
|
document and formatted for displayed. This is
|
||||||
|
controlled through the Document Style Semantics and Specification
|
||||||
|
Language (DSSSL).
|
||||||
|
The DSSSL tells the program doing the transformation how to convert
|
||||||
|
the raw markup into something that a human can read.
|
||||||
|
</para>
|
||||||
|
<para>For example: The DSSSL instructions may specify
|
||||||
|
that an RTF document should have all
|
||||||
|
<sgmltag>title</sgmltag>s transformed into 14 point
|
||||||
|
bold type; however, the instructions for an HTML
|
||||||
|
document may convert that same <sgmltag>title</sgmltag>
|
||||||
|
into an <h1> HTML element.</para>
|
||||||
|
<para>
|
||||||
|
For more information about transforming your document to other
|
||||||
|
document formats read: FIXME
|
||||||
|
</listitem></para>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The eXtensible Markup Language (XML) is a sub-set of SGML. Like
|
||||||
|
SGML it is also a metalanguage and defines the rules of how a
|
||||||
|
controlled vocabulary (DTD) can be used. Both SGML and XML
|
||||||
|
documents must point to a DTD for the rules about a document's
|
||||||
|
structure. DocBook is a DTD which is available in both SGML and XML
|
||||||
|
formats. Although the element names do not change between the two
|
||||||
|
there are slight differences in how the markup is
|
||||||
|
applied. The LDP has chosen
|
||||||
|
to store its documents in XML format using the DocBook DTD.
|
||||||
|
(Other markup languages are accepted by the LDP. See
|
||||||
|
the FIXME section for more information.)
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="whydocbook">
|
||||||
|
<title>Why DocBook?</title>
|
||||||
|
<para>DocBook provides for more than just formatting. You can
|
||||||
|
automatically build indexes, tables of contents, and links within
|
||||||
|
the document or to outside. You can also transform
|
||||||
|
your DocBook document into a variety of
|
||||||
|
formats including: LaTeX, info, text, HTML, and RTF.
|
||||||
|
From these basic formats, you can
|
||||||
|
then create other formats such as MS Word, PostScript, PDF and
|
||||||
|
so on. If you prefer to work in Lyx you can write in
|
||||||
|
Tex format, export to DocBook and then transform to
|
||||||
|
any of the formats mentioned above.
|
||||||
|
DocBook, unlike other formats, is more concerned about
|
||||||
|
describing a document's structure than detailing how
|
||||||
|
it will be displayed.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Although there are other DTDs used to write documentation,
|
||||||
|
there are a few reasons not to use them.</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
DocBook is the most popular DTD, being
|
||||||
|
used by more than a dozen major open source projects from GNOME
|
||||||
|
to Python to FreeBSD.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
The tools for DocBook are more developed than others.
|
||||||
|
DocBook support is included in most Linux distributions,
|
||||||
|
allowing you to send raw files to be processed at the
|
||||||
|
receiver's end.
|
||||||
|
</para></listitem>
|
||||||
|
<para><listitem>
|
||||||
|
And finally, DocBook has an extensive set of
|
||||||
|
tags (over 300 in all) which is very useful when you
|
||||||
|
are trying to describe the content of a document.
|
||||||
|
(Fortunately for new authors the majority of them do
|
||||||
|
not need to be used for simple documentation.)
|
||||||
|
</para><listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>Still not convinced? Eric Raymond has written a
|
||||||
|
<ulink url="">DocBook Demystification HOWTO</ulink>
|
||||||
|
which may help.
|
||||||
|
FIXME: I'm currently offline--must add the link in for
|
||||||
|
this doc.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="docbookxml">
|
||||||
|
<title>Why XML?</title>
|
||||||
|
<para>
|
||||||
|
While tools for writing XML are not as developed as those
|
||||||
|
for SGML, there are a few reasons why you may want to start
|
||||||
|
writing in XML:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<orderedlist inheritnum="ignore" continuation="restarts">
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
It's the format preferred by The LDP.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Libraries for handling XML files are developing at
|
||||||
|
a rapid pace. These utilities may make it easier
|
||||||
|
for new authoring tools to become available.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Many popular word processing programs are now creating
|
||||||
|
XML output. While it may not be DocBook XML, this does make
|
||||||
|
it easier for application writers to either add DocBook XML
|
||||||
|
support, or provide some method of translating between
|
||||||
|
their format and DocBook XML.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Everyone else is doing it. While this might not be a real
|
||||||
|
reason, it allows the LDP to keep up-to-date with similar
|
||||||
|
projects. Tools, procedures, and issues can be worked out
|
||||||
|
in a common framework.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Still not convinced? Fortunately the LDP does accept
|
||||||
|
a number of other file formats.
|
||||||
|
FIXME: add a link to the list of support file
|
||||||
|
formats
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="docbookintro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<para>DocBook defines a set of markup elements useful for marking
|
||||||
|
up text so that the text can then be transformed into several
|
||||||
|
different formats:
|
||||||
|
<acronym>HTML</acronym>, <acronym>XML</acronym>, <acronym>RTF</acronym>,
|
||||||
|
TeX, and others.</para>
|
||||||
|
|
||||||
|
<para>The idea is to write just once and reach the largest possible number
|
||||||
|
of people with the information.</para>
|
||||||
|
|
||||||
|
<para>Digital information not stored properly tends to get lost.
|
||||||
|
Because DocBook uses standard <acronym>ASCII</acronym> characters,
|
||||||
|
it is easy to index and search DocBook document directly.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The <acronym>SGML</acronym> systems use markups to describe their
|
||||||
|
data. DocBook holds over 300 markup elements each one with several
|
||||||
|
attributes which can assume several values; these can be fixed or defined
|
||||||
|
by the document / style that the author has used.</para>
|
||||||
|
|
||||||
|
<para>Just to remind you, if any changes are made to DocBook's
|
||||||
|
<acronym>DTD</acronym>, it's no longer DocBook.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="acceptedversions">
|
||||||
|
<title>DocBook Versions</title>
|
||||||
|
<para>
|
||||||
|
The LDP supports and accepts documentation in the following formats:
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
XML DocBook version 4.1.2
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
SGML DocBook versions 4.x and 3.1
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
SGML LinuxDoc
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="doctype">
|
||||||
|
<para>When writing your DocBook header, it should look like
|
||||||
|
this:</para>
|
||||||
|
<programlisting format="linespecific">
|
||||||
|
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</sgmltag>
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<!-- add different doctypes for articles, books, etc -->
|
||||||
|
<!-- explain what Doctypes are all about - check the catalog
|
||||||
|
section, I think for more pre-written work. -->
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,102 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="introduction">
|
||||||
|
<title>Authoring TLDP Documents: An Introduction</title>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
This comment can be deleted after an appropriate amount of time.
|
||||||
|
Section 2.1 The LDP
|
||||||
|
Moved this back into Chapter One - About this guide
|
||||||
|
|
||||||
|
Section 2.2, 2.3, 2.4 DocBook and XML
|
||||||
|
Moved this to two other sections: Markup and one of the
|
||||||
|
Appendices on Converting Documents to DocBook XML.
|
||||||
|
-->
|
||||||
|
|
||||||
|
<section id="newauthors">
|
||||||
|
<title>Contributing to The LDP</title>
|
||||||
|
<para>So you want to help out but you're not sure where to start?
|
||||||
|
The easiest way is to find something and document it. Also check
|
||||||
|
the <ulink url="http://tldp.org/authors/unmaint.html">unmaintained HOWTOs</ulink> and see if there is a
|
||||||
|
subject there that you know about and can continue
|
||||||
|
documenting. </para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="process">
|
||||||
|
<title>Summary of The LDP Process</title>
|
||||||
|
<para>If you are a new to the LDP and want to pick up an
|
||||||
|
unmaintained HOWTO or write a new HOWTO document, join the discussion
|
||||||
|
list at
|
||||||
|
<ulink url="http://lists.tldp.org">http://lists.tldp.org</ulink>.
|
||||||
|
This is to make sure the LDP knows who is working on what
|
||||||
|
documentation.</para>
|
||||||
|
|
||||||
|
<para>Once that part is complete, you may write your
|
||||||
|
documentation <emphasis>in the format of your choice</emphasis> and submit a draft to
|
||||||
|
<email>submit@en.tldp.org</email>. The draft will
|
||||||
|
be reviewed by an LDP volunteer. In a few short days you will
|
||||||
|
get the draft and comments from the volunteer. After applying
|
||||||
|
the comments, you may send this version to the submit list
|
||||||
|
again for final submission into the LDP. Review criteria is available
|
||||||
|
in the <ulink url="http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/">LDP Reviewer
|
||||||
|
HOWTO</ulink>. You should review this document yourself before
|
||||||
|
submitting your documentation. (Don't worry, it's pretty short
|
||||||
|
compared to this document.)</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
Reviewers: Please consult the <ulink
|
||||||
|
url="http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/">LDP Reviewer HOWTO</ulink> for information
|
||||||
|
about how to review various forms of LDP documentation.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>At this point, another LDP volunteer will translate your
|
||||||
|
document into DocBook and send you the finished DocBook
|
||||||
|
document. From here on, all submissions to the LDP must be in
|
||||||
|
DocBook format. If you have markup questions, you may ask the
|
||||||
|
volunteer who assisted you, or ask the LDP DocBook list.</para>
|
||||||
|
|
||||||
|
<para>If you choose to start your document off in DocBook, there
|
||||||
|
are plenty of templates to get you started. Check the
|
||||||
|
<ulink url="http://www.tldp.org/authors/index.html#resources">LDP
|
||||||
|
Author's Resources page</ulink> for details.
|
||||||
|
|
||||||
|
FIXME: we're adding templates as appendices to this document.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="mailinglists">
|
||||||
|
<title>Mailing Lists</title>
|
||||||
|
<para>There are a few mailing lists to subscribe to so you can
|
||||||
|
take part in how the LDP works.</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>First is <email>discuss@en.tldp.org</email>, which is the main
|
||||||
|
discussion group of the LDP.</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>Another is the <email>docbook@en.tldp.org</email> list, which is for
|
||||||
|
markup or other questions about DocBook itself. If you run into
|
||||||
|
trouble with a particular markup tag, you can send your question
|
||||||
|
here for answers.</para></listitem>
|
||||||
|
<itemizedlist>
|
||||||
|
|
||||||
|
<para>You can subscribe to either list by sending a "subscribe"
|
||||||
|
message to either <email>discuss-subscribe@en.tldp.org</email> or
|
||||||
|
<email>docbook-subscribe@en.tldp.org</email> with a subject reading
|
||||||
|
<quote>subscribe</quote> (no quotes). To
|
||||||
|
unsubscribe, send an e-mail with the subject of
|
||||||
|
<quote>unsubscribe</quote> to
|
||||||
|
<email>discuss-unsubscribe@en.tldp.org</email> or
|
||||||
|
<email>docbook-unsubscribe@en.tldp.org</email>.</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There is also a mailing list run by OASIS that can also
|
||||||
|
answer DocBook questions. Please see <ulink url="http://docbook.org/mailinglist/index.html">http://docbook.org/mailinglist/index.html</ulink>
|
||||||
|
for more information about the mailing lists. We prefer our own list,
|
||||||
|
but only because the LDP list focuses more on tag usage
|
||||||
|
than other questions such as formatting.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
|
@ -0,0 +1,419 @@
|
||||||
|
<chapter id="propose">
|
||||||
|
<title>Propose</title>
|
||||||
|
|
||||||
|
<section id="sg-subject">
|
||||||
|
<title>Choosing a Subject</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
It's likely that if you are reading the Author Guide, you already have a
|
||||||
|
subject in mind. The idea may have come from your own frustrations in
|
||||||
|
trying to get something to work; or maybe you are already writing (or
|
||||||
|
have written) documentation for work or a client and you want to submit
|
||||||
|
it to the LDP.
|
||||||
|
For example, if you posted a question to a mailing list
|
||||||
|
and it took many posts to resolve the problem--there may be a need for
|
||||||
|
documentation.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Regardless of how your picked your subject, it is
|
||||||
|
important that you feel there is a need for the
|
||||||
|
documentation. It also helps if you can convince a few people on the discuss
|
||||||
|
mailing list that your proposed documentation will be a valuable
|
||||||
|
contribution to the LDP.
|
||||||
|
If someone has requested documentation, or you worked
|
||||||
|
with a mailing list to resolve a problem you should include the details in
|
||||||
|
your proposal to The LDP discuss mailing list. It may help others to
|
||||||
|
understand the need for your specific document.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Now that you've got a subject, you will need to decide the
|
||||||
|
<quote>scope</quote> of the document. It is best if the subject area
|
||||||
|
is:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Clearly defined.</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Know before you begin exactly where the boundaries of your
|
||||||
|
subject area lie. You should not cover the same ground as another
|
||||||
|
HOWTO, and you should try not to leave gaps between your HOWTO
|
||||||
|
and related HOWTOs, either.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Not too broad, and not too narrow.</title>
|
||||||
|
<para>
|
||||||
|
If you try to cover too much information you may sacrifice depth.
|
||||||
|
It is better to cover a small subject area fully than to cover a large subject
|
||||||
|
area poorly. Linux tools are known for doing exactly one
|
||||||
|
thing and doing that one thing <emphasis>well</emphasis>.
|
||||||
|
Similarly, your HOWTO should cover one subject and cover it
|
||||||
|
<emphasis>well</emphasis>.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If your subject matter is very small, it might be better
|
||||||
|
included as part of another HOWTO. This makes it easier
|
||||||
|
for readers to find the HOWTO they need. Search the LDP repository
|
||||||
|
for HOWTOs on related topics, and see if you could place
|
||||||
|
your information in an existing HOWTO.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Undocumented.</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Before documenting a particular subject, check other HOWTOs at the LDP,
|
||||||
|
and see if the topic is already documented. If it is, refer to the
|
||||||
|
other HOWTO instead of rewriting documentation that already exists.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If the HOWTO already in place is insufficient, or needs updating,
|
||||||
|
contact the author and offer to help. LDP authors are usually nice folks.
|
||||||
|
After all, they put in their own valuable time to help people they
|
||||||
|
don't even know. And, they appreciate your help. But, please, don't
|
||||||
|
duplicate work. It causes confusion for everyone.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Pre-approved by the LDP.</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Before you proceed with your HOWTO, post to the discuss list
|
||||||
|
and get some feedback from other LDP volunteers. Checking with the
|
||||||
|
list <emphasis>before</emphasis> you begin can save you headaches
|
||||||
|
<emphasis>later</emphasis>. Trust us on this one.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<note><para>
|
||||||
|
It is a really good idea to join the discuss list, and follow
|
||||||
|
it regularly, even if you never post. It's a good way to stay current
|
||||||
|
on the activities, needs, and policies of the LDP. In fact it
|
||||||
|
should really be considered a pre-requisite to contributing
|
||||||
|
(even though it's not).
|
||||||
|
</para></note>
|
||||||
|
|
||||||
|
<section id="typesofdocs">
|
||||||
|
<!-- Sub-Section added by EJH: August 12, 2003 -->
|
||||||
|
<title>Types of Documents</title>
|
||||||
|
<para>
|
||||||
|
After you've decided what the scope of your document will have you
|
||||||
|
should start to consider the format you will use. There are
|
||||||
|
a number of different kinds of LDP documentation templates:
|
||||||
|
Guides, HOWTOs, mini-HOWTOs, man pages and FAQs. Rahul Sundaram
|
||||||
|
describes the scope of each of these types of documents in the <ulink
|
||||||
|
url="http://tldp.org/FAQ/LDP-FAQ/index.html">Linux Documentation
|
||||||
|
Project (LDP) FAQ</ulink>. Here is a brief overview of what they are
|
||||||
|
with pointers on how you can get started writing your own:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Guides</title>
|
||||||
|
<para>A guide covers a broad subject and is quite long. The Author
|
||||||
|
Guide (this document) is a guide.
|
||||||
|
Other guides include:
|
||||||
|
<ulink
|
||||||
|
url="http://tldp.org/LDP/intro-linux/html/index.html">Introduction to Linux: A hands on
|
||||||
|
guide</ulink>,
|
||||||
|
<ulink url="http://tldp.org/LDP/lkmpg/index.html">The Linux Kernel
|
||||||
|
Module Programming Guide</ulink>, etc. A full list of guides is
|
||||||
|
available from: <ulink url="http://tldp.org/guides.html">Linux Project
|
||||||
|
Documentation Guides</ulink>. Guides use the <quote>book</quote>
|
||||||
|
templates.
|
||||||
|
FIXME: Add links to the templates.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>HOWTOs</title>
|
||||||
|
<para>A HOWTO is typically a set of instructions that outlines,
|
||||||
|
step-by-step, how a specific task is accomplished. Examples of
|
||||||
|
HOWTOs are:
|
||||||
|
<ulink url="http://tldp.org/HOWTO/CDROM-HOWTO/index.html">CDROM-HOWTO</ulink>
|
||||||
|
<ulink
|
||||||
|
url="http://tldp.org/HOWTO/Module-HOWTO/index.html">Module-HOWTO</ulink>.
|
||||||
|
A full list of HOWTOs is available from: <ulink
|
||||||
|
url="http://tldp.org/HOWTO/HOWTO-INDEX/howtos.html">Single List of
|
||||||
|
HOWTOs</ulink> (warning: it's a BIG page). HOWTOs typically use the
|
||||||
|
<quote>article</quote> template and are output to multiple HTML
|
||||||
|
pages by default.
|
||||||
|
FIXME: Add links to the templates.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>mini-HOWTOs</title>
|
||||||
|
<para>A mini-HOWTO is a shorter, more concise version of a HOWTO.
|
||||||
|
They are listed with regular HOWTOs on the LDP site. mini-HOWTOs typically use
|
||||||
|
the <quote>article</quote> template but are output to a single
|
||||||
|
HTML page by default.
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>man pages</title>
|
||||||
|
<para>man (Manual) pages are the standard form of help available for many
|
||||||
|
linux applications and utilities. They can be viewed by typing
|
||||||
|
<command>man applicationname</command> at a prompt. A full list of man
|
||||||
|
pages is available from:
|
||||||
|
<ulink url="http://tldp.org/docs.html#man">Linux Man Pages</ulink>.
|
||||||
|
Since man pages are bundled with software there is no LDP template
|
||||||
|
at this time.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>FAQs</title>
|
||||||
|
<para>FAQs (Frequently Asked Questions) are a list of questions and
|
||||||
|
answers to help prevent new users from asking the same questions
|
||||||
|
over and over again.
|
||||||
|
A full list of FAQs is available from: <ulink
|
||||||
|
url="http://tldp.org/FAQ/">Linux Documentation Project
|
||||||
|
FAQs</ulink>. FAQs typically use the <quote>article</quote>
|
||||||
|
template with some specific DocBook elements to form the
|
||||||
|
Question/Answer structure.
|
||||||
|
FIXME: add links on how to markup an FAQ
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section> <!-- end of types of docs -->
|
||||||
|
</section> <!-- end of choosing a subject -->
|
||||||
|
|
||||||
|
<section id="unmaintained">
|
||||||
|
<title>Unmaintained and Out-of-date Documents</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you wish to become the "owner" for an unmaintained document there are
|
||||||
|
several steps you must go through.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
Contact the original author. Make sure the author no longer
|
||||||
|
wishes to maintain the document in question. Note that the email address
|
||||||
|
shown may no longer be valid. In that case, please try a <ulink
|
||||||
|
url="http://google.com">search</ulink> for the
|
||||||
|
author. If they cannot be found after a <quote>good-faith</quote> effort,
|
||||||
|
let us know (<email>feedback@en.tldp.org</email>).
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
Determine if a more up-to-date copy of the document exists, outside
|
||||||
|
of what is available on the LDP. If so, try to secure a copy for yourself
|
||||||
|
to work on.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
Inform the LDP which document you would like to own, so that we can
|
||||||
|
track who is working on what and prevent duplication of effort. We also
|
||||||
|
suggest that you join the LDP general discussion list
|
||||||
|
(<email>discuss@en.tldp.org</email>). This step is also required for new
|
||||||
|
documents.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
Submit the document to the LDP with any intended modifications. Make
|
||||||
|
sure to continue to reference the original author somewhere within the
|
||||||
|
document (Credits, Revision History, etc.). Once the document is
|
||||||
|
re-submitted, we will remove the entry from the list of unmaintained
|
||||||
|
documents.
|
||||||
|
</para><listitem>
|
||||||
|
<itemizedlist>
|
||||||
|
|
||||||
|
<note><para>Some of unmaintained documents may be outdated, or the content may be
|
||||||
|
covered in another (actively maintained) HOWTO. If that is the situation,
|
||||||
|
contact us (preferably on the discuss mailing list) and let us know.</para></note>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="sg-outline">
|
||||||
|
<title>Developing an Outline</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Before you actually begin writing, prepare an outline.
|
||||||
|
An outline will help you get a clear picture of the subject matter,
|
||||||
|
and allow you to concentrate on one small part of the HOWTO
|
||||||
|
at a time.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Unless your HOWTO is exceptionally small, your outline will probably
|
||||||
|
be multilevel.
|
||||||
|
When developing a multilevel outline, the top level should contain general
|
||||||
|
subject areas, and sub-headings should be more detailed and specific.
|
||||||
|
Look at each level of your outline independently,
|
||||||
|
and make sure it covers all key areas of the subject matter. Sub-headings
|
||||||
|
should cover all key areas of the heading under which they fall.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Each item in your outline should follow the item before it,
|
||||||
|
and lead into the item that comes next. For example, a HOWTO about a particular
|
||||||
|
program shouldn't have a section on <emphasis>configuration</emphasis>
|
||||||
|
before one on <emphasis>installation</emphasis>.</para>
|
||||||
|
|
||||||
|
<para>You may choose to use the following outline for a HOWTO about
|
||||||
|
using a specific program:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>development history</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>where to download the software from</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>how to install the software</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>how to configure the software</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>how to use the software</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>You may find it helpful to try a little <quote>card
|
||||||
|
sorting</quote> at this stage of the writing process. Write all of your mini
|
||||||
|
subject areas onto pieces of paper. Now sort these pieces of paper into
|
||||||
|
main headings and their sub-sections. It may help to shuffle the slips of
|
||||||
|
paper before you start. This will help to give you a fresh set of eyes
|
||||||
|
while working.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When you are comfortable with your outline, look over it once more,
|
||||||
|
with a critical eye. Have you covered every relevant topic in
|
||||||
|
sufficient detail? Have you wandered beyond the scope of the HOWTO?
|
||||||
|
It's a good idea to show your outline to others (including The LDP
|
||||||
|
discuss list) to get some feedback.
|
||||||
|
It's much easier to reorganize your HOWTO at the outline stage
|
||||||
|
than it is to reorganizing your document after writing it.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
You might have noticed a theme developing here.
|
||||||
|
Just like Free software, Free documentation is best when you
|
||||||
|
<quote>release early, release often.</quote> The discuss list includes
|
||||||
|
many experienced LDP authors, and you would be wise to seek their
|
||||||
|
advice when making decisions about your HOWTO.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="research">
|
||||||
|
<!-- Section added by EJH: August 12, 2003 -->
|
||||||
|
<title>Research</title>
|
||||||
|
<para>
|
||||||
|
While you are working on your outline you will most likely research
|
||||||
|
your topic (especially to confirm the document you are about to
|
||||||
|
write doesn't already exist!). Here are a few pointers that will keep
|
||||||
|
you from pulling out your hair later:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Compile your resources as you research.</title>
|
||||||
|
<para>It is almost guarenteed you will not remember where to
|
||||||
|
find a critical piece of information when you need it most. It
|
||||||
|
will help to bookmark important (and even not so important)
|
||||||
|
pages as you go. If the title of the document doesn't describe
|
||||||
|
the information that is relevent to you then you should add
|
||||||
|
notes on why the page is important.
|
||||||
|
If there are two key ideas you may want to bookmark the
|
||||||
|
same page with two different titles.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Assume your most important resource will disappear.</title>
|
||||||
|
<para>The dreaded 404: Page not found. Even if you have
|
||||||
|
bookmarked a page it may not be there when you return to it. If
|
||||||
|
a page contains a really critical piece of information: make a
|
||||||
|
copy. You may do this by creating a text file with the title of
|
||||||
|
the document, the author's name, the page's URL and the text of
|
||||||
|
the page into a text file on your computer. You might also
|
||||||
|
choose to <quote>print</quote> the file to a PDF (this will
|
||||||
|
capture the original URL on the page if you're using a smart
|
||||||
|
browser).</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Start your <quote>Resources</quote> page now.</title>
|
||||||
|
<para>As you find pages of interest add them to a Resources
|
||||||
|
document. You may do this by exporting your bookmarks or by
|
||||||
|
keeping a separate text file with the Resources sorted by
|
||||||
|
sub-category. A little effort now will save you a lot of time
|
||||||
|
later.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Write down subject areas as you go.</title>
|
||||||
|
<para>If you are card sorting you may find it particularly
|
||||||
|
useful to write topic cards as you find pages that cover that
|
||||||
|
specific topic. At the top of the card write the subject area.
|
||||||
|
In the main area of the card write a few notes about what you
|
||||||
|
might cover under this topic--include the titles of pages that
|
||||||
|
contain important information. If a sub-topic gets too big you
|
||||||
|
may want to divide it into multiple cards.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Separate generic information from version-specific
|
||||||
|
information.</title>
|
||||||
|
<para>The day after you finish your HOWTO a new version of the
|
||||||
|
software will be released. Some things, like where to download
|
||||||
|
the software, won't change. Other things will. You may also
|
||||||
|
choose to document old problems with specific software as a way
|
||||||
|
of encouraging people to upgrade their old versions. e.g.
|
||||||
|
<cite>Version X of the software is known for a specific bug.
|
||||||
|
The bug was fixed as of Version Y.</cite>
|
||||||
|
</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title>Save all related emails.</title>
|
||||||
|
<para>People will often have interesting insight into the
|
||||||
|
problem you're writing about. Any questions that are asked
|
||||||
|
about your topic should be addressed in the final document. If
|
||||||
|
you are writing about software make sure to ask people what
|
||||||
|
system they are using if their setup was different from your
|
||||||
|
own. All of these personal experiences with your topic can add
|
||||||
|
greatly to your final documentation.</para>
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
|
@ -0,0 +1,387 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="write">
|
||||||
|
<title>Write</title>
|
||||||
|
|
||||||
|
<setion id="sg-writingstyle">
|
||||||
|
<title>Writing the Text</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Hopefully by this point, your HOWTO has been organized, and bits of raw information
|
||||||
|
have been collected, documented, and inserted into the outline.
|
||||||
|
Good news: You're past the midpoint; it's all downhill from here.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Your next challenge is to massage all of the raw data you've collected
|
||||||
|
into a readable, entertaining, and understandable whole. If you're
|
||||||
|
working from an existing document make sure any new pieces of
|
||||||
|
information are in the best possible places.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
It has taken quite a bit of work to get to the point where you can
|
||||||
|
actually start writing, hasn't it? Well, the hard work begins to pay
|
||||||
|
off for you now. At this stage, you can begin to really use your
|
||||||
|
imagination and creativity to communicate this heap of dry,
|
||||||
|
boring information in your own unique way.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Removed the Politics and the English Language section. It was not
|
||||||
|
gender-neutral and therefore potentially offensive to female
|
||||||
|
authors. Well it was at least off-putting to THIS female
|
||||||
|
author.
|
||||||
|
I have linked to the full text in the resources section.
|
||||||
|
-->
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If it hasn't become painfully obvious yet all of these
|
||||||
|
suggestions are about keeping your documents simple.
|
||||||
|
Your readers are already struggling with new concepts, so don't
|
||||||
|
make them struggle to understand your language.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There are a number of classic guides to writing--many
|
||||||
|
of which are available online.
|
||||||
|
Their language will
|
||||||
|
seem old, but the messages are still valuable to authors today.
|
||||||
|
These are listed in the resources section. Also listed in the
|
||||||
|
resources section are a variety of sites that have
|
||||||
|
information specific to technical writing.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The Author Guide wouldn't be complete without
|
||||||
|
mentioning the Plain Language movement. Although
|
||||||
|
directed at simplifying government documents, <ulink
|
||||||
|
url="http://www.blm.gov/nhp/NPR/pe_toc.html">Writing user-friendly
|
||||||
|
documents</ulink> is quite useful. It includes before and after
|
||||||
|
writing samples. There's also a
|
||||||
|
<ulink
|
||||||
|
url="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html">PlainTrain
|
||||||
|
writing tutorial</ulink>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
And any document that discusses writing for the web wouldn't be complete without
|
||||||
|
a nod toward <ulink url="http://www.useit.com">useit.com</a>.
|
||||||
|
The following articles may be of specific interest:
|
||||||
|
<ulink url="http://www.useit.com/papers/webwriting/">Writing for the
|
||||||
|
Web</ulink>,
|
||||||
|
<ulink url="http://useit.com/alertbox/20030811.html">Information
|
||||||
|
pollution</ulink>, and
|
||||||
|
<ulink url="http://useit.com/alertbox/9703b.html">Be Succinct!
|
||||||
|
(Writing for the Web)</ulink>.
|
||||||
|
There are many, many resources for writing web
|
||||||
|
documents--a quick web search for <quote>web
|
||||||
|
writing</quote> will find lots of resources. (But
|
||||||
|
don't get too distracted--the ultimate goal is to
|
||||||
|
write, not to read about writing!)
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="writing-style">
|
||||||
|
<!-- Section Added by ejh: August 12, 2003 -->
|
||||||
|
<title>Writing Style and Style Guides</title>
|
||||||
|
<para>
|
||||||
|
There are a number of industry style guides which define how language
|
||||||
|
should be used in documents. A common example for American English is
|
||||||
|
the <ulink
|
||||||
|
url="http://www.chicagomanualofstyle.org/">Chicago Manual
|
||||||
|
of Style</ulink>. It defines things like: whether a period (.) should be inside or
|
||||||
|
outside of <quote>quotes</quote>; and the format for a citing
|
||||||
|
another document. A style guide helps to keep documents
|
||||||
|
consistent--most corporations will follow a style guide to
|
||||||
|
format media releases and other promotional material.
|
||||||
|
Style guides mays also define how words should be spelled
|
||||||
|
(is it color or colour?).
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The LDP does not require a specific style
|
||||||
|
guide; however, you should use a consistent style throughout your
|
||||||
|
document. Your document should be spell checked for a single
|
||||||
|
language (e.g. American English vs. British English).
|
||||||
|
The <ulink url="">Reviewer's HOWTO</ulink> currently lists a number of
|
||||||
|
conventions for LDP documents and is as close as it
|
||||||
|
gets to an official LDP Style Guide.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You can save yourself a lot of time in the editing phase if you
|
||||||
|
decide how you will write your document ahead of time. If you are
|
||||||
|
taking over someone else's document you may need to either: modify
|
||||||
|
your own style to fit the current document; or edit the
|
||||||
|
document so that it melds with the style you would like to
|
||||||
|
use from now on.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
From a writing style perspective, use of the
|
||||||
|
first-person in a HOWTO adds to its charm--an attribute most
|
||||||
|
other documentation sorely lacks. Don't be afraid
|
||||||
|
to speak for yourself--use the word <quote>I</quote>.
|
||||||
|
Describe your personal experiences and opinions.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="writing-resources">
|
||||||
|
<title>Online Writing Resources</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In the <quote><link linkend="references-techwriting"
|
||||||
|
endterm="references-techwriting.title"></link></quote>
|
||||||
|
section, you will find a list of resources that cover the subject
|
||||||
|
better than this guide could hope to. Consult them, and follow their
|
||||||
|
advice.
|
||||||
|
</para>
|
||||||
|
</section> <!-- writing-resources -->
|
||||||
|
</setion> <!-- sg-writingstyle -->
|
||||||
|
|
||||||
|
<setion id="sg-editing">
|
||||||
|
<title>Edit and Proofread the Text</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once you've written the text of your HOWTO, it is time
|
||||||
|
to polish and refine it. Good editing can make the
|
||||||
|
difference between a good HOWTO and a great one.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
One of the goals of editing is to remove [extraneous] material that
|
||||||
|
has crept its way into your document.
|
||||||
|
You should go through your HOWTO carefully, and ruthlessly
|
||||||
|
delete anything that doesn't contribute to the reader's understanding
|
||||||
|
of the subject matter. It is natural for writers to go off on tangents
|
||||||
|
while in the process of writing. Now is the time to correct that. It
|
||||||
|
often helps to leave a bit of time between when you write a document
|
||||||
|
and when you edit it.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Make sure that the contents of every section match the title of that
|
||||||
|
section precisely. It's possible that your original subject heading
|
||||||
|
is no longer relevent. If you've strayed from your original heading
|
||||||
|
it could mean one of the following: the original title was poorly
|
||||||
|
worded; the new material should actually go in a different section;
|
||||||
|
or the new material is not really necessary for your document. If you
|
||||||
|
need to change a title, check to see if the original subject heading
|
||||||
|
is still important. If it is make sure that topic is covered somewhere
|
||||||
|
else in the document.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When editing and proofing your work, check for obvious mistakes,
|
||||||
|
such as spelling errors and typos. You should also check for deeper, but
|
||||||
|
less obvious errors as well, such as <quote>holes</quote> in the
|
||||||
|
information. If you are creating a set of instructions it may
|
||||||
|
help to test them on a fresh machine. Sometimes there
|
||||||
|
are packages that need to be installed which you've forgotten to
|
||||||
|
mention in your documentation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When you are completely satisfied with the quality and accuracy of
|
||||||
|
your work, forward it to someone else for third-party proofing.
|
||||||
|
You will be too close to the work to see fundamental flaws.
|
||||||
|
Have others test the instructions as
|
||||||
|
well. Make sure they follow exactly what you have written. Ask anyone
|
||||||
|
who tests your documentation to make specific notes in any places
|
||||||
|
where they didn't follow your instructions (and the reason why they
|
||||||
|
didn't follow them). For example: <quote>I skipped step 2 because I
|
||||||
|
already have the required packages installed.</quote>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In a sense, editing is like code review in software development.
|
||||||
|
Having a programmer review their own code doesn't make much sense,
|
||||||
|
and neither does having a writer edit their own document.
|
||||||
|
Recruit a friend, or write the discuss list
|
||||||
|
to find a volunteer to proofread before submitting your document. You
|
||||||
|
may also want to submit your document to a mailing list that is
|
||||||
|
relevent to your document's topic. List members should be able to
|
||||||
|
help check the facts, clarity of your instructions and language of
|
||||||
|
the document.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
If you are writing in a language in which you are not fluent,
|
||||||
|
find an editor who is. Technical
|
||||||
|
documentation, more than any other type of writing, must use
|
||||||
|
extremely precise grammar and vocabulary. Misuse of language
|
||||||
|
makes your HOWTO less valuable.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="tools">
|
||||||
|
<title>Writing Tools (for the slightly more courageous)</title>
|
||||||
|
<para>
|
||||||
|
As a reminder: you do <emphasis>not</emphasis> need to submit your
|
||||||
|
initial document to the LDP in anything more than plain text! The LDP
|
||||||
|
volunteers will convert your document to DocBook for you. Once it has
|
||||||
|
been converted you will need to maintain your document in DocBook format.
|
||||||
|
The next chapter, Markup, will help you with the maintenance of your
|
||||||
|
document.
|
||||||
|
FIXME: add a link to the next chapter
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="ag-edittools">
|
||||||
|
<title>Editing Tools</title>
|
||||||
|
<para>
|
||||||
|
You may use any word processing, or text editing tool to write your
|
||||||
|
initial document. When you get to the <xref
|
||||||
|
linkend="markup"/> stage you may want to use
|
||||||
|
a text editor which recognizes DocBook files. At a minimum a program
|
||||||
|
which adds syntax highlighting to your markup will make life a lot
|
||||||
|
easier. For a description of editors which can handle DocBook files
|
||||||
|
please skip to <xref linkend="tools-editors"/>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="cvs-brief">
|
||||||
|
<title>Concurrent Versions System (CVS)</title>
|
||||||
|
<para>
|
||||||
|
The LDP is providing CVS access to authors. There are a few
|
||||||
|
good reasons for this:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<orderedlist inheritnum="ignore" continuation="restarts">
|
||||||
|
<listitem>
|
||||||
|
<para> CVS will keep an off-site backup of your documents. In
|
||||||
|
the event that you hand over a document to another author,
|
||||||
|
they can just retrieve the document from CVS and continue
|
||||||
|
on. In the event you need to go back to a previous version of
|
||||||
|
a document, you can retrieve it as well. </para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para> It's great to have many people working on the same
|
||||||
|
document. You can have CVS tell you what changes were made
|
||||||
|
while you were editing your copy by another author, and
|
||||||
|
integrate those changes in. </para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>CVS keeps a log of what changes were made. These logs (and
|
||||||
|
a date stamp) can be placed automatically inside the document
|
||||||
|
when you use some special tags that get processed before the
|
||||||
|
SGML processor. </para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para> It can provide for a way for a program to automatically
|
||||||
|
update the LDP web site with new documentation as it's written
|
||||||
|
and submitted. This is not in place yet, but it is a potential
|
||||||
|
goal. Currently, CVS updates signal the HOWTO coordinator to
|
||||||
|
update the LDP web page, meaning that if you use CVS, you're not
|
||||||
|
required to e-mail your XML code. (Although you do
|
||||||
|
still need to send the submit list an email when you
|
||||||
|
are ready for your document to be published.) </para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para> If you're completely new to CVS, there are a few web pages
|
||||||
|
you may want to look at which can help you out: </para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para> <ulink
|
||||||
|
url="http://cvshome.org/docs/blandy.html">http://cvshome.org/docs/blandy.html</ulink>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para> <ulink
|
||||||
|
url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</ulink></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><ulink
|
||||||
|
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">http://tldp.org/HOWTO/CVS-RCS-HOWTO.html</ulink>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There is also a brief CVS primer in <xref
|
||||||
|
linkend="cvs"/>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You can browse the LDP CVS repository via the web at <ulink
|
||||||
|
url="http://cvsview.tldp.org/">http://cvsview.tldp.org/</ulink>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="getaccount">
|
||||||
|
<title> Getting a CVS account </title>
|
||||||
|
<para> First you'll need to get an account at the LDP's CVS
|
||||||
|
Repository. This is pretty much the root directory that is used
|
||||||
|
by CVS, with various projects (HOWTOs, guides, etc.)
|
||||||
|
created as subdirectories of it. </para>
|
||||||
|
<para>Please fill the form:
|
||||||
|
<ulink url="http://tldp.org/cvs/">
|
||||||
|
http://tldp.org/cvs/</ulink>
|
||||||
|
</para>
|
||||||
|
<para>During filling the form we want you to inform us about
|
||||||
|
your plans, eg. which HOWTO you maintain.
|
||||||
|
</para>
|
||||||
|
<para>Your unique
|
||||||
|
CVSROOT directory will be created and you'll get an e-mail with
|
||||||
|
a response. Remember your password, it will <emphasis>not</emphasis>
|
||||||
|
be sent in the email. When you get your response, log into your CVSROOT
|
||||||
|
and make sure everything is set up properly: </para>
|
||||||
|
|
||||||
|
<screen format="linespecific">
|
||||||
|
<prompt>bash$</prompt> <command>export
|
||||||
|
CVSROOT=:pserver:<replaceable>your_userid</replaceable>@cvs.tldp.org:/cvsroot</command>
|
||||||
|
<prompt>bash$</prompt> <command>cvs -d $CVSROOT login</command>
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
<para> (Replace the <replaceable>your_userid</replaceable> with what
|
||||||
|
you were sent in the response e-mail). </para>
|
||||||
|
<para> You will be asked for your password, and then be given
|
||||||
|
access to the CVS Repository in read-write mode. Once you've
|
||||||
|
used <command moreinfo="none">cvs login</command> once and have
|
||||||
|
been given access to the system, your password is stored in
|
||||||
|
<filename moreinfo="none">.cvspass</filename> and you will not
|
||||||
|
have to use <command moreinfo="none">cvs login</command>
|
||||||
|
again. Just set the CVSROOT and continue on. You can get the
|
||||||
|
entire repository with this command: </para>
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
<prompt>bash$</prompt> <command>cvs get LDP</command>
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
<para> Or you can get the source for your own document with
|
||||||
|
these commands: </para>
|
||||||
|
|
||||||
|
<screen format="linespecific">
|
||||||
|
<prompt>bash$</prompt> <command>cvs get LDP/howto/docbook/YOUR-HOWTO.sgml</command>
|
||||||
|
<prompt>bash$</prompt> <command>cvs get
|
||||||
|
guide/docbook/YOURGUIDE</command>
|
||||||
|
</screen>
|
||||||
|
</section>
|
||||||
|
</section> <!-- cvs -->
|
||||||
|
|
||||||
|
|
||||||
|
<section id="ag-spellcheck">
|
||||||
|
<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 -->
|
||||||
|
</chapter>
|
|
@ -0,0 +1,12 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
Don't forget:
|
||||||
|
http://tldp.org/authors/template/Sample-HOWTO.xml
|
||||||
|
|
||||||
|
supported document types:
|
||||||
|
Linuxdoc SGML; DocBook SGML v4.2, v4.1 or v3.x; and DocBook XML v4.2 or
|
||||||
|
v4.1.2
|
||||||
|
|
||||||
|
HTML headers/footers for HTML output
|
||||||
|
http://www.sagehill.net/docbookxsl/HTMLHeaders.html
|
|
@ -0,0 +1,26 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="tools-edit">
|
||||||
|
<title>Editing tools</title>
|
||||||
|
<para>
|
||||||
|
Editing tools have come a long way in their support for
|
||||||
|
XML (and specifically DocBook). There are two types of
|
||||||
|
editors outlined in this section: text editors (emacs,
|
||||||
|
vim, etc); and word processors (OpenOffice, AbiWord,
|
||||||
|
etc). New authors who are not comfortable working with
|
||||||
|
markup languages should probably choose a word processor
|
||||||
|
that can output DocBook files. For this reason the word
|
||||||
|
processors are listed first.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Although many editors can also validate your DocBook
|
||||||
|
files, this information has been separated into the <xref
|
||||||
|
linkend="tools-validate" /> section.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
&tools-word-processors;
|
||||||
|
&tools-text-editors;
|
||||||
|
|
||||||
|
</section>
|
|
@ -0,0 +1,91 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<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>
|
|
@ -0,0 +1,183 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<!-- Note to Editors:
|
||||||
|
I've tried to convert these instructions from SGML to
|
||||||
|
XML. Please verify they are still correct. I'm offline
|
||||||
|
with no Emacs and no way of installing it. It's a good
|
||||||
|
way to get a lot of writing done, but not a good way to
|
||||||
|
write software-specific instructions. :)
|
||||||
|
-->
|
||||||
|
<section id="psgml">
|
||||||
|
<title>Emacs (PSGML)</title>
|
||||||
|
<indexterm> <primary>psgml</primary> </indexterm>
|
||||||
|
<indexterm> <primary>Emacs</primary> </indexterm>
|
||||||
|
<indexterm> <primary>Editors</primary>
|
||||||
|
<secondary>Emacs</secondary> </indexterm>
|
||||||
|
<indexterm> <primary>Editors</primary>
|
||||||
|
<secondary>psgml</secondary> </indexterm>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<ulink url="http://www.lysator.liu.se/~lenst/about_psgml/">
|
||||||
|
http://www.lysator.liu.se/~lenst/about_psgml/
|
||||||
|
</ulink>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para><application>Emacs</application> has an SGML
|
||||||
|
writing mode called <application>psgml</application> that is a
|
||||||
|
major mode designed for editing SGML and XML documents. It
|
||||||
|
provides:
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
<quote>syntax highlighting</quote> or <quote>pretty
|
||||||
|
printing</quote> features that make the tags stand out
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
a way to insert tags other than typing them by hand
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
and the ability to validate your document while writing
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For users of Emacs, it's a great way to go.
|
||||||
|
PSGML works with DocBook, LinuxDoc and other DTDs equally well.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="emacs-psgml-install">
|
||||||
|
<title>Verifying PSGML is Installed</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>
|
||||||
|
|
||||||
|
<tip><para>
|
||||||
|
If you don't have PSGML installed now might be a good
|
||||||
|
time to upgrade Emacs. The rest of these instructions
|
||||||
|
will assume you have PSGML installed.
|
||||||
|
</para></tip>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="emacs-config">
|
||||||
|
<title>Configuring Emacs for Use With PSGML</title>
|
||||||
|
<para>
|
||||||
|
If you want GNU Emacs to enter PSGML mode when you open
|
||||||
|
an <filename class="extension">.xml</filename> file, it
|
||||||
|
will need to be able to find the DocBook DTD files.
|
||||||
|
If your distribution already had PSGML set up for use
|
||||||
|
with GNU Emacs, you probably won't need to do anything.
|
||||||
|
Otherwise, check the section on
|
||||||
|
<xref linkend="config-catalogs" />.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
moved catalog exporting to a generic section.
|
||||||
|
I'm trying to make each section only deal with its own
|
||||||
|
information instead of information being repeated times
|
||||||
|
each editor. If there's even more than can be stripped
|
||||||
|
out of the (very long) emacs section, please feel free to
|
||||||
|
hack away. Maybe there's even another HOWTO that explains
|
||||||
|
how to set up Emacs for use with SGML/XML files? I've
|
||||||
|
actually done a fair amount of hacking, so things may
|
||||||
|
already be a little more balanced.
|
||||||
|
-->
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<!--
|
||||||
|
not sure what the DocBook markup is for "mode"s
|
||||||
|
I've used <application> above, but I doubt this is right.
|
||||||
|
-->
|
||||||
|
Once you've configured your system to use PSGML you will
|
||||||
|
need to override Emacs' default sgml-mode with the
|
||||||
|
psgml-mode. This can be done by configuring your
|
||||||
|
<filename>.emacs</filename> file. After you've edited the
|
||||||
|
configuration file you will need to restart Emacs.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
the following entity is configuration information for
|
||||||
|
the .emacs file. I think it should at least be a figure
|
||||||
|
but I'm hoping there's a better resource that we can just
|
||||||
|
point to for this information.
|
||||||
|
-->
|
||||||
|
&emacs-psgml-mode;
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="emacs-new-file">
|
||||||
|
<title>Creating New DocBook XML Files</title>
|
||||||
|
<para>
|
||||||
|
There are a number of steps to creating a new DocBook XML
|
||||||
|
file in Emacs.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
Create a new file with an
|
||||||
|
<filename class="extension">xml</filename>
|
||||||
|
extension.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
On the first line of the file enter the doctype for the
|
||||||
|
version of DocBook that you would like to use.
|
||||||
|
If you're not sure what a doctype is all about, check <xref
|
||||||
|
linkend="doctype" />
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><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 <computeroutput>Parsing prolog...done</computeroutput>
|
||||||
|
in the minibuffer.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><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">e</keycap>
|
||||||
|
</keycombo>
|
||||||
|
RETURN
|
||||||
|
<!-- FIXME not sure what the markup is for RETURN re.
|
||||||
|
keycombos -->
|
||||||
|
|
||||||
|
to automagically insert the parent element for your
|
||||||
|
document. (New authors are typically writing
|
||||||
|
<sgmltag>article</sgmltag>s.)
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
If things are working correctly, you should see new tags
|
||||||
|
for the parent element for your document right after the
|
||||||
|
document type declaration. In other words you should now
|
||||||
|
see two extra tags:
|
||||||
|
<sgmltag class="starttag">article</sgmltag>
|
||||||
|
and
|
||||||
|
<sgmltag class="endtag">article</sgmltag>
|
||||||
|
in your document.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
|
@ -0,0 +1,343 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="tools-text-editors">
|
||||||
|
<title>Text Editors</title>
|
||||||
|
|
||||||
|
<caution><para>
|
||||||
|
The tools outlined in this section allow you to work with
|
||||||
|
the DocBook tags directly. If you are not comfortable
|
||||||
|
working with markup languages you may want to use a word
|
||||||
|
processor instead. Word processors that support DocBook
|
||||||
|
are described in <xref linkend="tools-word-processors"
|
||||||
|
/>.
|
||||||
|
</para></caution>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you are comfortable working with markup languages and
|
||||||
|
text editors, you'll probably want to customize your
|
||||||
|
current editor of choice to handle DocBook files. Below
|
||||||
|
are some of the more common text editors that can, with
|
||||||
|
some tweaking, handle DocBook files.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
The Emacs section is long, and not really the forte of
|
||||||
|
this vim user. It's been hacked into a more resonable
|
||||||
|
length, but definitely needs some TLC from a Real Emacs
|
||||||
|
User.
|
||||||
|
-->
|
||||||
|
&configure-emacs;
|
||||||
|
|
||||||
|
<section id="vim">
|
||||||
|
<title>VIM</title>
|
||||||
|
<indexterm><primary>vim</primary></indexterm>
|
||||||
|
<indexterm>
|
||||||
|
<primary>Editors</primary>
|
||||||
|
<secondary>vim</secondary>
|
||||||
|
</indexterm>
|
||||||
|
<para>
|
||||||
|
<ulink url="http://www.vim.org">http://www.vim.org</ulink>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
No mention of <application>Emacs</application> is complete
|
||||||
|
without talking about <application>vi</application>.
|
||||||
|
The <application>VIM</application> (Vi IMproved)
|
||||||
|
editor has the functionality of
|
||||||
|
regular vi and includes <quote>syntax
|
||||||
|
highlighting</quote> of tags.</para>
|
||||||
|
|
||||||
|
<section id="usingvim">
|
||||||
|
<title>Getting Started</title>
|
||||||
|
<para>
|
||||||
|
There are many versions of <application>vi</application>.
|
||||||
|
New authors will likely want one of the more
|
||||||
|
feature-packed versions for syntax highlighting and
|
||||||
|
a graphical interface including mouse control.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Red Hat users will want the following packages:
|
||||||
|
vim-common, vim-minimal and vim-enhanced.
|
||||||
|
Debian users will want the following package: vim.
|
||||||
|
For an X interface (including <acronym>GUI</acronym> menus and
|
||||||
|
mouse control) users will want
|
||||||
|
<applicationa>gvim</application>. The g in gvim is for
|
||||||
|
<quote>Graphical</quote>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="vim-new-file">
|
||||||
|
<title>Creating New DocBook XML Files</title>
|
||||||
|
<para>
|
||||||
|
In both <application>vim</application> and
|
||||||
|
<application>gvim</application>, <filename
|
||||||
|
class="extension">.xml</filename> files will be
|
||||||
|
recognized and enter into <quote>SGML mode</quote>.
|
||||||
|
A series of known DocBook tags and attributes have
|
||||||
|
been entered into <application>vim</application>
|
||||||
|
and will be highlighted one color if the name is known
|
||||||
|
and another if it is not (e.g. yellow for a known tag and
|
||||||
|
light blue for one that is not).
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Having the
|
||||||
|
correct document type declaration at the top of your
|
||||||
|
document should add the syntax highlighting.
|
||||||
|
If you do not see this highlighting you will need to
|
||||||
|
force VIM into SGML mode (even for XML files) using the
|
||||||
|
command <command>:set ft=sgml</command>. If you are
|
||||||
|
working with multiple files for a single XML document you
|
||||||
|
can add your document type in <-- comments --> to
|
||||||
|
the top of the file to get the correct syntax
|
||||||
|
highlighting (you will need to restart the program to see
|
||||||
|
the change in highlighting).
|
||||||
|
</para>
|
||||||
|
</section> <!-- vim-new-file -->
|
||||||
|
</section> <!-- vim -->
|
||||||
|
|
||||||
|
<section id="epcEdit">
|
||||||
|
<title>epcEdit</title>
|
||||||
|
<indexterm><primary>epcEdit</primary></indexterm>
|
||||||
|
<indexterm>
|
||||||
|
<primary>Editors</primary>
|
||||||
|
<secondary>epcEdit</secondary>
|
||||||
|
</indexterm>
|
||||||
|
<para>
|
||||||
|
<ulink url="http://www.tksgml.de/">
|
||||||
|
http://www.tksgml.de/</ulink>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The epcEdit program allows you to edit XML 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>
|
||||||
|
|
||||||
|
<!-- replace this figure with one that shows an XML file -->
|
||||||
|
<!-- FIXME -->
|
||||||
|
<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 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>
|
||||||
|
<indexterm><primary>nedit</primary></indexterm>
|
||||||
|
<indexterm>
|
||||||
|
<primary>Editors</primary>
|
||||||
|
<secondary>nedit</secondary>
|
||||||
|
</indexterm>
|
||||||
|
<para>
|
||||||
|
<ulink url="http://nedit.org">
|
||||||
|
http://nedit.org</ulink>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
To be fair, 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 syntax highlighting. 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).
|
||||||
|
|
||||||
|
<!-- FIXME replace this screen shot with one that shows an
|
||||||
|
XML file instead of an SGML file -->
|
||||||
|
<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>When you open your DocBook file nedit should already
|
||||||
|
have syntax highlighting enabled. If it does not you can
|
||||||
|
turn it on explicitly using:
|
||||||
|
<menuchoice>
|
||||||
|
<guimenu>Preferences</guimenu>
|
||||||
|
<guimenuitem>Language Mode</guimenuitem>
|
||||||
|
<guimenuitem>SGML HTML</guimenuitem>
|
||||||
|
</menuchoice>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you have line numbers turned on (using
|
||||||
|
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
|
||||||
|
Line Numbers</guimenuitem></menuchoice>) then finding
|
||||||
|
validation errors is much simpler.
|
||||||
|
<application>nsgmls</application>, the validation tool
|
||||||
|
we'll use, lists errors by their line number.</para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="nedit-scripting">
|
||||||
|
<title>Configuring 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 your document using
|
||||||
|
<application>nsgmls</application>.
|
||||||
|
For more information about nsgmls and validating
|
||||||
|
documents please read <xref linkend="tools-validate" />.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!-- Make sure the guimenu markup is consistent and correct. -->
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><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.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
Under
|
||||||
|
Menu Entry, enter "Validate DocBook". This will be the entry
|
||||||
|
you'll see on the screen.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
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 Validate DocBook automatically run.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
Under Command
|
||||||
|
Input, select window, and under Command Output, select
|
||||||
|
dialog.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
Under Command to Execute, enter
|
||||||
|
<command>nsgmls
|
||||||
|
<parameter>-sv</parameter></command>. Using
|
||||||
|
<parameter>-v</parameter> outputs the version number
|
||||||
|
is output to the screen so that you know the command
|
||||||
|
has run.
|
||||||
|
</para>
|
||||||
|
<note><para>Note
|
||||||
|
that <command>nsgmls</command> has to be in your
|
||||||
|
<envar>PATH</envar> for this to work properly.
|
||||||
|
</note></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
Click <guibutton>OK</guibutton> and you'll now be back
|
||||||
|
at the main nedit screen. Load up an XML file, and select
|
||||||
|
<menuchoice><guimenu>Shell</guimenu><guimenuitem>Validate
|
||||||
|
DocBook</guimenuitem></menuchoice> or press
|
||||||
|
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
The <command>nedit</command> program will fire up and check
|
||||||
|
the contents of the window.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
If all you see is a version number for nsgml then your
|
||||||
|
document is valid. Any errors are reported by line
|
||||||
|
number in your document.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<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 which is currently
|
||||||
|
avaible for free (with an optional user registration).
|
||||||
|
It is written in Java, allowing it to run on any platform
|
||||||
|
that has a JVM (that is, works in both
|
||||||
|
Windows and Linux).
|
||||||
|
</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 is missing.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
|
@ -0,0 +1,558 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="transformations">
|
||||||
|
<title>Transformations</title>
|
||||||
|
<warning><para>
|
||||||
|
This section is about how to transform documents
|
||||||
|
from DocBook to other formats. If you do not want
|
||||||
|
to transform documents on your own computer you may
|
||||||
|
<emphasis>skip this section</emphasis>. If you are
|
||||||
|
a (really) new author and afraid of markup
|
||||||
|
languages, definitely skip this section.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
You do not ever need to transform documents before
|
||||||
|
submitting to the LDP. The LDP volunteers have a
|
||||||
|
system which transforms your DocBook file into
|
||||||
|
HTML, PDF and plain text formats. There, you've
|
||||||
|
been warned.
|
||||||
|
</para></warning>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Still here? Great! Transformations are a pretty
|
||||||
|
basic requirement to get what you've written from a
|
||||||
|
messy tag-soup into something that can be read.
|
||||||
|
This section will help you get your system
|
||||||
|
setup and ready to transform your latest document
|
||||||
|
into other formats. This is very useful is you want
|
||||||
|
to <emphasis>see</emphasis> your document before
|
||||||
|
you release it to the world. [Editor's note: Dare
|
||||||
|
I say it's virtually a requirement for any sane Editor?]
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
There are currently two ways to transform your
|
||||||
|
document: Document Style and Semantics
|
||||||
|
Specification Language (DSSSL); and XML Style sheets
|
||||||
|
*** (XSLT). Although the LDP web site uses DSSSL to
|
||||||
|
convert documents you can use XSLT if you want.
|
||||||
|
[Editor's note: the XSLT is probably easier for the
|
||||||
|
average newbie. The Editor can say that because she
|
||||||
|
is an average newbie that uses XSLT.]
|
||||||
|
<!-- Editors: you know the drill. A square bracket
|
||||||
|
is as good as a deleted bracket. ;) -->
|
||||||
|
FIXME!
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="dtd">
|
||||||
|
<title>DocBook DTD</title>
|
||||||
|
<para>
|
||||||
|
<indexterm><primary>DocBook DTD</primary></indexterm>
|
||||||
|
The DocBook DTD defines the structure of a DocBook
|
||||||
|
document. It contains rules about how the elements
|
||||||
|
may be used; and what the elements ought to be
|
||||||
|
describing. For example: it is the DocBook DTD which
|
||||||
|
states all <sgmltag>warning</sgmltag>s are to
|
||||||
|
<emphasis>warn</emphasis> the reader (this is the
|
||||||
|
definition of the element); and may not contain plain
|
||||||
|
text (this is the content model--and the bit which
|
||||||
|
forces you to wrap your warning text in a
|
||||||
|
<smgltag>para</sgmltag> or perhaps a list).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<caution><para>
|
||||||
|
It is important that you download the version(s)
|
||||||
|
that match your document. You may want to configure
|
||||||
|
your system now to deal with <quote>all</quote>
|
||||||
|
DocBook DTDs if you are going to be editing older
|
||||||
|
LDP documents. If you are a new author, you only
|
||||||
|
need the first one listed: XML DTD for DocBook
|
||||||
|
version 4.2.
|
||||||
|
</para></caution>
|
||||||
|
|
||||||
|
<para>The XML DTD is available from <ulink
|
||||||
|
url="http://www.oasis-open.org/docbook/xml/4.2">http://www.oasis-open.org/xml/4.2/</ulink>.
|
||||||
|
The LDP prefers this version of the DocBook DTD.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you are going to be working with SGML versions
|
||||||
|
of DocBook you will need one (or both) of:
|
||||||
|
<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>
|
||||||
|
|
||||||
|
<warning><para>
|
||||||
|
Do not modify these DTD files. Please feel free to open
|
||||||
|
them and look around at how DocBook
|
||||||
|
<emphasis>really</emphasis> works (it's actually
|
||||||
|
pretty cool inside a DTD file). Unfortunately if
|
||||||
|
you modify these files your document may no longer
|
||||||
|
validate against the actual Document Type
|
||||||
|
Definition for DocBook and chaos may ensue.
|
||||||
|
<!-- ejh: really I should have supper right about
|
||||||
|
now I'm getting less and less coherent. Please edit
|
||||||
|
me back into submission, thanks! :) -->
|
||||||
|
</para></warning>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dsssl">
|
||||||
|
<para>
|
||||||
|
There are three basic requirements to transform a
|
||||||
|
document using DSSSL:
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
The Document Style and Semantics Specification
|
||||||
|
Language files (these are plain text files).
|
||||||
|
<xref linkend="dsssl" />
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
The Document Type Definition file which matches
|
||||||
|
the DOCTYPE of your document (this is a plain
|
||||||
|
text file).
|
||||||
|
<xref linkend="dtd" />
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
A processor to do the actual work.
|
||||||
|
<xref linkend="jade" />
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<title>DSSSL</title>
|
||||||
|
<para>There are two versions of the Document Style
|
||||||
|
Semantics and Specification Language used by the LDP to transform
|
||||||
|
documents from your raw DocBook files into other
|
||||||
|
formats (which are then published on the Web). The LDP
|
||||||
|
version of the style sheets requires the Norman Walsh
|
||||||
|
version--which basically means if you're using DSSSL
|
||||||
|
the Norman Walsh version can be considered a requirement
|
||||||
|
for system setup.</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
|
||||||
|
<sgmltag>title</sgmltag> tag into an
|
||||||
|
<h1> HTML tag, 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>
|
||||||
|
|
||||||
|
<!-- duplicated from elsewhere in the guide -->
|
||||||
|
&ldp-dsssl;
|
||||||
|
|
||||||
|
<section id="processors">
|
||||||
|
<title>DSSSL Processors</title>
|
||||||
|
<section id="jade">
|
||||||
|
<title>Jade</title>
|
||||||
|
<para>
|
||||||
|
<indexterm><primary>jade</primary></indexterm>
|
||||||
|
There are two versions of the Jade processor: the
|
||||||
|
original version by James Clark; and an open-source
|
||||||
|
version of approximately the same program.
|
||||||
|
You only need one
|
||||||
|
of these programs. It should be installed
|
||||||
|
<emphasis>after</emphasis> the DTD and DSSSL have
|
||||||
|
been <quote>installed.</quote>
|
||||||
|
</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> <!-- cygnus -->
|
||||||
|
</section> <!-- jadewrappers -->
|
||||||
|
</section> <!-- jade -->
|
||||||
|
</section> <!-- dsssl -->
|
||||||
|
|
||||||
|
<section id="libxslt">
|
||||||
|
<title>libxslt</title>
|
||||||
|
<para>There are alternatives to DSSSL and Jade/OpenJade.</para>
|
||||||
|
<!-- moved from another part of the guide -->
|
||||||
|
&ldp-xsl;
|
||||||
|
</section>
|
||||||
|
</section> <!-- processors -->
|
||||||
|
|
||||||
|
<para>The process of producing output and generating indexes is
|
||||||
|
repetitive and error prone. To make things easier, some scripts are
|
||||||
|
included here to facilitate this work. Customize and use them at
|
||||||
|
will.</para>
|
||||||
|
|
||||||
|
<section id="tools-compile">
|
||||||
|
<title>Compiling the sources</title>
|
||||||
|
|
||||||
|
<indexterm>
|
||||||
|
<primary>tools</primary>
|
||||||
|
<secondary>compiling the sources</secondary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>The <command>compiles-sgml</command> script is a set of grouped
|
||||||
|
commands. As parameters, use the
|
||||||
|
<glossterm><acronym>SGML</acronym></glossterm> file and the output
|
||||||
|
format you want.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The script included below supports the following formats:
|
||||||
|
<glossterm><acronym>XML</acronym></glossterm>,
|
||||||
|
<glossterm><acronym>HTML</acronym></glossterm>, TeX,
|
||||||
|
<glossterm><acronym>RTF</acronym></glossterm>,
|
||||||
|
<glossterm>PS</glossterm>, <glossterm>DVI</glossterm> and mirrored PS,
|
||||||
|
ideal for the creation of photolithographs.</para>
|
||||||
|
|
||||||
|
<para>The generation of the indices is made automatically by the script
|
||||||
|
<filename>collateindex.pl</filename><footnote>
|
||||||
|
<para>More information about indexes are available at <ulink
|
||||||
|
url="http://nwalsh.com/docbook/dsssl/doc/indexing.html">the page about
|
||||||
|
index of Norman Walsh</ulink>.</para> </footnote>, which should be
|
||||||
|
installed in your system. </para>
|
||||||
|
|
||||||
|
<para>Besides the commands below, which generate the outputs in different
|
||||||
|
formats, there are other tools from <trademark>Cygnus</trademark> for making
|
||||||
|
the direct conversion. The tools can be obtained from <ulink
|
||||||
|
url="http://sourceware.cygnus.com/docbook-tools/">Cygnus</ulink>.</para>
|
||||||
|
|
||||||
|
<para>The list below is available <ulink
|
||||||
|
url="compiles-sgml">here</ulink>.</para>
|
||||||
|
|
||||||
|
<para>Here is also available a version of <ulink
|
||||||
|
url="collateindex.pl"><filename>collateindex.pl</filename></ulink>.</para>
|
||||||
|
|
||||||
|
<example id="listing-compile-sgml">
|
||||||
|
<title>Script compiles-sgml</title>
|
||||||
|
<programlisting>
|
||||||
|
&example-compile-sgml;
|
||||||
|
</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<indexterm>
|
||||||
|
<primary>tools</primary>
|
||||||
|
<secondary>compiling sources</secondary>
|
||||||
|
<tertiary>compile-sgml</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
|
||||||
|
<para>A similar script can be modified by creating a
|
||||||
|
<filename>Makefile</filename> and optimizing some functions.</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="toc-articles">
|
||||||
|
<title>Inserting a summary on the initial articles page</title>
|
||||||
|
|
||||||
|
<indexterm>
|
||||||
|
<primary>tools</primary>
|
||||||
|
<secondary>articles</secondary>
|
||||||
|
<tertiary>summary</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>A feature that might be valuable in some cases is the insertion
|
||||||
|
of the summary on the initial page of an article. DocBook articles
|
||||||
|
do not include it as a standard feature.</para>
|
||||||
|
|
||||||
|
<para>To enable this, it is necessary to modify
|
||||||
|
the stylesheet file.</para>
|
||||||
|
|
||||||
|
<para>The example below describes the process, and its use is shown
|
||||||
|
in <xref linkend="listing-compile-sgml"/>.</para>
|
||||||
|
|
||||||
|
<example>
|
||||||
|
<title>Stylesheet to insert summaries in articles</title>
|
||||||
|
<programlisting>
|
||||||
|
&dsl-example;
|
||||||
|
</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="automatic-indexes">
|
||||||
|
<title>Inserting indexes automatically</title>
|
||||||
|
|
||||||
|
<indexterm>
|
||||||
|
<primary>tools</primary>
|
||||||
|
<secondary>indexes</secondary>
|
||||||
|
<tertiary>automatic generation</tertiary>
|
||||||
|
<seealso>edition, index</seealso>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Although DocBook has markups for the composition of them, indexes
|
||||||
|
are not generated automatically. The <command>collateindex.pl</command>
|
||||||
|
command allows indexes to be
|
||||||
|
generated automatically.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The way to use this script is described bellow and a practical
|
||||||
|
example can be seen previously in this document (see <xref
|
||||||
|
linkend="listing-compile-sgml"/>).</para>
|
||||||
|
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Process the document with <application>jade</application>
|
||||||
|
using the style to <glossterm><acronym>HTML</acronym></glossterm>
|
||||||
|
with the option <option>-V html-index</option>.</para>
|
||||||
|
<informalexample>
|
||||||
|
<screen><prompt>$</prompt> <command>jade</command> <option>-t sgml -d html/docbook.dsl -V html-index document.sgml</option></screen>
|
||||||
|
</informalexample>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Generate the <filename>index.sgml</filename> file with
|
||||||
|
<command>collateindex.pl</command>.
|
||||||
|
</para>
|
||||||
|
<informalexample>
|
||||||
|
<screen><prompt>$</prompt> <command>perl</command> <option>collateindex.pl -o index.sgml HTML.index</option></screen>
|
||||||
|
</informalexample>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para>For the above example to work, it's necessary to define an
|
||||||
|
<glossterm>external entity</glossterm> by calling the file
|
||||||
|
<filename>index.sgml</filename>.</para>
|
||||||
|
|
||||||
|
<example id="ex-entity-external-index">
|
||||||
|
<title>Configuring an external entity to include the index</title>
|
||||||
|
<programlisting>
|
||||||
|
<sgmltag class="starttag">!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
|
||||||
|
|
||||||
|
<!-- Insertion of the index -->
|
||||||
|
<!entity index SYSTEM "index.sgml">
|
||||||
|
]</sgmltag>
|
||||||
|
</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<para>See also <xref linkend="encoding-index"/> for information on how to
|
||||||
|
insert necessary information on the text.</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>Remember that if you're trying to get Tables of Contents
|
||||||
|
or Indexes on PS or PDF output you'll need to run <application
|
||||||
|
moreinfo="none">jadetex</application> or <application
|
||||||
|
moreinfo="none">pdfjadetex</application> at least three
|
||||||
|
times. This is required by <application
|
||||||
|
moreinfo="none">TeX</application> but not by
|
||||||
|
DocBook or related applications.</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
</section> <!-- transformations -->
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,826 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<chapter id="tools-validate">
|
||||||
|
<!-- this chapter doesn't flow well-fix the order of hte
|
||||||
|
sections. -->
|
||||||
|
<section id="configurations">
|
||||||
|
<title>Configuration needed </title>
|
||||||
|
<indexterm zone="configurations">
|
||||||
|
<primary>configurations</primary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<section id="config-catalog">
|
||||||
|
<para>The identifier systems used by <acronym>SGML</acronym> and
|
||||||
|
by some tools
|
||||||
|
are based on catalogs that perform the translation of these
|
||||||
|
identifiers to files that hold the necessary definitions.</para>
|
||||||
|
|
||||||
|
<para>The section on tailoring a catalog (see <xref
|
||||||
|
linkend="making-catalogs"/>) will give more details about these
|
||||||
|
files.</para>
|
||||||
|
|
||||||
|
<!-- from the EMACS section -->
|
||||||
|
<para>
|
||||||
|
<!-- make this paragraph shorter and tighter -->
|
||||||
|
To verify if whether or not your system knows where to
|
||||||
|
find its DocBook DTDs you will need to view the list
|
||||||
|
of your system's
|
||||||
|
environmental variables. This can be done by typing
|
||||||
|
<command>printenv</command> at a prompt.
|
||||||
|
Look for SGML_CATALOG_FILES. If it is not set, or does not
|
||||||
|
point to the correct directory for the DocBook DTD files
|
||||||
|
then you will need to set the correct directory.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This list of files is stored in a catalog.
|
||||||
|
Even though we are working with XML files, Emacs stores this
|
||||||
|
information in the SGML_CATALOG_FILES environmental
|
||||||
|
variable. You will need to export this variable with the
|
||||||
|
correct location for your DTD files. If you don't already
|
||||||
|
have a copy of the DTD files for DocBook, please read
|
||||||
|
<xref linkend="dtds" />.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once you've found your DTD files
|
||||||
|
you can export their location so that programs
|
||||||
|
(specifically Emacs) know where to find them:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<screen format="linespecific">
|
||||||
|
<prompt>bash$</prompt>
|
||||||
|
<command>export
|
||||||
|
SGML_CATALOG_FILES=
|
||||||
|
<variable>/usr/lib/sgml/catalog</variable></command>
|
||||||
|
</screen>
|
||||||
|
<!-- from the EMACS section -->
|
||||||
|
|
||||||
|
<para>For tools to be able to find the necessary catalog(s),
|
||||||
|
the environment variable <envar>SGML_CATALOG_FILES</envar>
|
||||||
|
should be set, as shown in the following example:</para>
|
||||||
|
|
||||||
|
<informalexample id="var-sgml-catalog-files">
|
||||||
|
<para>
|
||||||
|
<screen><prompt>$</prompt> <command>export</command> <envar>SGML_CATALOG_FILES="/usr/lib/sgml/catalog"</envar></screen></para>
|
||||||
|
</informalexample>
|
||||||
|
|
||||||
|
<indexterm zone="var-sgml-catalog-files">
|
||||||
|
<primary>configurations</primary>
|
||||||
|
<secondary>variables</secondary>
|
||||||
|
<tertiary>SGML_CATALOG_FILES</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This is the only necessary additional
|
||||||
|
configuration for DocBook
|
||||||
|
tools and the like to work correctly on your platform.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</section> <!-- config-catalog -->
|
||||||
|
|
||||||
|
|
||||||
|
<section id="making-catalogs">
|
||||||
|
<title>Creating and modifying catalogs</title>
|
||||||
|
|
||||||
|
<indexterm zone="making-catalogs">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>creating</secondary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<indexterm zone="making-catalogs">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>modifying</secondary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A catalog is a text file containing the
|
||||||
|
translation rules of the
|
||||||
|
public identifier to system's files.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
They make it easy to use DocBook, for they
|
||||||
|
allow each user to have their files installed
|
||||||
|
in a different place (e.g. your home directory,
|
||||||
|
<filename class="directory">/usr/local/sgml</filename>,
|
||||||
|
or in any other place) though no other change on
|
||||||
|
the document is necessary for it to be
|
||||||
|
processed and <quote>compiled</quote>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<example id="example-catalog">
|
||||||
|
<title>Example of catalog</title>
|
||||||
|
<programlistingco>
|
||||||
|
<areaspec>
|
||||||
|
<area coords="1" id="ex.catalog.comment"/>
|
||||||
|
<area coords="5" id="ex.catalog.definition"/>
|
||||||
|
<area coords="11" id="ex.catalog.eof"/>
|
||||||
|
</areaspec>
|
||||||
|
<programlisting>
|
||||||
|
-- Catalogue for the Conectiva Styles --
|
||||||
|
|
||||||
|
OVERRIDE YES
|
||||||
|
|
||||||
|
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN"
|
||||||
|
"/home/ldp/styles/books.dtd"
|
||||||
|
|
||||||
|
DELEGATE "-//OASIS"
|
||||||
|
"/home/ldp/SGML/dtds/catalog.dtd"
|
||||||
|
|
||||||
|
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
|
||||||
|
|
||||||
|
-- EOF --
|
||||||
|
</programlisting>
|
||||||
|
<calloutlist>
|
||||||
|
<callout arearefs="ex.catalog.comment">
|
||||||
|
<para> Comment. Comments start with <quote>--</quote> and
|
||||||
|
follow to the end of the line. </para>
|
||||||
|
</callout>
|
||||||
|
<callout arearefs="ex.catalog.definition">
|
||||||
|
<para> The public type association <parameter class="option">"-//Conectiva SA//DTD books V1.0//EN"</parameter>
|
||||||
|
with the file <filename>books.dtd</filename> on the directory <filename
|
||||||
|
class="directory">/home/ldp/styles</filename>. </para>
|
||||||
|
</callout>
|
||||||
|
<callout arearefs="ex.catalog.eof">
|
||||||
|
<para> Comment signifying the end of the file.</para>
|
||||||
|
</callout>
|
||||||
|
</calloutlist>
|
||||||
|
</programlistingco>
|
||||||
|
<indexterm zone="example-catalog">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>creating</secondary>
|
||||||
|
<tertiary>example</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
<indexterm zone="example-catalog">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>modifying</secondary>
|
||||||
|
<tertiary>sample</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<para>As in the example above, to associate an identifier to a file just
|
||||||
|
follow the sequence shown:</para>
|
||||||
|
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Copy the identifier <emphasis>PUBLIC</emphasis></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Type the identifying text </para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Indicate the path to the associated file</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<section id="catalog-explaining-terminology">
|
||||||
|
<title>Explaining the terminology system </title>
|
||||||
|
|
||||||
|
<indexterm zone="catalog-explaining-terminology">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>creating</secondary>
|
||||||
|
<tertiary>terminology</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
<indexterm zone="catalog-explaining-terminology">
|
||||||
|
<primary>catalog</primary>
|
||||||
|
<secondary>modifying</secondary>
|
||||||
|
<tertiary>terminology</tertiary>
|
||||||
|
</indexterm>
|
||||||
|
|
||||||
|
<para>Notice the identifier</para>
|
||||||
|
|
||||||
|
<programlisting>"-//Conectiva SA//DTD books V1.0//EN"</programlisting>
|
||||||
|
|
||||||
|
<para>Its formation is not random and follows some pre-defined
|
||||||
|
conditions.</para>
|
||||||
|
|
||||||
|
<para>The token <quote>-</quote> indicates that the used identifier isn't a
|
||||||
|
registered type. Only a few identifiers are registered and those usualy
|
||||||
|
belong to entities like <acronym>ISO</acronym>, <acronym>IEEE</acronym>,
|
||||||
|
and others.</para>
|
||||||
|
|
||||||
|
<para>The second part of the identifier defines the name of the
|
||||||
|
organization that created it. On the example above, &conectiva; S.A.</para>
|
||||||
|
|
||||||
|
<para>The one before the last defines the contents (in this case a
|
||||||
|
<acronym>DTD</acronym><footnote>
|
||||||
|
<para>These are valid: <acronym>DTD</acronym>, DOCUMENT, ELEMENTS,
|
||||||
|
ENTITIES and NONSGML.</para> </footnote>) and the name of the identified
|
||||||
|
text.</para>
|
||||||
|
|
||||||
|
<para>The last element indicates the language in which the document was
|
||||||
|
written. Since DocBook is a DTD written in English, the language is
|
||||||
|
<literal>EN</literal>. The two letter code recommended is the
|
||||||
|
<acronym>ISO</acronym> identification of the language.</para>
|
||||||
|
|
||||||
|
<para>More information can be obtained at <ulink
|
||||||
|
url="http://www.oasis-open.org/html/a401.htm">OASIS Technical Resolution
|
||||||
|
9401:1997 (Amendment 2 to TR 9401)</ulink>.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="making-catalogs-commands">
|
||||||
|
<title>Useful commands for catalogs</title>
|
||||||
|
|
||||||
|
FIX ME!!!
|
||||||
|
Restructure as follows:
|
||||||
|
before: author info, dates, versions, copyright etc
|
||||||
|
content: lists, paragraphs, sections, application
|
||||||
|
asides: warning, note, tip
|
||||||
|
commands: userinput, parameter, option
|
||||||
|
display: screen
|
||||||
|
references: sample of how to make a bibliography, link within a
|
||||||
|
document
|
||||||
|
after: license, appendix
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<para>The most common commands to be used on catalogs are:</para>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>PUBLIC</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The keyword <literal>PUBLIC</literal> maps
|
||||||
|
public identifiers for identifiers on the system.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>SYSTEM</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The <literal>SYSTEM</literal> keyword maps
|
||||||
|
system identifiers for files on the system.</para>
|
||||||
|
<informalexample>
|
||||||
|
<para>
|
||||||
|
SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd"
|
||||||
|
"publicacoes/livros.dtd"</para>
|
||||||
|
</informalexample>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>SGMLDECL</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The keyword <literal>SGMLDECL</literal> designates the
|
||||||
|
system identifier of the SGML statement that should be used.
|
||||||
|
</para>
|
||||||
|
<informalexample>
|
||||||
|
<para>
|
||||||
|
SGMLDECL "publishings/books.dcl"</para>
|
||||||
|
</informalexample>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>DTDDECL</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>Similar to the <literal>SGMLDECL</literal> the
|
||||||
|
keyword <literal>DTDDECL</literal> identifies the SGML statement
|
||||||
|
that should be used. <literal>DTDDECL</literal> makes the
|
||||||
|
association of the statement with a public identifier to a
|
||||||
|
<acronym>DTD</acronym>. Unfortunately, this association isn't
|
||||||
|
supported by the open source tools available. The benefits of this
|
||||||
|
statement can be achieved somehow with multiple catalog files.
|
||||||
|
</para>
|
||||||
|
<informalexample>
|
||||||
|
<para>
|
||||||
|
DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/livros.dcl"</para>
|
||||||
|
</informalexample>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>CATALOG</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The keyword <literal>CATALOG</literal> allows a catalog
|
||||||
|
to be included inside another. This is a way to make use of several
|
||||||
|
different catalogs without the need to alter them.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>OVERRIDE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The keyword <literal>OVERRIDE</literal> informs whether an
|
||||||
|
identifier has priority over a system identifier.
|
||||||
|
The standard on most systems is that the system identifier
|
||||||
|
has priority over the public one.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>DELEGATE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The keyword <literal>DELEGATE</literal> allows the
|
||||||
|
association of a catalog to a specific type of public identifier.
|
||||||
|
The clause <literal>DELEGATE</literal> is very similar to the
|
||||||
|
<literal>CATALOG</literal>, except for the fact that it doesn't do
|
||||||
|
anything until a specific pattern is specified.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>DOCTYPE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>If a document starts with a type of document, but
|
||||||
|
has no public identifier and no system identifier the clause
|
||||||
|
<literal>DOCTYPE</literal> associates this document
|
||||||
|
with a specific DTD.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<!-- the editing bits will need to be stripped out -->
|
||||||
|
<title>Validating SGML</title>
|
||||||
|
<para> Using jade, or really the nsgmls command, you can
|
||||||
|
validate your .sgml code against the DTD to make sure there
|
||||||
|
aren't any errors. </para>
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.sgml</command>
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
<para> If there are no issues, you'll just get your command
|
||||||
|
prompt back. </para>
|
||||||
|
</section>
|
||||||
|
<section id="validatexml">
|
||||||
|
<title>Validating XML code</title>
|
||||||
|
<para>Validating XML is a touch harder than validating SGML
|
||||||
|
code, but it can be done. You will need to have XML DocBook
|
||||||
|
installed, and then set the <envar>SGML_CATALOG_FILES</envar>
|
||||||
|
to the location of xml.soc (included with jade) and to
|
||||||
|
the location of the DocBook XML catalog file.
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
<prompt>bash$</prompt> <command>export <envar>SGML_CATALOG_FILES</envar>=/usr/lib/sgml/declaration/xml.soc:/usr/lib/xml/catalog</command>
|
||||||
|
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.xml</command>
|
||||||
|
</screen>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="tools-validate-editors">
|
||||||
|
<title>Editing Tools That Also Validate</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>
|
|
@ -0,0 +1,141 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="tools-word-processors">
|
||||||
|
<title>Word Processors</title>
|
||||||
|
<para>
|
||||||
|
Even if you aren't comfortable working DocBook's tagset
|
||||||
|
in a text editor you can still produce valid DocBook
|
||||||
|
documents using a word processor. Support at this point
|
||||||
|
is very limited, but it does exist in the following
|
||||||
|
programs. The up side, of course, is that things like
|
||||||
|
spellcheck are built in to the program. In addition to
|
||||||
|
this, support for DocBook (and XML) is constantly
|
||||||
|
improving.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="abiword">
|
||||||
|
<title>AbiWord</title>
|
||||||
|
<para>
|
||||||
|
Through word of mouth I've heard that AbiWord can work
|
||||||
|
(natively) with DocBook documents. This will need to be
|
||||||
|
tested by someone (possibly me) and should definitely be
|
||||||
|
included if it is the case.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="openoffice">
|
||||||
|
<title>OpenOffice.org</title>
|
||||||
|
<para>
|
||||||
|
<ulink url="http://openoffice.org">http://openoffice.org</ulink>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
As of OpenOffice.org (OOo) 1.1RC there has been
|
||||||
|
support for exporting files to DocBook format.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Although
|
||||||
|
OOo uses the full DocBook document type declaration, it
|
||||||
|
does not actually export the full list of DocBook
|
||||||
|
elements. It uses a <quote>simplified</quote> DocBook
|
||||||
|
tagset which is geared to on-the-fly rendering. (Although
|
||||||
|
it is not the official Simplified DocBook which is
|
||||||
|
described in <xref linkend="dtds" />.)
|
||||||
|
The OpenOffice simplified (or "special" docbook) is
|
||||||
|
available from
|
||||||
|
<ulink url="http://www.chez.com/ebellot/ooo2sdbk/">
|
||||||
|
http://www.chez.com/ebellot/ooo2sdbk/
|
||||||
|
</ulink>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
OOo has been tested by LDP volunteers with mostly
|
||||||
|
positive results. Thanks to Charles Curley
|
||||||
|
(<a href="http://www.charlescurley.com">charlescurley.com</a>)
|
||||||
|
for the following notes:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
To be able to export to DocBook, you must have a Java runtime
|
||||||
|
environment (JRE) installed and registered with OOo--a
|
||||||
|
minimum of version 4.2.x is recommended. The configuration
|
||||||
|
instructions will depend on how you installed your JRE.
|
||||||
|
Visit the OOo web site for help with your setup.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Contrary to the OOo documentation, the Linux OOo did not come with a
|
||||||
|
JRE. I got one from Sun.
|
||||||
|
</para>
|
||||||
|
</listitem> <!-- openoffice -->
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
The exported file has lots of empty lines. My 54 line exported file
|
||||||
|
had 5 lines of actual XML code.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
There was no effort at pretty printing.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
The header is:
|
||||||
|
<computeroutput>
|
||||||
|
<?xml version=3D"1.0" encoding=3D"UTF-8"?>
|
||||||
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http:/=/www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
||||||
|
</computeroutput>
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
The pull-down menu in the "Save As" dialog box for file format
|
||||||
|
indicates that the export format is "DocBook (simplified)." There is
|
||||||
|
no explanation of what that "simplified" indicates. Does OOo export
|
||||||
|
a subset of DocBook? If so, which elements are ignored? Is there any
|
||||||
|
way to enter any of them manually?
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>
|
||||||
|
There is NO documentation on the DocBook export filter or whether
|
||||||
|
OOo will import it again.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Conclusions: OOo 1.1RC is worth looking at if you want a word
|
||||||
|
processor for preparing DocBook documents.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
However, I hope they cure the lack of documentation.
|
||||||
|
For one thing, it would be nice to know which native OOo
|
||||||
|
styles map to which DocBook elements. It would also be
|
||||||
|
nice to know how to map one's own OOo styles to DocBook elements.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="wordperfect">
|
||||||
|
<!-- I don't run Windows - can someone please confirm this
|
||||||
|
information is still true? -->
|
||||||
|
<title>WordPerfect 9 (Corel Office 2000)</title>
|
||||||
|
<para>
|
||||||
|
<ulink url="http://www.corel.com/">
|
||||||
|
http://www.corel.com/</ulink>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<!-- what about XML capabilities? Please replace if
|
||||||
|
appropriate. -->
|
||||||
|
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 which supports SGML.
|
||||||
|
</para>
|
||||||
|
</section> <!-- wordperfect -->
|
||||||
|
</section> <!-- tools-word-processors -->
|
|
@ -0,0 +1,208 @@
|
||||||
|
<!--
|
||||||
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
||||||
|
-->
|
||||||
|
<section id="docbook">
|
||||||
|
<title>Converting Documents to DocBook XML</title>
|
||||||
|
|
||||||
|
<section id="xmldifferences">
|
||||||
|
<title>Differences between XML and SGML</title>
|
||||||
|
<para>
|
||||||
|
There are a few changes between DocBook XML and SGML. Handling
|
||||||
|
these differences should be relatively easy for most small documents,
|
||||||
|
and many authors will not need to make any changes
|
||||||
|
to convert their documents other than the XML and DocBook
|
||||||
|
declarations at the start of their document.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For others, here is a list of what you should keep in mind
|
||||||
|
when converting your documents from SGML to XML.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
An element typically has three parts: the start tag,
|
||||||
|
the content (your words) and the end tag. Qualifiers
|
||||||
|
are added in the start tag and are known as
|
||||||
|
attributes. They will always have a name and a
|
||||||
|
quoted value.</para>
|
||||||
|
<screen><filename
|
||||||
|
class="directory">/usr/local<filename></screen>
|
||||||
|
<para>
|
||||||
|
The start tag contains one attribute (class)
|
||||||
|
with a value of directory. The end tag (also filename)
|
||||||
|
must not contain any attributes.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Element names (tags) and their attributes are
|
||||||
|
case-dependent--typically lowercase.
|
||||||
|
The following will not validate because the end tag
|
||||||
|
&tl;PARA> is uppercase:
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
<para>This part will fail XML validation</PARA>
|
||||||
|
</screen>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Most XML-specific tags (like entity)
|
||||||
|
have to be in all capital letters (ENTITY).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
All attributes in the start tag must be
|
||||||
|
"quoted". This can
|
||||||
|
be either single (') or double (") quotes, but
|
||||||
|
not
|
||||||
|
reverse (`) or <quote>smart quotes</quote>.
|
||||||
|
The quote used to start a name="value"
|
||||||
|
pair must be the same quote used at the end of
|
||||||
|
the value. In other words: "this" would
|
||||||
|
validate, but 'that" would not.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Tags that have a start tag, but no end tag are
|
||||||
|
referred to as <quote>empty</quote> because they do
|
||||||
|
not contain (wrap around) anything. These tags must still be
|
||||||
|
closed with a trailing slash (/). For example:
|
||||||
|
<sgmltag>xref</sgmltag> must be written as
|
||||||
|
<xref linkend="software"/>. You may not
|
||||||
|
have any spaces between the / and >.
|
||||||
|
(Although you may have a space after the final
|
||||||
|
attribute: <xref linkend="foo" />.)
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Processing instructions that get sent to the DSSSL
|
||||||
|
must have a question mark at the
|
||||||
|
end of the tag. The XML version of this tag
|
||||||
|
would look like this:
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
<?dbhtml filename="foo"?>
|
||||||
|
</screen>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If you're converting from SGML to XML, be sure
|
||||||
|
file names refer to .xml files instead of .sgml.
|
||||||
|
Some tools may get confused if a .sgml file contains XML.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Tag minimizations were used in SGML instead of
|
||||||
|
writing out the element name in the end tag.
|
||||||
|
e.g. <sgmltag>para<sgmltag>This is foo.<sgmltag
|
||||||
|
class="endtag"></sgmltag> Tag minimizations are
|
||||||
|
not supported in XML and their use is
|
||||||
|
discouraged in DocBook.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="differences">
|
||||||
|
<title>Changing DTDs</title>
|
||||||
|
<para>
|
||||||
|
The big changes between version changes in the DTD
|
||||||
|
involve changed elements (tags). Elements may be:
|
||||||
|
depricated (which means they will be removed in
|
||||||
|
future versions); removed; modified; or added.
|
||||||
|
Almoost all authors will run into a changed or
|
||||||
|
depricated tag when going to from a lower version
|
||||||
|
of DocBook to a higher version (e.g. 3.x to 4.x).
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <cite>DocBook: The Definitive Guide</cite> does
|
||||||
|
an excellent job of showing you how elements fit
|
||||||
|
together. For each element it tells you what an
|
||||||
|
element must contain (its content model) and what is
|
||||||
|
may be contained in (who its parents are). For
|
||||||
|
example: a <sgmltag>note</sgmltag> must contain a
|
||||||
|
<sgmltag>para<sgmltag>. If you try to write
|
||||||
|
<note>Content in a
|
||||||
|
note</note> your document will not validate.
|
||||||
|
Learning how elements are assembled will make it a
|
||||||
|
lot easier to understand any validation errors that
|
||||||
|
are thrown at you. If you get trully stuck you can
|
||||||
|
also email the LDP's docbook mailing list for extra
|
||||||
|
hints. Information on subscribing is available from
|
||||||
|
<xref linkend="mailinglists" />
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
All tags that have been depricated or changed for 4.x are listed
|
||||||
|
in <cite>DocBook: The definitive guide</cite>,
|
||||||
|
published by O'Reilly and Associates. This book is
|
||||||
|
also available online from <ulink
|
||||||
|
url="http://www.docbook.org">http://www.docbook.org</ulink>.
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
|
||||||
|
<section id="differences3040">
|
||||||
|
<title>Differences between version 3.x and 4.x</title>
|
||||||
|
<para>
|
||||||
|
Here are a few elements that are of particular
|
||||||
|
relevence to LDP authors:
|
||||||
|
</para>
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title><sgmltag>artheader</sgmltag></title>
|
||||||
|
has been changed to
|
||||||
|
<sgmltag>articleinfo</sgmltag>.
|
||||||
|
Most other header elements have been renamed to info.
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title><sgmltag>graphic</sgmltag></title>
|
||||||
|
has being depricated and will be removed as of DocBook 5.x.
|
||||||
|
To prepare for this, start using
|
||||||
|
<sgmltag>mediaobject</sgmltag>. There is more
|
||||||
|
information about <sgmltag>mediaobject</sgmltag>
|
||||||
|
in <xref linkend="images"/>.
|
||||||
|
</formalpara>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<formalpara>
|
||||||
|
<title><sgmltag>imagedata</sgmltag> file formats
|
||||||
|
must now be written in UPPERCASE letters. If you
|
||||||
|
use lowercase or mixed-case spellings
|
||||||
|
for your file formats, it will fail.
|
||||||
|
</formalpara>
|
||||||
|
<para>
|
||||||
|
Valid:
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
<imagedata format="EPS" fileref="foo.eps">
|
||||||
|
</screen>
|
||||||
|
<para>
|
||||||
|
Invalid:
|
||||||
|
</para>
|
||||||
|
<screen>
|
||||||
|
<imagedata format="eps" fileref="foo.eps">
|
||||||
|
</screen>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
</section>
|
Loading…
Reference in New Issue