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

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:
emmajane 2003-08-20 04:08:35 +00:00
parent 33aab5c0a8
commit 2bb56893f9
16 changed files with 3852 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
LDP/guide/docbook/LDP-Author-Guide/ag-about.xml Normal file
View File

@ -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>

180
LDP/guide/docbook/LDP-Author-Guide/ag-distribute.xml Normal file
View File

@ -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>

49
LDP/guide/docbook/LDP-Author-Guide/ag-maintain.xml Normal file
View File

@ -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>

266
LDP/guide/docbook/LDP-Author-Guide/ag-markup.xml Normal file
View File

@ -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 &lt;para&gt; and then
the end tag &lt;/para&gt;. In HTML, a sub-set of SGML, this would be
done with the element &lt;p&gt;. 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 &lt;h1&gt; 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>

102
LDP/guide/docbook/LDP-Author-Guide/ag-overview.xml Normal file
View File

@ -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>

419
LDP/guide/docbook/LDP-Author-Guide/ag-proposal.xml Normal file
View File

@ -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>

387
LDP/guide/docbook/LDP-Author-Guide/ag-writing.xml Normal file
View File

@ -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>

12
LDP/guide/docbook/LDP-Author-Guide/templates.xml Normal file
View File

@ -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

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

@ -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>

91
LDP/guide/docbook/LDP-Author-Guide/tools-emacs-psgml.xml Normal file
View File

@ -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>

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

@ -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>

343
LDP/guide/docbook/LDP-Author-Guide/tools-text-editors.xml Normal file
View File

@ -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 &lt;-- comments --&gt; 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>

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

@ -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
&lt;h1&gt; 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>
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name
&lt;xml_dtd_pth&gt;/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name
</screen>
</callout>
</calloutlist>
</informalexample>
<para>
If you want to convert your existing SGML DocBook into
XML docbook, use this as your declaration (the lines at the
very start of your document).
</para>
<screen>
&lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
&lt;!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'&gt;
</screen>
<para>
If you have followed LDP guidelines, there should be no
other changes required to your document. Note that there
are changes between DocBook 3.x and 4.x that you may
also have to take into account. You can get more information
at this in <xref linkend="differences3040"/>.
</para>
</section>
</section>
<section id="openjade">
<title>OpenJade</title>
<para><ulink
url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink></para>
<para>An extension of Jade written by the DSSSL
community. Some applications require jade, but are being
updated to support either software package.</para>
</section>
</section>
<section id="jadewrappers">
<title>Jade wrappers</title>
<para>These tools are optional and may be installed after Jade,
the DSSSL, and DTD have been installed.</para>
<section id="sgmltools-lite">
<title>sgmltools-lite</title>
<para><ulink
url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink></para>
<para>This is the successor to the sgmltools project, which
has been officially disbanded for over a year. Since then,
Cees de Groot has created a slightly different project, which
acts as a wrapper to the jade SGML processor. It hides much of
the ugliness of the syntax. This author was able to install the
old sgmltools package followed by the sgmltools-lite and could
format this document quite easily. There's even a man page for
sgmltools showing syntax.</para>
</section>
<section id="cygnus">
<title>Cygnus DocBook Tools</title>
<para>May be Red Hat specific - <ulink
url="http://www.redhat.com/">http://www.redhat.com/</ulink></para>
<para>
<indexterm><primary>Cygnus Tools</primary></indexterm>
Red Hat distributes three packages, starting with the
6.2 release, that include DocBook support and some tools. The
tools are easily installed, allowing you to focus more on
writing than wrestling with the tools. TeTex, Jade, and
JadeTeX must be installed first. All three of these packages
are available on the installation CD.
</para>
<section id="usingcygnus">
<title>Using the Cygnus Tools</title>
<para> These tools are provided with Red Hat 6.2. Make sure
the following packages are installed: </para>
<itemizedlist>
<listitem><para> sgml-common-0.1-8.noarch </para></listitem>
<listitem><para> docbook-3.1-4.noarch </para></listitem>
<listitem><para> stylesheets-1.54.13rh-1.noarch </para></listitem>
</itemizedlist>
<para> Red Hat has the latest version on their web site:
<ulink
url="http://www.redhat.com/support/errata/RHBA-2000022-01.html">http://www.redhat.com/support/errata/RHBA-2000022-01.html</ulink>.</para>
<para>Download/get/sneaker-net the RPMs to your machine and
install in the usual manner (become root, then <command
moreinfo="none">rpm -Uvh filename</command>). Once the RPMs
are installed, you can use the following commands to render
DocBook: </para>
<screen>
<prompt>bash$</prompt> <command>db2html</command> <option>filename</option>
</screen>
<para> Renders DocBook into HTML. A subdirectory with the
filename (minus the .sgml extension) is created and the HTML
files are placed there. </para>
<screen>
<prompt>bash$</prompt> <command>db2pdf</command> <option>filename</option>
</screen>
<para>Renders DocBook into a PDF file. Note that there is currently a
problem with db2pdf, and pd2ps caused by JadeTeX. This has been
<ulink url="http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=9670">
registered as a bug with RedHat</ulink>.</para>
</section> <!-- 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" [
&lt;!-- Insertion of the index --&gt;
&lt;!entity index SYSTEM "index.sgml"&gt;
]</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 -->

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

@ -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 [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo>. If Emacs
manages to parse your DTD, you will see <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. Try
<emphasis>C-c C-e RETURN</emphasis> to insert a
<emphasis><sgmltag
class="starttag">test</sgmltag></emphasis> element. If
things are working correctly, you should see the following
in Emacs: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE test [
&lt;!ELEMENT test - - (#PCDATA)&gt;
]</sgmltag>
<sgmltag class="starttag">test</sgmltag><sgmltag class="endtag">test</sgmltag>
</programlisting>
</section>
<section>
<title> Writing a New HOWTO in DocBook </title>
<para> Start a new file for your HOWTO and enter the
following: </para>
<programlisting format="linespecific">
<sgmltag class="starttag">!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN"</sgmltag>
</programlisting>
<para> Enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap><keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap>
<keycap moreinfo="none">p</keycap></keycombo> and hold
your breath. If everything goes as planned, you will see
Emacs chewing for a few seconds and then <emphasis>Parsing
prolog...done</emphasis> in the minibuffer. </para>
<para> At this point, enter <keycombo moreinfo="none"><keycap
moreinfo="none">C</keycap> <keycap
moreinfo="none">c</keycap></keycombo><keycombo
moreinfo="none"><keycap moreinfo="none">C</keycap><keycap
moreinfo="none">e</keycap></keycombo><keycap
moreinfo="none">RETURN</keycap> to insert an
<emphasis><sgmltag
class="starttag">article</sgmltag></emphasis> element and
proceed to write your HOWTO. </para>
</section>
<section>
<title> Quick Reference for Emacs with PSGML </title>
<para> See Nik Clayton's primer for FreeBSD documentation:
<ulink
url="http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html">http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html</ulink>
</para>
</section>
</section>
</section>
<section id="vim">
<title>VIM</title>
<para><ulink
url="http://www.vim.org">http://www.vim.org</ulink></para>
<para>No mention of Emacs is complete without talking about
vi. The <indexterm><primary>vim</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>vim</secondary>
</indexterm>
VIM (Vi IMproved) editor has the functionality of
regular vi, but also has an SGML mode that will
color-coordinate your screen to show where tags are.</para>
<section id="usingvim">
<title>Getting Started</title>
<para>The vim program comes in many parts. There is
the plain vim program, which is compatibile with the
vi program and its commands. Red Hat users will want the vim-common
and vim-minimal packages. Next is the enhanced
<command>vim</command>, which includes the highlighting and other
features of vim over regular vi. Red Hat
users will want vim-enhanced. Last, but certainly not least, is the
X interface, which gives a graphical interface, menus, and mouse
control. To separate this from vim or vi, the command for graphical
access is called <command>gvim</command>.</para>
</section>
<section>
<title>Loading or starting new documents</title>
<para>In both <command>vim</command> and <command>gvim</command> modes,
<filename>.sgml</filename> files will be automatically recognized and
enter into <quote>sgml mode</quote>. A series of known DocBook tags
have been entered into <command>vim</command> and will he highlighted
in brown if a tag is known. If it isn't, it will appear in light blue.
attributes to known tags are in light blue, and values for the
attributes are in pink. From here on, you can use regular <command>vi</command>
commands to navigate and edit.</para>
<para>
While VIM has an XML mode, this mode will not highlight known
and unknown DocBook tags. You can still force VIM into
SGML mode if you like using the <command>:set ft=sgml</command>
command. Note that this will not have any affect on the file
or its contents, only the highlighting within VIM.
</para>
</section>
</section>
<section id="wordperfect">
<title>WordPerfect 9 (Corel Office 2000)</title>
<para><ulink
url="http://www.corel.com/">http://www.corel.com/</ulink></para>
<para>WordPerfect 9 for the MS Windows platform has support
for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML
capabilities.</para>
<para>This is the least expensive of the commercial
applications that support SGML.</para>
</section>
<section id="epcEdit">
<title>epcEdit</title>
<para><ulink
url="http://www.tksgml.de/">http://www.tksgml.de/</ulink></para>
<para>The <indexterm><primary>epcEdit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>epcEdit</secondary>
</indexterm>
epcEdit program allows you to visually edit SGML
files. It has the advantages of not needing to know Emacs or
vi before starting, and is cross-platform, working in both
Windows and Linux. This is a commercial application, and
pricing can be found at
<ulink url="http://www.tksgml.de/pricing.html">http://www.tksgml.de/pricing.html</ulink>
</para>
<para>Along with visual editing, epcEdit will also validate
documents on loading, and on demand by using the <menuchoice
moreinfo="none"><guimenu
moreinfo="none">Document</guimenu><guimenuitem
moreinfo="none">Validate</guimenuitem></menuchoice>
command.</para>
<figure>
<title>epcEdit screen shot</title>
<mediaobject>
<imageobject>
<imagedata format="EPS" fileref="sgeditscreenshot.eps"/>
</imageobject>
<imageobject>
<imagedata format="JPG" fileref="sgeditscreenshot.jpg"/>
</imageobject>
<textobject>
<phrase>The screen shot of the epcEdit program shows a
tree on the left side that has the SGML document in a
hierarchy, while the right side shows the document.
Tags are shown with a grey background.</phrase>
</textobject>
</mediaobject>
</figure>
</section>
<section id="nedit">
<title>nedit</title>
<para><ulink
url="http://nedit.org">http://nedit.org</ulink></para>
<para>To be fair,
<indexterm><primary>nedit</primary></indexterm>
<indexterm>
<primary>Editors</primary>
<secondary>nedit</secondary>
</indexterm>
nedit is more
for programmers, so it might seem a bit of overkill for new
users and especially non-programmers. All that aside, it's
extremely powerful, allowing for color coding of tags. Unlike
epcEdit, nedit doesn't allow you to automatically insert tags
or automatically validate your code. However, it does allow
for shell commands to be run against the contents of the
window (as opposed to saving the file, then checking). In a
few minutes, I was able to set up <command>nsgmls</command> to
validate the SGML and <command>aspell</command> to do my spell
checking.
<figure>
<title>nedit screen shot</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditscreenshot.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditscreenshot.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>The nedit program can provide line numbers
across the left side of the screen, handy for when
<command>nsgmls</command> complains of errors</phrase>
</textobject>
</mediaobject>
</figure>
</para>
<section id="usingnedit">
<title>Using nedit</title>
<para>For writing new documentation, it is recommended that
you download and use the LDP DocBook template. Once you have
the file, you can start up nedit and begin editing. If the
file is saved with a .sgml extension, nedit will load the file
up with SGML/HTML tags enabled. You can turn this on
explicitly using the
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Language
Mode</guimenuitem><guimenuitem>SGML
HTML</guimenuitem></menuchoice> command. </para>
</section> <!-- New Documents -->
<section id="tipsandtricksnedit">
<title>Tips and tricks with nedit</title>
<para>Since you can feed the contents of your window to
outside programs, you can easily extend nedit to perform
repetitive functions. The example you'll see here is to
validate the SGML code using <command>nsgmls</command>.</para>
<para> Select
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Default
Settings</guimenuitem><guimenuitem>Customize
Menus</guimenuitem><guimenuitem>Shell
Menu...</guimenuitem></menuchoice>. This will bring up the
Shell Command dialog box, with all the shell commands nedit
has listed under the
<menuchoice><guimenu>Shell</guimenu></menuchoice> menu. Under
Menu Entry, enter "SGML Validate". This will be the entry
you'll see on the screen. Under Accelerator, press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
Once this menu item is set up, you can press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>
to have the SGML Validate automatically run. Under Command
Input, select window, and under Command Output, select
dialog. Under Command to Execute, enter nsgmls -sv. Note
that <command>nsgmls</command> has to be in your
<envar>PATH</envar> for this to work properly. </para>
<figure>
<title>Adding shell commands to nedit</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditshellcommand.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditshellcommand.jpg" format="JPG"/>
</imageobject>
</mediaobject>
</figure>
<para> Click <guibutton>OK</guibutton> and you'll now be back
at the main nedit screen. Load up an SGML file, and select
<menuchoice><guimenu>Shell</guimenu><guimenuitem>SGML
Validate</guimenuitem></menuchoice> or press
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
The <command>nedit</command> program will fire up and check
the contents of the window. The reason for using -sv is that
the -v tells <command>nsgmls</command> to output the version
of the program, so you'll always get output and know that
<command>nsgmls</command> has run. If all you get is a
version number, then there are no errors with the document.
If there are errors, then they'll be listed in the separate
window for you to see. If you have line numbers turned on
(using
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
Line Numbers</guimenuitem></menuchoice>) then finding the
errors is much simpler, as <command>nsgmls</command> will list
errors by their line number.</para>
<figure>
<title>nsgmls output on success</title>
<mediaobject>
<imageobject>
<imagedata fileref="neditsuccess.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="neditsuccess.jpg" format="JPG"/>
</imageobject>
<textobject>
<phrase>If nsgmls reports success, it merely reports the version of nsgmls</phrase>
</textobject>
</mediaobject>
</figure>
</section>
</section>
<section id="morphoneditor">
<title>Morphon XML editor</title>
<para> <ulink url="http://www.morphon.com/xmleditor/index.shtml">http://www.morphon.com/xmleditor/index.shtml</ulink></para>
<para>This is a commerical application that has a free 30 day
license available for download. It is written in Java, allowing
it to run on any platform that has a JVM (that is, works in both
Windows and Linux). The cost is $150USD for a single user
license, and $75USD for a student license.</para>
<para>On the plus sides of XMLEditor is the left side of the
screen shows the heirarchy of the document (starting with Book
and so on). Selecting an item in the list brings you to that
part of the document so you can edit it. The right part of the
screen shows the text without any markup or tags being shown.
If you have external files as ELEMENTS (as the LDP Author Guide
does), XMLEditor will follow the links and load the files, so
you always work on the entire work. On the minus side of this,
you will get errors if a file (like index.xml) is
missing.</para>
</section>
</section>
</chapter>

141
LDP/guide/docbook/LDP-Author-Guide/tools-word-processors.xml Normal file
View File

@ -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>
&lt;?xml version=3D"1.0" encoding=3D"UTF-8"?&gt;
&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http:/=/www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"&gt;
</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 -->

208
LDP/guide/docbook/LDP-Author-Guide/x2docbook.xml Normal file
View File

@ -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>&lt;filename
class="directory"&gt;/usr/local&lt;filename&gt;</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&gt; is uppercase:
</para>
<screen>
&lt;para&gt;This part will fail XML validation&lt;/PARA&gt;
</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
&lt;xref linkend="software"/&gt;. You may not
have any spaces between the / and &gt;.
(Although you may have a space after the final
attribute: &lt;xref linkend="foo" /&gt;.)
</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>
&lt;?dbhtml filename="foo"?&gt;
</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
&lt;note&gt;Content in a
note&lt;/note&gt; 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>
&lt;imagedata format="EPS" fileref="foo.eps"&gt;
</screen>
<para>
Invalid:
</para>
<screen>
&lt;imagedata format="eps" fileref="foo.eps"&gt;
</screen>
</listitem>
</itemizedlist>
</section>
</section>