5221 lines
217 KiB
Plaintext
5221 lines
217 KiB
Plaintext
|
||
LDP Author Guide
|
||
|
||
Jorge Godoy
|
||
|
||
[http://www.conectiva.com] Conectiva S.A.
|
||
Publishing Department
|
||
|
||
<godoy@metalab.unc.edu>
|
||
|
||
Emma Jane Hogbin
|
||
|
||
<emmajane@xtrinsic.com>
|
||
|
||
Mark F. Komarinski
|
||
|
||
<mkomarinski@wayga.org>
|
||
|
||
David C. Merrill
|
||
|
||
david -AT- lupercalia.net
|
||
|
||
2005-03-04
|
||
Revision History
|
||
Revision 4.84.74.64.54.44.34.24.1
|
||
2006-04-202005-03-042005-01-232004-07-142004-04-192004-04-042004-04-0
|
||
22004-01-27 Revised by: MGejhejhejhejhejhejhejh
|
||
Added notes about prefered submission formats, corrected links,
|
||
packaged templates.Typo fixed in sample DocBook markup. Added new
|
||
web-based authoring tool and information on LaTeX to DocBook
|
||
conversions.Typos fixed in xmlto notes and book template. Copied
|
||
information about DocBook-capable word processing tools into the
|
||
"Converting Documents to DocBook XML" Appendix; added new XML
|
||
editors; and information about tools to convert other formats to
|
||
DocBook XML.Updated information regarding CVS accounts and connecting
|
||
to the CVS server.Added editor credit requirements to the Using
|
||
DocBook section. Updated the submission procedure. New documents can
|
||
now only be added by one of the Review Coordinators after the
|
||
successful completion of each of the required reviews.Removed the
|
||
section Contributing to The LDP (replaced by Summary of The LDP
|
||
Process).Added references for LyX to DocBook conversions in the
|
||
bibliography.Updated the license requirements and added them to the
|
||
table of contents (moved them out of the sub-section).
|
||
|
||
This guide describes the process of submitting and publishing a
|
||
document with The Linux Documentation Project (TLDP). It includes
|
||
information about the tools, toolchains and formats used by TLDP. The
|
||
document's primary audience is new TLDP authors, but it also contains
|
||
information for seasoned documentation authors.
|
||
________________________________________________________________
|
||
|
||
Table of Contents
|
||
1. About this Guide
|
||
|
||
1.1. About this Guide
|
||
1.2. About The LDP
|
||
1.3. Feedback
|
||
1.4. Copyrights and Trademarks
|
||
1.5. Acknowledgments and Thanks
|
||
1.6. Document Conventions
|
||
|
||
2. Authoring TLDP Documents: An Introduction
|
||
|
||
2.1. Summary of The LDP Process
|
||
2.2. Mailing Lists
|
||
|
||
3. Writing Your Proposal
|
||
|
||
3.1. Choosing a Subject
|
||
3.2. Scope of Your Document
|
||
3.3. Unmaintained and Out-of-date Documents
|
||
3.4. Developing an Outline
|
||
3.5. Research
|
||
|
||
4. Write
|
||
|
||
4.1. Writing the Text
|
||
4.2. Edit and Proofread the Text
|
||
4.3. Tools for Writing, Editing and Maintaining your Document
|
||
|
||
5. Markup
|
||
|
||
5.1. Markup: A General Overview
|
||
5.2. DocBook: What it is and why we use it
|
||
5.3. XML and SGML: Why we use XML
|
||
5.4. Markup Languages Accepted by TLDP
|
||
|
||
6. Distributing Your Documentation
|
||
|
||
6.1. Before Distributing Your Documentation
|
||
6.2. Licensing and Copyright
|
||
6.3. Acknowledgments
|
||
6.4. TLDP Review Process
|
||
6.5. Submission to LDP for publication
|
||
|
||
7. Maintenance
|
||
|
||
7.1. Maintaining Your Document
|
||
7.2. Fixing Errors
|
||
|
||
References
|
||
A. Templates
|
||
|
||
A.1. Document Templates
|
||
A.2. Style Sheets
|
||
A.3. GNU Free Documentation License
|
||
|
||
B. System Setup: Editors, Validation and Transformations
|
||
|
||
B.1. Tools for your operating system
|
||
B.2. Editing tools
|
||
B.3. Validation
|
||
B.4. Transformations
|
||
B.5. DocBook DTD
|
||
B.6. Formatting Documents
|
||
|
||
C. Concurrent Version System (CVS)
|
||
|
||
C.1. Getting a CVS account
|
||
C.2. Using CVS
|
||
C.3. CVS Resources
|
||
|
||
D. DocBook: Sample Markup
|
||
|
||
D.1. General Tips and Tricks
|
||
D.2. <section> and <sectN>: what's the difference?
|
||
D.3. Command Prompts
|
||
D.4. Encoding Indexes
|
||
D.5. Inserting Pictures
|
||
D.6. Markup for Metadata
|
||
D.7. Bibliographies
|
||
D.8. Entities (shortcuts, text macros and re-usable text)
|
||
D.9. Customizing your HTML files
|
||
|
||
E. Converting Documents to DocBook XML
|
||
|
||
E.1. Text to DocBook
|
||
E.2. OpenOffice.org to DocBook
|
||
E.3. Microsoft Word to DocBook
|
||
E.4. LaTeX to DocBook
|
||
E.5. LyX to DocBook
|
||
E.6. DocBook to DocBook Transformations
|
||
|
||
Glossary
|
||
F. GNU Free Documentation License
|
||
|
||
F.1. 0. PREAMBLE
|
||
F.2. 1. APPLICABILITY AND DEFINITIONS
|
||
F.3. 2. VERBATIM COPYING
|
||
F.4. 3. COPYING IN QUANTITY
|
||
F.5. 4. MODIFICATIONS
|
||
F.6. 5. COMBINING DOCUMENTS
|
||
F.7. 6. COLLECTIONS OF DOCUMENTS
|
||
F.8. 7. AGGREGATION WITH INDEPENDENT WORKS
|
||
F.9. 8. TRANSLATION
|
||
F.10. 9. TERMINATION
|
||
F.11. 10. FUTURE REVISIONS OF THIS LICENSE
|
||
F.12. Addendum
|
||
|
||
List of Tables
|
||
D-1. Useful markup
|
||
|
||
List of Figures
|
||
B-1. epcEdit screen shot
|
||
B-2. nedit screen shot
|
||
B-3. Adding shell commands to nedit
|
||
B-4. nsgmls output on success
|
||
|
||
List of Examples
|
||
B-1. Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES
|
||
Environmental Variables
|
||
|
||
B-2. Example of an SGML catalog
|
||
B-3. Sample XML Catalog file
|
||
B-4. Debugging example using xmllint
|
||
B-5. "Installing" DSSSL style sheets
|
||
B-6. Example creating HTML output
|
||
B-7. "Installing" DocBook Document Type Definitions
|
||
B-8. Style sheet to insert summaries in articles
|
||
B-9. Configuring an external entity to include the index
|
||
D-1. Command Prompt with programlisting
|
||
D-2. Command Prompt with screen
|
||
D-3. Code for the generation of an index
|
||
D-4. Use of the attribute zone
|
||
D-5. Usage of values startofrange and endofrange on the
|
||
attributeclass
|
||
|
||
D-6. Inserting a picture
|
||
D-7. Using <imageobject>
|
||
D-8. Other Credit
|
||
D-9. Editor
|
||
D-10. Sample Meta Data
|
||
D-11. A Bibliography
|
||
D-12. Adding Entities
|
||
D-13. Use of parameter entities
|
||
________________________________________________________________
|
||
|
||
Chapter 1. About this Guide
|
||
|
||
1.1. About this Guide
|
||
|
||
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.
|
||
|
||
Version 4 of this document was released in early 2004 by Emma Jane
|
||
Hogbin. A complete overhaul of the document was done to separate the
|
||
authoring HOWTOs from the technical HOWTOs. The review took
|
||
approximately eight months.
|
||
|
||
The newest version of this document can be found at the LDP homepage
|
||
[http://www.tldp.org/] http://www.tldp.org. The original DocBook,
|
||
HTML, and other formats can be found there.
|
||
|
||
There are many ways to contribute to the Linux movement that do not
|
||
require the ability to produce software. One such way is to write
|
||
documentation. The availability of easy-to-understand, technically
|
||
accurate documentation can make a world of difference to someone who
|
||
is struggling with Linux software. This Guide is designed to help you
|
||
research and write a HOWTO which can be submitted to the LDP. The
|
||
appendices also include sample templates, markup tips and information
|
||
on how to transform your document from DocBook to another format
|
||
(such as HTML) for easier proofreading.
|
||
________________________________________________________________
|
||
|
||
1.2. About The LDP
|
||
|
||
The Linux Documentation Project (LDP) was started to provide new
|
||
users a way of quickly getting information about a particular
|
||
subject. It not only contains a series of books on administration,
|
||
networking, and programming, but also has a large number of smaller
|
||
works on individual subjects, written by those who have used it. If
|
||
you want to find out about printing, you get the Printing HOWTO. If
|
||
you want to do find out if your Ethernet card works with Linux, grab
|
||
the Ethernet HOWTO, and so on.
|
||
|
||
The LDP provides documents to the world in a variety of convenient
|
||
formats and also accepts submissions in a number of formats. The
|
||
current standard for storing the source documentation is a format
|
||
known as DocBook, see Section 5.2.
|
||
|
||
|
||
The Linux Documentation Project (LDP) is working on developing free,
|
||
high-quality documentation for the GNU/Linux operating system. The
|
||
overall goal of the LDP is to collaborate in all of the issues of
|
||
Linux documentation. This includes the creation of "HOWTOs" and
|
||
"Guides". We hope to establish a system of documentation for Linux
|
||
that will be easy to use and search. This includes the integration of
|
||
the manual pages, info docs, HOWTOs, and other documents.
|
||
|
||
--LDP Manifesto located at [http://www.tldp.org/manifesto.html]
|
||
http://www.tldp.org/manifesto.html
|
||
|
||
The human readable version goes more like this: The LDP consists of a
|
||
large group of volunteers who are working on documentation about
|
||
Linux and the programs which run on the Linux kernel. These documents
|
||
exist primarily as shorter HOWTOs and longer Guides. Both are
|
||
available from [http://www.tldp.org/] http://www.tldp.org/. This
|
||
Guide focuses primarily on how to write your own HOWTOs for
|
||
submission to the LDP.
|
||
________________________________________________________________
|
||
|
||
1.3. Feedback
|
||
|
||
Send feedback to <discuss@en.tldp.org>. Please reference the title of
|
||
this document in your email. Please note: you must
|
||
[http://tldp.org/mailinfo.html#maillists] be subscribed in order to
|
||
send email to the list.
|
||
________________________________________________________________
|
||
|
||
1.4. Copyrights and Trademarks
|
||
|
||
Copyright 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy
|
||
|
||
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."
|
||
________________________________________________________________
|
||
|
||
1.5. Acknowledgments and Thanks
|
||
|
||
1.5.1. Version 1 - Version 3
|
||
|
||
Thanks to everyone that gave comments as I was writing this. This
|
||
includes David Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson,
|
||
Mark Craig and other members of the <discuss@en.tldp.org> list. Some
|
||
sections I got from the [http://www.tldp.org/HOWTO/] HOWTO Index and
|
||
the sgmltools documentation. The sections on network access to CVS
|
||
was partially written by Sergiusz Pawlowicz (<ser@metalab.unc.edu>).
|
||
Sections on DocBook were written by Jorge Godoy
|
||
(<godoy@conectiva.com>). A great deal of thanks to both of them for
|
||
their help.
|
||
________________________________________________________________
|
||
|
||
1.5.2. Version 4
|
||
|
||
Thanks to Tabatha Marshall and Machtelt Garrels (Tille) for making
|
||
sure I actually finished the document. Thanks to my reviewers:
|
||
Charles Curley, Martin Brown and Tille; and to Saqib Ali for his
|
||
on-line transformation and validation tools. I have also incorporated
|
||
a number of useful emails from the LDP mailing lists. The original
|
||
authors are credited within the document. Special personal thank yous
|
||
are extended to Steve Champeon for getting me interested in markup
|
||
languages and for being a wonderful mentor; and to my partner, Graig
|
||
Kent, for being outrageously supportive. [EJH]
|
||
________________________________________________________________
|
||
|
||
1.6. Document Conventions
|
||
|
||
This document uses the following conventions[1]:
|
||
|
||
Descriptions Appearance
|
||
Information requiring special attention
|
||
|
||
Warning
|
||
|
||
This is a warning.
|
||
Caution
|
||
|
||
Caution
|
||
|
||
This cautions the reader.
|
||
Hint
|
||
|
||
Tip
|
||
|
||
This is a hint.
|
||
Notes
|
||
|
||
Note
|
||
|
||
This is a note.
|
||
File Names file.extension
|
||
Directory Names directory
|
||
Commands to be typed command
|
||
Applications Names application
|
||
Prompt of users command under bash shell bash$
|
||
Prompt of root users command under bash shell bash#
|
||
Prompt of user command under tcsh shell tcsh$
|
||
Environment Variables VARIABLE
|
||
Emphasized word word
|
||
Quoted text "quote"
|
||
Code Example
|
||
<para>Beginning and end of paragraph</para>
|
||
________________________________________________________________
|
||
|
||
Chapter 2. Authoring TLDP Documents: An Introduction
|
||
|
||
2.1. Summary of The LDP Process
|
||
|
||
The following section outlines the process of creating and/or
|
||
maintaining a document for the Linux Documentation Project. This
|
||
section includes all steps--some of which may not be relevant to your
|
||
specific document.
|
||
|
||
1. Join the discuss mailing list. Authors who are interested in
|
||
taking over the maintenance of someone else's document should
|
||
also join this list. This is to make sure the LDP knows who is
|
||
working on what documentation.
|
||
If you have not yet written your documentation, please review our
|
||
documents ([http://tldp.org/HOWTO/HOWTO-INDEX/howtos.html]
|
||
current, [http://tldp.org/authors/unmaint.html] unmaintained and
|
||
[] in progress) and submit a proposal to the list. Your proposal
|
||
should include reasons why your document will be different than
|
||
those already in the collection; or identify a subject that is
|
||
currently missing from our documentation. For more information
|
||
about writing proposals, please read Chapter 3.
|
||
For more information about the mailing lists, please read Section
|
||
2.2 or visit [http://lists.tldp.org] lists.tldp.org to subscribe.
|
||
If your document has already been written, please submit a copy
|
||
to the discuss list (or include the URL of where it can be
|
||
found).
|
||
2. Write your document. If your document has not yet been written,
|
||
please be sure to email the discuss list before you start
|
||
writing. You may choose whatever format you feel most comfortable
|
||
in to write your document. If it is not one of the formats
|
||
accepted by the LDP a volunteer will convert it for you. For more
|
||
information on writing technical documentation, please read
|
||
Chapter 4.
|
||
3. If you are adding your own markup, you may also want to join the
|
||
docbook mailing list. For more information about the LDP DocBook
|
||
list please read Section 2.2. If you would like to start with a
|
||
template, you may find the templates in Appendix A useful. There
|
||
is also a general introduction to markup in Chapter 5 and a
|
||
section full of examples at Appendix D.
|
||
4. Submit your document for technical, language and metadata
|
||
reviews. Do this by emailing your document to
|
||
<submit@en.tldp.org>. In the subject line be sure give the title
|
||
of the document. In the body of the email say that you are ready
|
||
for the review process. Outline any additional reviews your
|
||
document may have already received. You should be assigned a
|
||
reviewer within the week. The reviews may take an additional week
|
||
each. For more information about this process, please read
|
||
Chapter 6.
|
||
If your document is not already in DocBook or LinuxDoc format, a
|
||
reviewer will convert it for you.
|
||
5. Once your document has been through each of the reviews a Review
|
||
Coordinator will add it to the CVS, update the version number to
|
||
1.0 and have the document published on the public Web site. For
|
||
more information about your final submission to the LDP, please
|
||
read Section 6.5.
|
||
|
||
Tip If you don't submit your document in DocBook format
|
||
|
||
|
||
The volunteer adding markup to your document may choose any accepted
|
||
markup language. The Author Guide, however, will refer only to
|
||
DocBook. If you are submitting plain text or some other format,
|
||
please let the LDP know if you prefer to maintain your document in
|
||
either LinuxDoc or DocBook, which are the accepted formats for
|
||
end-results.
|
||
________________________________________________________________
|
||
|
||
2.2. Mailing Lists
|
||
|
||
You can subscribe to the following mailing lists:
|
||
|
||
* First is <discuss@en.tldp.org>, which is the main discussion
|
||
group of the LDP.
|
||
* Another is the <docbook@en.tldp.org> list, which is for questions
|
||
about DocBook use including markup and transformations. If you
|
||
run into trouble with a particular markup tag, you can send your
|
||
question here for answers.
|
||
|
||
You can subscribe to either list by sending a request message to
|
||
either <discuss-subscribe@en.tldp.org> or
|
||
<docbook-subscribe@en.tldp.org>. The subject of your message should
|
||
read "subscribe" (no quotes). To remove yourself from the list, send
|
||
an E-mail with the subject of "unsubscribe" to
|
||
<discuss-unsubscribe@en.tldp.org> or
|
||
<docbook-unsubscribe@en.tldp.org>.
|
||
|
||
If you are interested in DocBook beyond the simple markup of your LDP
|
||
document, you may want to consider joining one of the
|
||
[http://www.oasis-open.org/] OASIS DocBook mailing lists. Please see
|
||
[http://docbook.org/mailinglist/index.html]
|
||
http://docbook.org/mailinglist/index.html for more information.
|
||
________________________________________________________________
|
||
|
||
Chapter 3. Writing Your Proposal
|
||
|
||
3.1. Choosing a Subject
|
||
|
||
It is 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 other purposes 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 -- that might be an incentive to write documentation.
|
||
|
||
Regardless of how you picked your subject, it is important that the
|
||
LDP community understand why your documentation should be included in
|
||
its collection. 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.
|
||
________________________________________________________________
|
||
|
||
3.2. Scope of Your Document
|
||
|
||
Now that you've got a subject, you will need to decide the scope of
|
||
the document. The scope or subject area should be:
|
||
|
||
1. Clearly defined. Define the boundaries of your subject area
|
||
before you begin. Do not repeat information that is in another
|
||
HOWTO and do not leave gaps of information between your HOWTO and
|
||
someone else's HOWTO.
|
||
2. Not too broad, and not too narrow. If you try to cover too much
|
||
information you may sacrifice depth. It is better to cover a
|
||
small subject area in detail than to cover a large subject area
|
||
poorly. Linux tools are known for doing exactly one thing and
|
||
doing that one thing well. Similarly, your HOWTO should cover one
|
||
subject and cover it well.
|
||
If the scope of your proposed document is very narrow, it might
|
||
be better to include your information as part of another HOWTO.
|
||
This makes it easier for readers to find the HOWTO they need.
|
||
Search the LDP repository for topics which relate to your
|
||
document. If you find a document which is a good match, email the
|
||
author and ask them if they would like to include your
|
||
contribution.
|
||
3. Undocumented. Before documenting a particular subject, always do
|
||
a web search (and specifically a search within the LDP documents)
|
||
to see if your topic is already covered in another document. If
|
||
it is, refer to the other document instead of duplicating the
|
||
information within your own document. You may wish to include a
|
||
brief summary of information that can be found in other
|
||
documents.
|
||
If the HOWTO already in place is insufficient or needs updating,
|
||
contact the author and offer to help. See also Section 3.3 for
|
||
taking over old or unmaintained documents.
|
||
Most authors appreciate any help offered. Additionally, sending
|
||
comments and remarks to the author is usually regarded both as a
|
||
reassurance and a reward: to the author, feedback is the ultimate
|
||
proof that writing the documentation was not a pointless effort.
|
||
4. Pre-approved by the LDP. Before you proceed with your HOWTO, post
|
||
to the discuss list and get some feedback from other LDP
|
||
volunteers. Checking with the list before you begin can save you
|
||
headaches later.
|
||
|
||
Note Stay in touch!
|
||
|
||
|
||
Joining the discuss list and following it regularly, even if you
|
||
never post, is a good way to stay current on the activities, needs
|
||
and policies of the LDP.
|
||
________________________________________________________________
|
||
|
||
3.2.1. Documentation Templates
|
||
|
||
After you've decided the scope of your document you should start to
|
||
consider the type of document that you will write. There are a number
|
||
of different LDP documentation templates: Guides, HOWTOs, man pages
|
||
and FAQs. Rahul Sundaram describes their scope in the Linux
|
||
Documentation Project (LDP) FAQ. Here is a brief overview of what
|
||
they are with pointers on how you can get started writing your own:
|
||
|
||
* Guides. A guide covers a broad subject and is quite long. The
|
||
Author Guide (this document) is a guide. Other guides include:
|
||
Introduction to Linux: A hands on guide, The Linux Kernel Module
|
||
Programming Guide, etc. A full list of guides is available from:
|
||
Linux Project Documentation Guides. Guides use the "book"
|
||
templates located in Appendix A.
|
||
* HOWTOs. A HOWTO is typically a set of instructions that outlines,
|
||
step-by-step, how a specific task is accomplished. Examples of
|
||
HOWTOs are: [http://tldp.org/HOWTO/CDROM-HOWTO/index.html]
|
||
CDROM-HOWTO [http://tldp.org/HOWTO/Module-HOWTO/index.html]
|
||
Module-HOWTO. A full list of HOWTOs is available from: Single
|
||
List of HOWTOs (warning: it's a BIG page). HOWTOs typically use
|
||
the "article" template and are output to multiple HTML pages by
|
||
default. Templates are available in Appendix A.
|
||
* man pages. man (Manual) pages are the standard form of help
|
||
available for many linux applications and utilities. They can be
|
||
viewed by typing man applicationname at a prompt. A full list of
|
||
man pages is available from: [http://tldp.org/docs.html#man]
|
||
Linux Man Pages. Since man pages are bundled with software there
|
||
is no LDP template at this time.
|
||
* FAQs. 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: Linux Documentation Project FAQs. FAQs typically use the
|
||
"article" template with some specific DocBook elements to form
|
||
the Question/Answer structure. You can find a template for
|
||
writing a FAQ in Appendix A.
|
||
|
||
Note mini-HOWTOs and HOWTOs
|
||
|
||
|
||
The LDP no longer distinguishes between HOWTOs and mini-HOWTOs. All
|
||
previously written mini-HOWTOs have been included in longer HOWTOs.
|
||
All new documents must be at least HOWTO in length. This means the
|
||
documents should cover a bigger subject area rather than a small one.
|
||
If your document is very small you may wish to submit it for
|
||
inclusion in another, larger HOWTO that already exists. If you're not
|
||
sure what size your document is, email the discuss list and ask for
|
||
feedback.
|
||
________________________________________________________________
|
||
|
||
3.3. Unmaintained and Out-of-date Documents
|
||
|
||
If you wish to become the "owner" for an unmaintained document there
|
||
are several steps you must go through.
|
||
|
||
* Contact the author. Make sure the author no longer wishes to
|
||
maintain the document in question. Note that the E-mail address
|
||
shown may no longer be valid. In that case, try a
|
||
[http://google.com] search for the author. If the original author
|
||
of a document cannot be found after a "good-faith" effort, let us
|
||
know (<discuss@en.tldp.org>--subscription required).
|
||
* 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.
|
||
* Inform the LDP which document you would like to maintain, 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 (<discuss@en.tldp.org>). This step is also required for new
|
||
documents.
|
||
* 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.
|
||
|
||
Note Feedback wanted
|
||
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
3.4. Developing an Outline
|
||
|
||
Before you actually begin writing, prepare an outline. An outline
|
||
will help you to get a clear picture of the subject matter and allow
|
||
you to concentrate on one small part of the HOWTO at a time.
|
||
|
||
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.
|
||
|
||
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 configuration before
|
||
one on installation.
|
||
|
||
You may choose to use the following outline for a HOWTO about using a
|
||
specific program:
|
||
|
||
* development history
|
||
* where to download the software from
|
||
* how to install the software
|
||
* how to configure the software
|
||
* how to use the software
|
||
|
||
You may find it helpful to try a little "card sorting" 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.
|
||
|
||
When you are comfortable with your outline, look it over once more,
|
||
with a critical eye. Have you covered every relevant topic in
|
||
sufficient detail? Have you not wandered beyond the scope of the
|
||
document? It is a good idea to show your outline to others (including
|
||
The LDP discuss list) to get some feedback. Remember: it is much
|
||
easier to reorganize your document at the outline stage than doing
|
||
this after writing it.
|
||
|
||
Tip Writing a HOWTO made easy
|
||
|
||
|
||
For help writing your HOWTO outline, and getting a head start on the
|
||
markup of your document, check out The LDP HOWTO Generator. Note that
|
||
this is for generating HOWTOs. Templates for FAQs and Guides are
|
||
available in Appendix A.
|
||
|
||
Note You're not alone
|
||
|
||
|
||
You might have noticed a theme developing here. Just like Free
|
||
software, Free documentation is best when you "release early, release
|
||
often." The discuss list includes many experienced LDP authors, and
|
||
you would be wise to seek their advice when making decisions about
|
||
your contribution.
|
||
________________________________________________________________
|
||
|
||
3.5. Research
|
||
|
||
While you are working on your outline you will most likely research
|
||
your topic--especially to confirm the document you are about to write
|
||
does not yet exist! Here are a few pointers that will keep you from
|
||
pulling out your hair later:
|
||
|
||
* Compile your resources as you research. It is almost guaranteed
|
||
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. Make sure
|
||
the bookmark's title reflects why the page is important to you.
|
||
If there are multiple key ideas in one page, you may want to
|
||
bookmark the same page with different titles.
|
||
* Assume your most important resource will disappear. The dreaded
|
||
"Error 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 "print" the
|
||
file to a PDF (save as or convert to PDF format will capture the
|
||
original URL on the page if you're using a smart browser).
|
||
* Start your "Resources" page now. 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.
|
||
There is more information about the DocBook markup of
|
||
bibliographies in Section D.7.
|
||
* Write down subject areas as you go. 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.
|
||
* Separate generic information from version-specific information. A
|
||
new version of the software that you describe might be released
|
||
the day after you release your document. Other things, like where
|
||
to download the software, won't change. Alternatively, you may
|
||
choose to document old problems with specific software as a way
|
||
of encouraging readers to upgrade to the latest version
|
||
available: "Version X of the software is known for a specific
|
||
bug. The bug was fixed as of Version Y."
|
||
* Save all related emails. People will often have interesting
|
||
insight into the problem that you are 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. Add information in your
|
||
document about which system configurations your instructions have
|
||
been tested on. (Having lots of friends with moderately different
|
||
configurations can be very beneficial!) All of these personal
|
||
experiences can add greatly to your final documentation.
|
||
________________________________________________________________
|
||
|
||
Chapter 4. Write
|
||
|
||
4.1. Writing the Text
|
||
|
||
By now you should have organized your document; you collected bits of
|
||
raw information and inserted them into the outline. Your next
|
||
challenge is to massage all of the raw data you've collected into a
|
||
readable, entertaining and understandable whole. If you are working
|
||
from an existing document make sure any new pieces of information are
|
||
in the best possible places.
|
||
|
||
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 information.
|
||
Don't be too clever though! Your readers are already struggling with
|
||
new concepts--do not make them struggle to understand your language
|
||
as well.
|
||
|
||
There are a number of classic guides to writing--many of which are
|
||
available on-line. Their language will seem old, but the messages are
|
||
still valuable to authors today. These are listed in . Also listed in
|
||
the resources section are a variety of sites that have information
|
||
specific to technical writing.
|
||
|
||
The Author Guide wouldn't be complete without mentioning the Plain
|
||
Language movement. Although directed at simplifying government
|
||
documents, Writing user-friendly documents is quite useful. It
|
||
includes before and after writing samples. There's also a PlainTrain
|
||
writing tutorial.
|
||
|
||
And any document that discusses writing for the web wouldn't be
|
||
complete without a nod toward [http://www.useit.com] useit.com. The
|
||
following articles may be of specific interest:
|
||
|
||
* [http://www.useit.com/papers/webwriting/] Writing for the Web
|
||
* [http://useit.com/alertbox/20030811.html] Information pollution
|
||
* [http://useit.com/alertbox/9703b.html] Be Succinct! (Writing for
|
||
the Web)
|
||
|
||
There are many, many resources for writing web documents--a quick web
|
||
search for "web writing" will find lots of resources. Don't get too
|
||
distracted, though: the ultimate goal is to write, not to read about
|
||
writing!
|
||
________________________________________________________________
|
||
|
||
4.1.1. Writing Style and Style Guides
|
||
|
||
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 Chicago Manual of Style. It defines things like: whether a period
|
||
(.) should be inside or outside of "quotes"; and the format for
|
||
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?).
|
||
|
||
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 [http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/]
|
||
Reviewer's HOWTO currently lists a number of conventions for LDP
|
||
documents and it is as close as it gets to an official LDP Style
|
||
Guide.
|
||
|
||
Tip A personal glossary
|
||
|
||
|
||
It helps to make a list of terms that you were new to you when you
|
||
first started researching and writing your document. You can refer to
|
||
this list while writing the text. You may also want to include it as
|
||
a glossary in your final document.
|
||
|
||
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.
|
||
|
||
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 "I" to
|
||
describe your personal experiences and opinions.
|
||
________________________________________________________________
|
||
|
||
4.1.2. On-line Writing Resources
|
||
|
||
In the 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.
|
||
________________________________________________________________
|
||
|
||
4.2. Edit and Proofread the Text
|
||
|
||
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.
|
||
|
||
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 does not
|
||
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.
|
||
|
||
Make sure that the content of every section matches the title
|
||
precisely. It's possible that your original subject heading is no
|
||
longer relevant. 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.
|
||
|
||
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 "holes" in the information. If
|
||
you are creating a set of instructions it may help to test them on a
|
||
new machine. Sometimes there are packages that need to be installed
|
||
which you've forgotten to mention in your documentation, for
|
||
instance.
|
||
|
||
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: "I skipped step 2 because I already have the required
|
||
packages installed."
|
||
|
||
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 relevant to your document's topic.
|
||
List members should be able to help check the facts, clarity of your
|
||
instructions and language of the document.
|
||
|
||
Note Native speaker?
|
||
|
||
|
||
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 document less valuable.
|
||
________________________________________________________________
|
||
|
||
4.3. Tools for Writing, Editing and Maintaining your Document
|
||
|
||
Caution Reminder
|
||
|
||
|
||
You do not need to submit your initial document to the LDP in
|
||
anything more than plain text! Other open submission formats are
|
||
accepted as well, for instance OpenOffice documents, RTF files or
|
||
HTML. 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, but that should be obvious.
|
||
________________________________________________________________
|
||
|
||
4.3.1. Editing Tools
|
||
|
||
You may use any word processing or text editing tool to write your
|
||
initial document. When you get to the 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 Section B.2.
|
||
________________________________________________________________
|
||
|
||
4.3.2. Concurrent Versions System (CVS)
|
||
|
||
The LDP provides optional CVS access to its authors. This enables
|
||
collaborative writing and has the following positive effects:
|
||
|
||
1. 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.
|
||
2. However difficult from an organizational point of view, it's
|
||
great to have multiple people working on the same document. CVS
|
||
enables you to do this. You can have CVS tell you what changes
|
||
were made by another author while you were editing your copy, and
|
||
integrate those changes.
|
||
3. CVS keeps a log of what changes were made. These logs (and a date
|
||
stamp) can be placed automatically inside your documents when
|
||
they are published.
|
||
4. CVS can be combined with scripts 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 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,
|
||
because the whole publishing process has not been fully automated
|
||
yet.)
|
||
|
||
Note Access to our CVS repository
|
||
|
||
|
||
Only authors with at least three submissions get access to our CVS,
|
||
see Appendix C.
|
||
|
||
For more information on how to use CVS to maintain your LDP
|
||
documents, please read Appendix C.
|
||
________________________________________________________________
|
||
|
||
4.3.3. Spell Check
|
||
|
||
Some writing tools will come with their own built-in spell check
|
||
tools. This list is only if your application does not have a spell
|
||
check option.
|
||
|
||
Spell Check Software
|
||
|
||
aspell [http://aspell.sourceforge.net] http://aspell.sourceforge.net
|
||
This spell check 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.
|
||
|
||
The aspell command comes with the aspell package, included on
|
||
most Linux distributions. Use the command as follows:
|
||
|
||
aspell -c file
|
||
|
||
An interactive user interface allows for fast and easy
|
||
correction of errors. Use the --help to read more about aspell
|
||
features.
|
||
|
||
ispell [http://www.cs.hmc.edu/~geoff/ispell.html]
|
||
http://www.cs.hmc.edu/~geoff/ispell.html
|
||
Similar to aspell, but tries to spell check your markup tags.
|
||
If you have a choice, use aspell, if not, ispell is a very
|
||
acceptable substitute.
|
||
________________________________________________________________
|
||
|
||
Chapter 5. Markup
|
||
|
||
5.1. Markup: A General Overview
|
||
|
||
A markup language is a system for marking or tagging a document to
|
||
define the structure of the document. You may add tags to your
|
||
document to define which parts of your document are paragraphs,
|
||
titles, sections, glossary items (the list goes on!). There are many
|
||
markup languages in use today. XHTML and HTML will be familiar to
|
||
those who author web documents. The LDP uses a markup language known
|
||
as DocBook. Each of these markup languages uses its own "controlled
|
||
vocabulary" to describe documents. For example: in XHTML a paragraph
|
||
would be marked up with the tagset <p></p> while in DocBook a
|
||
paragraph would be marked up with <para></para>. The tagsets are
|
||
defined in a quasi dictionary known as a Document Type Definition
|
||
(DTD).
|
||
|
||
Markup languages also follow a set of rules on how a document can be
|
||
assembled. The rules are either SGML (Standard Generalized Markup
|
||
Language) or XML (eXtensible Markup Language). These rules are
|
||
essentially the "grammar" of a document's markup. SGML and XML are
|
||
very similiar. XML is a sub-set of SGML, but XML requires more
|
||
precise use of the tags when marking up a document. The LDP accepts
|
||
both SGML and XML documents, but prefers XML.
|
||
|
||
There are three components to an XML/SGML document which is read by a
|
||
person.
|
||
|
||
* 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. This is the only part that is required of LDP
|
||
authors!
|
||
* Markup. To describe the structure of a document a controlled
|
||
vocabulary is added on top of the content. It is used to
|
||
distinguish different kinds of content: paragraphs, lists,
|
||
tables, warnings (and so on). The markup must also conform to
|
||
either SGML or XML rules. If you are not comfortable adding
|
||
markup to your document, a TLDP volunteer will do it for you.
|
||
* Transformation. Finally the document is transformed from DocBook
|
||
to PDF, HTML, PostScript for display in digital or paper form.
|
||
This transformation 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. The LDP uses a series of
|
||
scripts to automate these transformations. You are not required
|
||
to transform your own documents.
|
||
|
||
Note Content, markup and transformations
|
||
|
||
|
||
Steve Champeon does a great job of explaining how content, markup
|
||
languages, and transformations all fit together in his article The
|
||
Secret Life of Markup. Although he is writing from an HTML
|
||
perspective, the ideas are relevant and there is an example of
|
||
DocBook markup.
|
||
________________________________________________________________
|
||
|
||
5.2. DocBook: What it is and why we use it
|
||
|
||
According to the official DocBook web site,
|
||
|
||
|
||
DocBook is a general purpose XML and SGML document type particularly
|
||
well suited to books and papers about computer hardware and software
|
||
(though it is by no means limited to these applications).
|
||
|
||
--DocBook.org
|
||
|
||
Tip For the impatient
|
||
|
||
|
||
In the next sections we will be explaining about the theoretical side
|
||
of DocBook, its origins, development, advantages and disadvantages.
|
||
If you just want the practical side, check out these sections for an
|
||
overview of HOWTO DocBook: , Appendix D, and Appendix E from this
|
||
guide.
|
||
|
||
Caution For the beginner
|
||
|
||
|
||
We wish to stress again the fact that any open document format will
|
||
be accepted. If you feel more comfortable with plain text, OpenOffice
|
||
or HTML, that is fine with us. If you do not look forward to learning
|
||
DocBook, LDP volunteerd will convert your document to DocBook XML. To
|
||
us, the most important task for our authors is the actual writing,
|
||
not the formatting, keep that in mind!
|
||
|
||
From the point of submission onwards, however, you will have to
|
||
maintain your document in this XML format, but that's a piece of
|
||
cake. Promised.
|
||
|
||
Although there are other DTDs used to write documentation, there are
|
||
a few reasons not to use them.
|
||
|
||
* DocBook is the most popular DTD, being used by more than a dozen
|
||
major open source projects from GNOME to Python to FreeBSD.
|
||
* 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.
|
||
* 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.
|
||
|
||
Still not convinced? Eric Raymond has written a DocBook
|
||
Demystification HOWTO which may help.
|
||
|
||
Convinced, but still not comfortable with the thought of working with
|
||
DocBook? Give David Lawyer's
|
||
[http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html]
|
||
Howtos-with-LinuxDoc-mini-HOWTO a try.
|
||
________________________________________________________________
|
||
|
||
5.3. XML and SGML: Why we use XML
|
||
|
||
DocBook comes in a couple of different flavors--including both XML
|
||
and SGML formats. This means that you may use either the SGML
|
||
grammar/rules when adding markup, or you may use the XML
|
||
grammar/rules. Either way you may only use one set of rules
|
||
throughout your document, and you must define which one you are using
|
||
at the top of your document.
|
||
|
||
The LDP prefers the XML flavor of DocBook. There are a number of
|
||
reasons for this including the following:
|
||
|
||
1. Libraries for handling XML files are developing at a rapid pace.
|
||
These utilities may make it easier for new authoring tools to
|
||
become available.
|
||
2. 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.
|
||
3. 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.
|
||
|
||
Still not convinced? Fortunately the LDP does accept a number of
|
||
other file formats for input. The list of accepted markup languages
|
||
can be found in Section 5.4
|
||
________________________________________________________________
|
||
|
||
5.4. Markup Languages Accepted by TLDP
|
||
|
||
The LDP stores its documents in the following markup languages:
|
||
|
||
1. DocBook XML version 4.2 (preferred), 4.1.2
|
||
2. DocBook SGML version 4.2, 4.1, or 3.x
|
||
3. LinuxDoc SGML
|
||
|
||
Note New Documents
|
||
|
||
|
||
A new document may be submitted to the LDP in any format. Documents
|
||
which are not in DocBook or LinuxDoc will be converted by a
|
||
volunteer. The author is responsible for adding markup to any
|
||
revisions which are made.
|
||
________________________________________________________________
|
||
|
||
Chapter 6. Distributing Your Documentation
|
||
|
||
6.1. Before Distributing Your Documentation
|
||
|
||
Before you distribute your documentation, there are a few more things
|
||
that you will need to check and possibly add to your document.
|
||
|
||
Spelling and Grammar Check
|
||
You can read more about helper applications in Section 4.3.3.
|
||
You should also check your document for its overall flow and
|
||
clarity.
|
||
|
||
Abstract and Other Meta Data
|
||
Add a short paragraph which clearly defines the scope of your
|
||
document. For more information on how to add this information
|
||
using DocBook please read Section D.6
|
||
|
||
Acknowledgments
|
||
Give credit where credit is due. For more information about
|
||
when to give credit, read Section 6.3.
|
||
|
||
License and Copyright
|
||
The LDP distributes documents, however, the author maintains
|
||
the copyright on the document. All documents accepted by the
|
||
LDP must contain a license and copyright notice. You can read
|
||
more about this in Section 6.2.1. You may also want to add a
|
||
Disclaimer, but this is optional. More about this in Section
|
||
6.2.2.
|
||
|
||
Validate the Markup
|
||
If you are submitting a DocBook or LinuxDoc document, make
|
||
sure the markup is valid. Read why in Section B.3.1.
|
||
|
||
Obtain Peer Reviews
|
||
You may want to have others review your document before
|
||
submitting it to the LDP. Ask people for a Peer Review and/or
|
||
a Technical Accuracy Review. Since not all mailing lists will
|
||
respond favorably to attachments, you may wish to set up a
|
||
temporary web site which houses your document. Note: this is
|
||
absolutely not required.
|
||
________________________________________________________________
|
||
|
||
6.2. Licensing and Copyright
|
||
|
||
In order for a document to be accepted by the LDP, it must be
|
||
licensed and conform to the "LICENSE REQUIREMENTS" section of the LDP
|
||
Manifesto located at [http://www.tldp.org/manifesto.html]
|
||
http://www.tldp.org/manifesto.html.
|
||
|
||
We recommend using the GNU Free Documentation License (GFDL), one of
|
||
the Creative Commons Licenses
|
||
([http://creativecommons.org/licenses/sa/1.0/] Share-Alike, or
|
||
[http://creativecommons.org/licenses/by-sa/2.0/]
|
||
Attribution-Share-Alike), or the LDP license (currently under
|
||
review). The full text of the license must be included in your
|
||
document, including the title and version of the license you are
|
||
using. The LDP will not accept new documents that do not meet
|
||
licensing requirements.
|
||
|
||
Warning Debian-compatible licenses
|
||
|
||
|
||
The Debian package maintainer for LDP documents has divided the LDP
|
||
documents into those with a "free" license and those with a
|
||
"non-free" license. For a summary of this list, please read
|
||
[http://www.debian.org/legal/licenses/byname] Debian License
|
||
Summaries. Currently the Artistic License, BSD License and the GNU
|
||
General Public License are listed as "free". These licenses will also
|
||
be accepted by the LDP. The definition of "non-free" has not been
|
||
made transparent. By choosing another license that has any kind of
|
||
restriction on redistribution or whether or not the document may be
|
||
modified, your document may be put into the "non-free" package
|
||
instead of the "free" package. We are working with Debian to clarify
|
||
how these decisions are made.
|
||
|
||
You can get DocBook markups of both the GNU GPL and the GNU FDL from
|
||
[http://developer.gnome.org/projects/gdp/licenses.html] the GNOME
|
||
Documentation Project. You can then merely include the license in its
|
||
entirety in your document. A DocBook-formatted copy of the license is
|
||
available in Appendix A.
|
||
|
||
For more information about open source documentation and licensing,
|
||
please check .
|
||
________________________________________________________________
|
||
|
||
6.2.1. Copyright
|
||
|
||
As an author, you may retain the copyright and add other restrictions
|
||
(for example: require approval for any translations or derivative
|
||
works). 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.
|
||
________________________________________________________________
|
||
|
||
6.2.2. Disclaimer
|
||
|
||
If you would like to include a disclaimer, you may choose to use the
|
||
following:
|
||
|
||
No liability for the contents of this document can be accepted.
|
||
Use the concepts, examples and information at your own risk. There
|
||
may be errors and inaccuracies, that could be damaging to your
|
||
system. Proceed with caution, and although it is highly unlikely
|
||
that accidents will happen because of following advice or
|
||
procedures described in this document, the author(s) do not take
|
||
any responsibility for any damage claimed to be caused by doing
|
||
so.
|
||
|
||
All copyrights are held by their by their respective owners,
|
||
unless specifically noted otherwise. Use of a term in this
|
||
document should not be regarded as affecting the validity of any
|
||
trademark or service mark. Naming of particular products or brands
|
||
should not be seen as endorsements.
|
||
________________________________________________________________
|
||
|
||
6.2.3. Licensing source code
|
||
|
||
If your HOWTO includes bits of source code that you want others to
|
||
use, you may choose to release the source code under GPL.
|
||
________________________________________________________________
|
||
|
||
6.3. Acknowledgments
|
||
|
||
Your document should have an "Acknowledgments" 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.
|
||
|
||
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 <editor>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
|
||
translators and converters.
|
||
|
||
A converter is someone who performs a source code conversion, for
|
||
instance from HTML to DocBook XML. Source code conversions help the
|
||
LDP achieve long term goals for meta-data, and allow us to distribute
|
||
documentation in many different formats.
|
||
|
||
Translators take your original document and translate it into other
|
||
human-readable languages, from English to Japanese for example, or
|
||
from German to English. Each translation allows many more people all
|
||
over the world to make use of your document and of the Linux
|
||
operating system!
|
||
|
||
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.
|
||
|
||
Note Acknowledgments translated in DocBook
|
||
|
||
|
||
For more information on how to add these credits using DocBook please
|
||
read Section D.6
|
||
________________________________________________________________
|
||
|
||
6.4. TLDP Review Process
|
||
|
||
Before your document is accepted to the LDP collection it will
|
||
undergo at least three formal reviews. These reviews include a
|
||
technical accuracy review, a language review and a metadata review.
|
||
All new documents must pass these reviews before being accepted into
|
||
the collection.
|
||
|
||
When you feel your document is finished, email a copy to the submit
|
||
mailing list (<submit@en.tldp.org>). Please include the title of your
|
||
document and "Final Review Required" in the subject line of your
|
||
email. A team of volunteers will be assigned to your document for
|
||
each of the reviews. It may take up to a week to gather a team who is
|
||
qualified to review your document. Typically the technical review
|
||
happens first, followed by the language review and finally the
|
||
metadata review. Your reviewers will read your document give you
|
||
feedback on whether or not they think your document is ready for
|
||
publication in the LDP collection.
|
||
|
||
Your reviewers may have specific points that must be changed. Once
|
||
you have made the changes submit your document back to your review
|
||
team. They will review the document again and advise you on whether
|
||
or not your document is ready for inclusion in the LDP collection.
|
||
You may need to undergo several edits before your document is ready.
|
||
Or it may not require any additional work. Be prepared to make at
|
||
least one round of changes for both the technical and language
|
||
reviews. Ideally this exchange will happen in the LDP's
|
||
[http://cvs.tldp.org] CVS to better track each of the changes that
|
||
are made, and keep track of the most current version of your
|
||
document.
|
||
|
||
Once your document has passed both the technical and language
|
||
reviews, you may submit it by following the instructions in Section
|
||
6.5.
|
||
|
||
Tip Comparing Two Source Files
|
||
|
||
|
||
Your reviewer may make changes directly to your source file, or they
|
||
may put their suggestions in a separate email. If they are working
|
||
with the source file directly, and your document is using DocBook
|
||
XML, you may find XMLdiff useful to see the changes that your
|
||
reviewer has made to your source file. It is a python tool that
|
||
figures out the differences between two similar XML files, in the
|
||
same way the diff utility compares text files.
|
||
|
||
XMLdiff is available from [http://www.logilab.org/projects/xmldiff]
|
||
http://www.logilab.org/projects/xmldiff.
|
||
|
||
For more information on what the reviewers will be looking for,
|
||
please read the
|
||
[http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/index.html] Linux
|
||
Documentation Project Reviewer HOWTO.
|
||
________________________________________________________________
|
||
|
||
6.5. Submission to LDP for publication
|
||
|
||
Note The final step
|
||
|
||
|
||
This section contains information on what to do after your document
|
||
has received both a technical and language review by the LDP
|
||
volunteers.
|
||
|
||
As part of the review process a Review Coordinator will add your
|
||
document to the CVS (including any associated image files) and notify
|
||
the submit mailing list that your document is ready for publication.
|
||
|
||
If you do not already have a CVS account, please apply for one when
|
||
your document is submitted for publication. You can apply for an
|
||
account contacting LDP CVS master Sergiusz [mailto:ser@gnu.org]
|
||
mailto:ser@gnu.org
|
||
________________________________________________________________
|
||
|
||
Chapter 7. Maintenance
|
||
|
||
7.1. Maintaining Your Document
|
||
|
||
Just because your document has now been published does not mean your
|
||
job is done. Linux documentation needs regular maintenance to make
|
||
sure it is up to date, and to improve it in response to readers'
|
||
ideas and suggestions. TLDP is a living, growing body of knowledge,
|
||
not just a publish-and-forget-it static entity.
|
||
|
||
Add relevant mailing lists to your document where people can get
|
||
support. If you have the time, follow these mailing lists yourself to
|
||
stay up-to-date on the latest information.
|
||
|
||
Put your email address in the document, 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 this folder.
|
||
|
||
Note We are not a free support service, but...
|
||
|
||
|
||
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 contribution to 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.
|
||
________________________________________________________________
|
||
|
||
7.2. Fixing Errors
|
||
|
||
7.2.1. Fixing Your Own Documents
|
||
|
||
If you find an error in your own document, please fix it and
|
||
re-submit the document. You can re-submit your files by emailing them
|
||
to <submit@en.tldp.org>.
|
||
|
||
If you have been using the CVS, you can submit your changes to the
|
||
CVS tree and then send a note to the submit mailing list
|
||
(<submit@en.tldp.org>). In your email please give the exact path of
|
||
your document in the CVS tree.
|
||
|
||
Remember to update the revision history at the top of the document.
|
||
________________________________________________________________
|
||
|
||
7.2.2. Fixing Other Documents in the Collection
|
||
|
||
If you find an error in someone else's document please contact the
|
||
author of the document with the correction. If you do not hear back
|
||
from the author within a "reasonable" amount of time, please email
|
||
the LDP coordinator at <discuss@en.tldp.org>
|
||
([http://tldp.org/mailinfo.html#maillists] subscription required) and
|
||
describe the problem and how you think it needs to be fixed. If the
|
||
license permits, you may be asked to make the change directly to the
|
||
document. If the problems are serious, the document may be removed
|
||
from the collection, or moved to the "Unmaintained" section.
|
||
|
||
Note Taking over unmaintained documentation
|
||
|
||
|
||
For more information on how to deal with unmaintained documents,
|
||
please read: [http://www.tldp.org/authors/unmaint.html] Unmaintained
|
||
(includes a list of steps to take to take over "ownership" of
|
||
unmaintained documents, and a list of unmaintained documents).
|
||
________________________________________________________________
|
||
|
||
References
|
||
|
||
Markup and general information
|
||
|
||
Secret Life of Markup, The,
|
||
[http://hotwired.lycos.com/webmonkey/02/42/index4a.html]
|
||
http://hotwired.lycos.com/webmonkey/02/42/index4a.html, Steve
|
||
Champeon.
|
||
|
||
Progressive Enhancement and the Future of Web Design: Where We Are
|
||
Now , [http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html]
|
||
http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html, Steve
|
||
Champeon.
|
||
|
||
SGML, [http://www.w3.org/MarkUp/SGML/]
|
||
http://www.w3.org/MarkUp/SGML/.
|
||
________________________________________________________________
|
||
|
||
DocBook References
|
||
|
||
DocBook XML 4.1.2 Quick Start Guide,
|
||
[http://www.jimweller.net/jim/dbxmlqs/index.html]
|
||
http://www.jimweller.net/jim/dbxmlqs/index.html, Jim Weller.
|
||
|
||
|
||
|
||
Describes how to install, configure and use the tools and resources
|
||
for DocBook XML 4.1.2. The purpose of this quick start guide is to
|
||
get new docbook authors, editors, and contributors up and running
|
||
fast with the DoocBook tools. These are powerful tool in the hands of
|
||
an author. It assumes a fair knowledge of building and installing
|
||
source packages. There are probably a million and one ways to
|
||
accomplish my ultimate goal of installing and using these tools. This
|
||
one works well for me.
|
||
|
||
--Jim Weller
|
||
|
||
Installing And Using An XML/SGML DocBook Editing Suite Setting Up A
|
||
Free XML/SGML DocBook Editing Suite For Windows And Unix/Linux/BSD,
|
||
[http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bu
|
||
ild/tutorials/docbooksys/docbooksys.html]
|
||
http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bui
|
||
ld/tutorials/docbooksys/docbooksys.html , Ashley J.S. Mills, 2002.
|
||
|
||
Getting Upto Speed With DocBook,
|
||
[http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bu
|
||
ild/tutorials/UniDocBook/UniDocBook.html]
|
||
http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bui
|
||
ld/tutorials/UniDocBook/UniDocBook.html, Ashley J.S. Mills, 2002.
|
||
|
||
DocBook: The Definitive Guide, [http://www.docbook.org/]
|
||
http://www.docbook.org/, Norman Walsh, Leonard Muellner, 1999,
|
||
1-56592-580-7, O'Reilly & Associates, Inc..
|
||
|
||
This book was released by O'Reilly in October 1999, and is a great
|
||
reference to DocBook. I have not found it to be a great practical
|
||
book. You can pick it up at the book vendor of choice, and the entire
|
||
book is also available online (in HTML and SGML formats) at the above
|
||
URL.
|
||
|
||
Simplified DocBook: The Definitive Guide,
|
||
[http://www.docbook.org/tdg/simple/en/html/sdocbook.html]
|
||
http://www.docbook.org/tdg/simple/en/html/sdocbook.html, Norman
|
||
Walsh, Leonard Muellner, 1999.
|
||
|
||
Simplified DocBook, [http://www.oasis-open.org/docbook/xml/simple/]
|
||
http://www.oasis-open.org/docbook/xml/simple/.
|
||
|
||
XML Matters: Getting started with the DocBook XML dialect,
|
||
[http://www-106.ibm.com/developerworks/xml/library/xml-matters3.html]
|
||
http://www-106.ibm.com/developerworks/xml/library/xml-matters3.html.
|
||
|
||
FAQ for DocBook markup,
|
||
[http://www.dpawson.co.uk/docbook/markup.html]
|
||
http://www.dpawson.co.uk/docbook/markup.html.
|
||
|
||
Single-Source Publishing with DocBook XML, , [
|
||
http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial
|
||
/frames/frames.html]
|
||
http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial
|
||
/frames/frames.html, Dan York, 2002.
|
||
|
||
DocBook Install mini-HOWTO,
|
||
[http://tldp.org/HOWTO/mini/DocBook-Install/]
|
||
http://tldp.org/HOWTO/mini/DocBook-Install/, Robert Easter.
|
||
|
||
Exploring SGML DocBook, [http://lwn.net/2000/features/DocBook/]
|
||
http://lwn.net/2000/features/DocBook/, Giorgio Zoppi.
|
||
________________________________________________________________
|
||
|
||
LinuxDoc
|
||
|
||
Howtos-with-LinuxDoc-mini-HOWTO,
|
||
[http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html]
|
||
http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html, David Lawyer.
|
||
|
||
LinuxDoc-SGML User's Guide, [http://www.nmt.edu/tcc/doc/guide.html]
|
||
http://www.nmt.edu/tcc/doc/guide.html.
|
||
________________________________________________________________
|
||
|
||
Converting Other Formats to DocBook
|
||
|
||
Converting HTML to Docbook SGML/XML Using html2db,
|
||
[http://www.cise.ufl.edu/~ppadala/tidy/]
|
||
http://www.cise.ufl.edu/~ppadala/tidy/.
|
||
|
||
5-Minute Review: Using LyX for Creating DocBook,
|
||
[http://www.teledyn.com/help/XML/lyx2db/t1.html]
|
||
http://www.teledyn.com/help/XML/lyx2db/t1.html.
|
||
|
||
Document processing with LyX and SGML,
|
||
[http://www.karakas-online.de/mySGML/]
|
||
http://www.karakas-online.de/mySGML/.
|
||
________________________________________________________________
|
||
|
||
LDP templates, tools & links
|
||
|
||
LDP Templates, , [http://www.tldp.org/authors/index.html#resources]
|
||
http://www.tldp.org/authors/index.html#resources .
|
||
|
||
Contains links to SGML templates and their resulting HTML output to
|
||
help you see what your document will look like. Many of the tags just
|
||
need to be replaced with information unique to your HOWTO. Also
|
||
contains links to tools and other useful information.
|
||
|
||
Linux Documentation Project HOWTO Generator, The,
|
||
[http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html]
|
||
http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html.
|
||
|
||
This is a standalone web page with a number of fields to fill in and
|
||
a few buttons. When ready the compile button starts the compilation
|
||
of all the input fields and wraps it all in proper LinuxDoc SGML,
|
||
ready to process with the LinuxDoc SGML tools.
|
||
|
||
The compiled output is outputted to a read-only text area near the
|
||
bottom of the webpage, so the text has to be copied and pasted into a
|
||
file for compilation.
|
||
|
||
DocBook is not currently supported.
|
||
________________________________________________________________
|
||
|
||
DocBook Transformations
|
||
|
||
DocBook XML/SGML Processing Using OpenJade, ,
|
||
[http://tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/]
|
||
http://tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/, Saqib Ali.
|
||
________________________________________________________________
|
||
|
||
General Writing Links and Style Guides
|
||
|
||
Guide to Grammar and Style,
|
||
[http://newark.rutgers.edu/~jlynch/Writing/]
|
||
http://newark.rutgers.edu/~jlynch/Writing/, Jack Lynch.
|
||
|
||
Purdue's Online Writing Lab, [http://owl.english.purdue.edu/]
|
||
http://owl.english.purdue.edu/.
|
||
|
||
Chicago Manual of Style, [http://www.chicagomanualofstyle.org/]
|
||
http://www.chicagomanualofstyle.org/.
|
||
|
||
Plain Language Resources,
|
||
[http://www.plainlanguagenetwork.org/Resources/]
|
||
http://www.plainlanguagenetwork.org/Resources/.
|
||
|
||
Writing User-Friendly Documents,
|
||
[http://www.blm.gov/nhp/NPR/pe_toc.html]
|
||
http://www.blm.gov/nhp/NPR/pe_toc.html.
|
||
|
||
This is quite useful. It includes before and after writing samples.
|
||
|
||
PlainTrain Writing Tutorial,
|
||
[http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html]
|
||
http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html.
|
||
|
||
Writing for the Web, [http://www.useit.com/papers/webwriting/]
|
||
http://www.useit.com/papers/webwriting/.
|
||
|
||
Information Pollution, [http://useit.com/alertbox/20030811.html]
|
||
http://useit.com/alertbox/20030811.html.
|
||
|
||
Be Succinct! (Writing for the Web),
|
||
[http://useit.com/alertbox/9703b.html]
|
||
http://useit.com/alertbox/9703b.html.
|
||
|
||
Politics and the English Language,
|
||
[http://www.k-1.com/Orwell/index.cgi/work/essays/language.html]
|
||
http://www.k-1.com/Orwell/index.cgi/work/essays/language.html, George
|
||
Orwell.
|
||
|
||
A classic text on writing.
|
||
|
||
Elements of Style, The, [http://www.bartleby.com/141/]
|
||
http://www.bartleby.com/141/, Strunk and White.
|
||
|
||
A classic text on writing.
|
||
|
||
A Short Handbook and Style Sheet,
|
||
[http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics]
|
||
http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics, Thomas
|
||
Pinney.
|
||
|
||
Technical Writing Links, [http://www.techcomplus.com/tips.htm]
|
||
http://www.techcomplus.com/tips.htm.
|
||
|
||
Technical Writing Tutorial,
|
||
[http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html]
|
||
http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html.
|
||
|
||
Strategies to succeed in technical writing,
|
||
[http://www.school-for-champions.com/techwriting.htm]
|
||
http://www.school-for-champions.com/techwriting.htm.
|
||
|
||
User Guides Online Tutorial,
|
||
[http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml]
|
||
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml.
|
||
|
||
DMOZ Technical Writing Links,
|
||
[http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing
|
||
/]
|
||
http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing/
|
||
.
|
||
|
||
techwr-L, [http://www.raycomm.com/techwhirl/magazine/]
|
||
http://www.raycomm.com/techwhirl/magazine/.
|
||
|
||
Technical Writing Links,
|
||
[http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html]
|
||
http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html.
|
||
|
||
An omnibus of links--scrounge for goodies.
|
||
________________________________________________________________
|
||
|
||
Related TLDP Documents
|
||
|
||
Linux Documentation Project (LDP) FAQ,
|
||
[http://tldp.org/FAQ/LDP-FAQ/index.html]
|
||
http://tldp.org/FAQ/LDP-FAQ/index.html, Rahul Sundaram.
|
||
|
||
LDP HOWTO-INDEX, [http://tldp.org/HOWTO/HOWTO-INDEX/]
|
||
http://tldp.org/HOWTO/HOWTO-INDEX/, Guylhem Aznar, Joshua Drake, Greg
|
||
Ferguson.
|
||
________________________________________________________________
|
||
|
||
Software: CVS
|
||
|
||
CVS: Project Management, [http://doc.cs.byu.edu/programming/cvs/]
|
||
http://doc.cs.byu.edu/programming/cvs/, Byron Clark.
|
||
|
||
CVS,
|
||
[http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bu
|
||
ild/tutorials/cvstute/cvstute.html]
|
||
http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/bui
|
||
ld/tutorials/cvstute/cvstute.html, Ashley J.S. Mills, Alan P. Sexton.
|
||
|
||
CVS--Concurrent Versions System,
|
||
[http://www.loria.fr/~molli/cvs/doc/cvs_toc.html]
|
||
http://www.loria.fr/~molli/cvs/doc/cvs_toc.html, Pascal Molli.
|
||
|
||
Learning About CVS , [http://cvshome.org/docs/]
|
||
http://cvshome.org/docs/.
|
||
________________________________________________________________
|
||
|
||
Software: Emacs
|
||
|
||
Information about PSGML ,
|
||
[http://www.lysator.liu.se/~lenst/about_psgml/]
|
||
http://www.lysator.liu.se/~lenst/about_psgml/.
|
||
|
||
Emacs: The Free Software IDE,
|
||
[http://www.linuxjournal.com/article.php?sid=576]
|
||
http://www.linuxjournal.com/article.php?sid=576.
|
||
|
||
Emacs/PSGML Quick Reference,
|
||
[http://www.snee.com/bob/sgmlfree/psgmqref.html]
|
||
http://www.snee.com/bob/sgmlfree/psgmqref.html, Bob Ducharme.
|
||
|
||
NT Emacs Installation, [http://www.charlescurley.com/emacs.html]
|
||
http://www.charlescurley.com/emacs.html, Charles Curley.
|
||
|
||
Cygwin Packages for DocBook Authoring,
|
||
[http://www.docbook.org/wiki/moin.cgi/CygwinPackages/]
|
||
http://www.docbook.org/wiki/moin.cgi/CygwinPackages/.
|
||
|
||
SGML for Windows NT: Setting up a free SGML/XML editing and
|
||
publishing system on Windows/Cygwin ,
|
||
[http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.ht
|
||
ml]
|
||
http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.htm
|
||
l, Markus Hoenicka, 2000.
|
||
|
||
Vim, [http://www.newriders.com/books/opl/ebooks/0735710015.html]
|
||
http://www.newriders.com/books/opl/ebooks/0735710015.html, Steve
|
||
Oualline.
|
||
________________________________________________________________
|
||
|
||
XML Authoring Tools
|
||
|
||
Saqib's list of XML Authoring Tools,
|
||
[http://www.xml-dev.com/xml/editors.html]
|
||
http://www.xml-dev.com/xml/editors.html.
|
||
________________________________________________________________
|
||
|
||
Documentation Licenses
|
||
|
||
Licensing HOWTO, [http://www.catb.org/~esr/Licensing-HOWTO.html]
|
||
http://www.catb.org/~esr/Licensing-HOWTO.html, Eric Raymond,
|
||
Catherine Raymond.
|
||
|
||
|
||
|
||
This document explains how U.S. copyright and licensing law applies
|
||
to open-source software projects. It compares the strengths and
|
||
weaknesses of the existing open-source licenses, and gives guidance
|
||
on how to choose a license for your project. It also explains the
|
||
legalities of changing a project's license. It suggests new practice
|
||
for coping with today's high-threat legal environment--this part is a
|
||
must-read for all project leaders.
|
||
|
||
--Eric Raymond and Catherine Raymond
|
||
|
||
OPL, [http://www.opencontent.org/openpub/]
|
||
http://www.opencontent.org/openpub/.
|
||
|
||
OpenContent officially closed June 30, 2003.
|
||
|
||
Creative Commons, [http://creativecommons.org/licenses/by-sa/1.0/]
|
||
http://creativecommons.org/licenses/by-sa/1.0/.
|
||
|
||
GNU Free Documentation License,
|
||
[http://www.gnu.org/copyleft/fdl.html]
|
||
http://www.gnu.org/copyleft/fdl.html.
|
||
|
||
GNU General Public License,
|
||
[http://www.gnu.org/licenses/licenses.html#GPL]
|
||
http://www.gnu.org/licenses/licenses.html#GPL.
|
||
|
||
If you would like your documents to be included in the main Debian
|
||
distribution, you should use this license. It is not, however, the
|
||
LDP's license of choice.
|
||
________________________________________________________________
|
||
|
||
Appendix A. Templates
|
||
|
||
The LDP stores its documents in the following markup languages:
|
||
|
||
1. DocBook XML version 4.2 (preferred), 4.1.2
|
||
2. DocBook SGML version 4.2, 4.1, or 3.x
|
||
3. LinuxDoc SGML
|
||
|
||
Note New Documents
|
||
|
||
|
||
A new document may be submitted to the LDP in any format. Documents
|
||
which are not in DocBook or LinuxDoc will be converted by a
|
||
volunteer. The author is responsible for adding markup to any
|
||
revisions which are made.
|
||
________________________________________________________________
|
||
|
||
A.1. Document Templates
|
||
|
||
1. HOWTO (Article) [templates/ldp-howto.zip]
|
||
templates/ldp-howto.zip. Most HOWTO documents will use this
|
||
template.
|
||
2. Guide (Book) [templates/ldp-guide.zip] templates/ldp-guide.zip.
|
||
Use this template to create a full book (like this Author Guide,
|
||
for instance). Templates provided by Tille Garrels.
|
||
3. FAQ [templates/ldp-faq.zip] templates/ldp-faq.zip. A standard
|
||
article for writing a FAQ (Frequently Asked Questions) list.
|
||
4. LinuxDoc[templates/ldp-linuxdoc.zip] templates/ldp-linuxdoc.zip.
|
||
A standard template both in HOWTO length and Guide length.
|
||
5. Disclaimer [disclaimer.xml] disclaimer.xml. A standard disclaimer
|
||
which warns readers that (1) your document may not be perfect and
|
||
(2) you are not responsible if things end up broken because of
|
||
it.
|
||
________________________________________________________________
|
||
|
||
A.2. Style Sheets
|
||
|
||
The following style sheets can be used to make your document nicer to
|
||
look at. Remember that the LDP will use its own style sheets to
|
||
distribute your documentation.
|
||
|
||
1. DSL Style Sheet [style.dsl] style.dsl. This DSL style sheet was
|
||
provided by Tille and is to be used with DSSSL transformations.
|
||
2. Cascading Style Sheet [style-ob.css] style-ob.css. This CSS file
|
||
was provided by Saqib Ali and Emma Jane Hogbin. The "ob" is for
|
||
"orange and blue". Use this CSS file with an HTML file.
|
||
Instructions are included in the CSS file.
|
||
________________________________________________________________
|
||
|
||
A.3. GNU Free Documentation License
|
||
|
||
The GFDL (GNU Free Documentation License) is available in XML format
|
||
at [http://www.gnu.org/licenses/fdl.xml]
|
||
http://www.gnu.org/licenses/fdl.xml. For a version in appendix format
|
||
suitable for including in your document, you can see get the XML for
|
||
this document from CVS at
|
||
[http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide
|
||
/fdl-appendix.xml]
|
||
http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/
|
||
fdl-appendix.xml.
|
||
|
||
TLDP template files for DocBook (XML and SGML) and Linuxdoc SGML are
|
||
available from the TLDP website at
|
||
[http://www.tldp.org/authors/index.html#resources]
|
||
http://www.tldp.org/authors/index.html#resources.
|
||
________________________________________________________________
|
||
|
||
Appendix B. System Setup: Editors, Validation and Transformations
|
||
|
||
In this section, we will cover some of the tools that you may want to
|
||
use to create your own LDP documentation. If you use some other tool
|
||
to assist you in writing documents for the LDP, please drop us a line
|
||
and we'll add a blurb for it here. Section 1.3 has contact
|
||
information.
|
||
________________________________________________________________
|
||
|
||
B.1. Tools for your operating system
|
||
|
||
A few notes on setting up your system for DocBook publishing. These
|
||
tools focus more on the transformation of documents from DocBook to
|
||
XHTML (for example).
|
||
|
||
Tools For Your Operating System
|
||
|
||
Debian
|
||
http://www.docbook.org/wiki/moin.cgi/DebianGnuLinuxPackages
|
||
|
||
[http://www.surgo.net] Morgon Kanter suggests apt-get install
|
||
docbook-xml docbook-xsl xsltproc as the minimum requirements.
|
||
[http://lists.tldp.org/index.cgi?1:mss:4851]
|
||
http://lists.tldp.org/index.cgi?1:mss:4851
|
||
|
||
Fedora (aka the new RedHat)
|
||
Notes contributed by Charles Curley.
|
||
|
||
Tools for Docbook SGML and XML are included in the
|
||
distrubution. So are Emacs and PSGML mode, although you will
|
||
have to customize your .emacs. If you are missing a package
|
||
after installing Fedora, get familiar with yum or apt.
|
||
|
||
Installation instructions: none; use Red Hat 9 until they are
|
||
written:
|
||
[http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/]
|
||
http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/.
|
||
|
||
Mandrake
|
||
Notes contributed by [http://www.artemio.net] Artemio.
|
||
|
||
In Mandrake (as of my current 9.2), all the stuff including
|
||
openjade, xmlto, docbook-utils etc. comes as standard.
|
||
|
||
So I just needed to get the TLDP XSL sheet and that's all.
|
||
Didn't ever have any dependency or other problems, everything
|
||
works fine (knock on wood :-)).
|
||
|
||
RedHat
|
||
According to Hal Burgiss, your system is likely already ready
|
||
to edit and process DocBook documents without installing any
|
||
additional packages.
|
||
________________________________________________________________
|
||
|
||
B.2. Editing tools
|
||
|
||
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.
|
||
|
||
Although many editors can also validate your DocBook files, this
|
||
information has been separated into Section B.3.
|
||
|
||
Note More info
|
||
|
||
|
||
Check the resources section for more .
|
||
________________________________________________________________
|
||
|
||
B.2.1. Word Processors
|
||
|
||
Even if you are not 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 spell check are built in to the program. In addition to this,
|
||
support for DocBook (and XML) is constantly improving.
|
||
|
||
Note Converting Microsoft Word documents
|
||
|
||
|
||
Even if you want to use MS Word to write your documents, you may find
|
||
[http://www.docsoft.com/w2xmlv2.htm] w2XML useful. Note that this is
|
||
not free software--the cost is around $130USD. There is, however, a
|
||
trial version of the software.
|
||
|
||
Note Work on the content!
|
||
|
||
|
||
Remember that all formatting changes you make to your document will
|
||
be ignored when your document is released by the LDP. Instead of
|
||
focusing on how your document looks, focus on the content.
|
||
________________________________________________________________
|
||
|
||
B.2.1.1. AbiWord
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
B.2.1.2. OpenOffice.org
|
||
|
||
[http://openoffice.org] http://openoffice.org
|
||
|
||
As of OpenOffice.org (OOo) 1.1RC there has been support for exporting
|
||
files to DocBook format.
|
||
|
||
Although OOo uses the full DocBook document type declaration, it does
|
||
not actually export the full list of DocBook elements. It uses a
|
||
"simplified" DocBook tagset which is geared to on-the-fly rendering.
|
||
(Although it is not the official Simplified DocBook which is
|
||
described in Section B.5.) The OpenOffice simplified (or "special"
|
||
docbook) is available from
|
||
[http://xml.openoffice.org/xmerge/docbook/supported_tag_table.html]
|
||
http://xml.openoffice.org/xmerge/docbook/supported_tag_table.html.
|
||
________________________________________________________________
|
||
|
||
B.2.1.2.1. Open Office 1.0.x
|
||
|
||
OOo has been tested by LDP volunteers with mostly positive results.
|
||
Thanks to Charles Curley ([http://www.charlescurley.com]
|
||
charlescurley.com) for the following notes on using OOo version
|
||
1.0.x:
|
||
|
||
Note Check the version of your OpenOffice
|
||
|
||
|
||
These notes may not apply to the version of OOo you are using.
|
||
|
||
* 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.
|
||
Contrary to the OOo documentation, the Linux OOo did not come
|
||
with a JRE. I got one from Sun.
|
||
* The exported file has lots of empty lines. My 54 line exported
|
||
file had 5 lines of actual XML code.
|
||
* There was no effort at pretty printing.
|
||
* The header is: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE
|
||
article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
||
* The pull-down menu in the File->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?
|
||
* There is NO documentation on the DocBook export filter or whether
|
||
OOo will import it again.
|
||
|
||
Conclusions: OOo 1.1RC is worth looking at if you want a word
|
||
processor for preparing DocBook documents.
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
B.2.1.2.2. Open Office 1.1
|
||
|
||
[http://www.merlinmonroe.com] Tabatha Marshall offers the following
|
||
additional information for OOo 1.1.
|
||
|
||
The first problem was when I tried to do everything on version
|
||
1.0.1. That was obviously a problem. I have RH8, and it was
|
||
installed via rpm packages, so I ripped it out and did a full, new
|
||
install of OpenOffice 1.1. It took a while to find out 1.1 was a
|
||
requirement for XML to work.
|
||
|
||
During the install process I believe I was offered the choice to
|
||
install the XML features. I have a tendency to do full installs of
|
||
my office programs, so I selected everything.
|
||
|
||
I can't offer any advice to those trying to update their current
|
||
OO 1.1. Their "3 ways" aren't documented very well at the site
|
||
([http://xml.openoffice.org] xml.openoffice.org) and as of this
|
||
writing, I can't even find THAT on their site anymore. I think
|
||
more current documentation is needed there to walk people through
|
||
the process. Most of this was unclear and I had to pretty much
|
||
experiment to get things working.
|
||
|
||
Well, after I installed everything I had some configuration to do.
|
||
I opened the application, and got started by opening a new file,
|
||
choosing templates, then selecting the DocBook template. A nice
|
||
menu of Paragraph Styles popped up for me, which are the names for
|
||
all those tags, I noticed (you can see I don't use WYSIWYG often).
|
||
|
||
With a blank doc before me (couldn't get to the XML Filter
|
||
Settings menu unless some type of doc was opened), I went into
|
||
Tools->XML Filter Settings, and edited the entry for DocBook file.
|
||
I configured mine as follows:
|
||
|
||
* Doctype -//OASIS//DTD DocBook XML V4.2//EN
|
||
* DTD http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd
|
||
* XSLT for export
|
||
/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl
|
||
* XSLT for import
|
||
/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffhe
|
||
adings.xsl (this is the default)
|
||
* Template for import
|
||
/home/tabatha/OpenOffice/user/template/DocBook
|
||
File/DocBookTemplate.stw
|
||
|
||
At first, if I opened an XML file that had even one parsing error,
|
||
it would just open the file anyway and display the markup in OO. I
|
||
have many XML files that use © and other types of entities
|
||
which show up as parse errors (depending on the encoding) even
|
||
though they can be processed through. But today I was unable to
|
||
open any of those files. I got input/output errors instead. Still
|
||
investigating that one.
|
||
|
||
However when you do successfully open a document (one parsing with
|
||
no errors), it puts it automatically into WYSIWYG based on the
|
||
markup, and you can then work from the paragraph styles menu like
|
||
any other such editor.
|
||
|
||
To validate the document, I used Tools->XML Filter Settings, then
|
||
clicked the Test XSLTs button. On my screen, I set up the XSLT for
|
||
export to be ldp-html.xsl. If you test and there are errors, a new
|
||
window pops up with error messages at the bottom, and the lines
|
||
that need to be changed up at the top. You can change them there
|
||
and progress through the errors until they're all gone, and keep
|
||
testing until they're gone.
|
||
|
||
If you want to open a file to see the source instead of the
|
||
processed results, go to Tools->XML Filter Settings->Test XSLTs,
|
||
and then under the Import section, check the Display Source box.
|
||
My import XSLT is currently docbooktosoffheadings.xsl (the
|
||
default) and the template for import is DocBookTemplate.stw (also
|
||
default).
|
||
|
||
I think this might work for some people, but unfortunately not for
|
||
me. I've never used WYSIWYG to edit markup. Emacs with PSGML can
|
||
tell me what my next tag is no matter where I am, validate by
|
||
moving through the trouble spots, and I can parse and process from
|
||
command line.
|
||
|
||
With OpenOffice, you have to visit
|
||
[http://xml.openoffice.org/filters.html]
|
||
http://xml.openoffice.org/filters.html to find conversion tools.
|
||
________________________________________________________________
|
||
|
||
B.2.1.3. WordPerfect 9 (Corel Office 2000)
|
||
|
||
[http://www.corel.com/] http://www.corel.com/
|
||
|
||
WordPerfect 9 for the MS Windows platform has support for SGML and
|
||
DocBook 3.0. WordPerfect 9 for Linux has no SGML capabilities.
|
||
|
||
If you are using WordPerfect on the Linux operating system, please
|
||
read: WordPerfect on Linux FAQ
|
||
________________________________________________________________
|
||
|
||
B.2.1.4. XMLmind's XML editor
|
||
|
||
[http://www.xmlmind.com/xmleditor/] http://www.xmlmind.com/xmleditor/
|
||
|
||
Although strictly speaking, it is not a word processor, XMLmind's XML
|
||
editor allows authors to concentrate on the content, and not the
|
||
markup. It has built in spelling and conversion utilities which allow
|
||
you to transform your documents without having to install and
|
||
configure an additional processing tool such as jade. There is a free
|
||
"standard edition", which is a simplified version of their
|
||
"professional edition."
|
||
________________________________________________________________
|
||
|
||
B.2.1.5. Conglomerate
|
||
|
||
[http://www.conglomerate.org] http://www.conglomerate.org
|
||
|
||
According to their web site, "Conglomerate aims to be an XML editor
|
||
that everyone can use. In particular, our primary goal is to create
|
||
the ultimate editor for DocBook and similar formats. It aims to hide
|
||
the jargon and complexity of XML and present the information in your
|
||
documents in a way that makes sense."
|
||
________________________________________________________________
|
||
|
||
B.2.1.6. Vex: a visual editor for XML
|
||
|
||
[http://vex.sourceforge.net/] http://vex.sourceforge.net/
|
||
|
||
According to their web site, "The visual part comes from the fact
|
||
that Vex hides the raw XML tags from the user, providing instead a
|
||
wordprocessor-like interface. Because of this, Vex is best suited for
|
||
document-style XML documents such as XHTML and DocBook rather than
|
||
data-style XML documents."
|
||
________________________________________________________________
|
||
|
||
B.2.2. Text Editors
|
||
|
||
Caution For advanced writers
|
||
|
||
|
||
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 Section B.2.1.
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
B.2.2.1. Emacs (PSGML)
|
||
|
||
http://www.lysator.liu.se/~lenst/about_psgml/
|
||
|
||
Emacs has an SGML writing mode called psgml that is a major mode
|
||
designed for editing SGML and XML documents. It provides:
|
||
|
||
* "syntax highlighting" or "pretty printing" features that make the
|
||
tags stand out
|
||
* a way to insert tags other than typing them by hand
|
||
* and the ability to validate your document while writing
|
||
|
||
For users of Emacs, it's a great way to go. PSGML works with DocBook,
|
||
LinuxDoc and other DTDs equally well.
|
||
________________________________________________________________
|
||
|
||
B.2.2.1.1. Verifying PSGML is Installed
|
||
|
||
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 (C-himpsgml).
|
||
|
||
Tip Dependencies
|
||
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
B.2.2.1.2. Configuring Emacs for Use With PSGML
|
||
|
||
If you want GNU Emacs to enter PSGML mode when you open an .xml 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.
|
||
|
||
Note Tuning Emacs
|
||
|
||
|
||
For more information on how to configure Emacs, check out .
|
||
|
||
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 .emacs file. After you've edited the
|
||
configuration file you will need to restart Emacs.
|
||
________________________________________________________________
|
||
|
||
B.2.2.1.3. Creating New DocBook XML Files
|
||
|
||
There are a number of steps to creating a new DocBook XML file in
|
||
Emacs.
|
||
|
||
* Create a new file with an xml extension.
|
||
* 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 Section B.5
|
||
* Enter C-c C-p. If Emacs manages to parse your DTD, you will see
|
||
Parsing prolog...done in the minibuffer.
|
||
* Enter C-c C-e Enter to auto-magically insert the parent element
|
||
for your document. (New authors are typically writing articles.)
|
||
* 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:
|
||
<article> and </article> in your document.
|
||
________________________________________________________________
|
||
|
||
B.2.2.1.4. Spell Checking in Emacs
|
||
|
||
Emacs can be configured to use aspell by adding the following to your
|
||
~/.emacs file. Thanks to [http://www.ertius.org] Rob Weir for this
|
||
configuration information.
|
||
;; Use aspell
|
||
(setq-default ispell-program-name "aspell")
|
||
;;Setup some dictionary languages
|
||
(setq ispell-dictionary "british")
|
||
(setq flyspell-default-dictionary "british")
|
||
________________________________________________________________
|
||
|
||
B.2.2.2. epcEdit
|
||
|
||
[http://www.tksgml.de/] http://www.tksgml.de
|
||
|
||
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
|
||
[http://www.tksgml.de/pricing.html] http://www.tksgml.de/pricing.html
|
||
|
||
Along with visual editing, epcEdit will also validate documents on
|
||
loading, and on demand by using the Document->Validate command.
|
||
|
||
Figure B-1. epcEdit screen shot
|
||
|
||
[sgeditscreenshot.jpg]
|
||
________________________________________________________________
|
||
|
||
B.2.2.3. Morphon XML editor
|
||
|
||
[http://www.morphon.com/xmleditor/index.shtml]
|
||
http://www.morphon.com/xmleditor/index.shtml
|
||
|
||
This is a commercial application which is currently available for
|
||
free (with an optional user registration). It is written in Java,
|
||
allowing it to run on any platform that has a Java Virtual Machine
|
||
(that is, works in both Windows and Linux).
|
||
|
||
On the plus sides of XMLEditor is the left side of the screen shows
|
||
the hierarchy 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.
|
||
________________________________________________________________
|
||
|
||
B.2.2.4. nedit
|
||
|
||
[http://nedit.org] http://nedit.org
|
||
|
||
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).
|
||
|
||
Figure B-2. nedit screen shot
|
||
|
||
[neditscreenshot.jpg]
|
||
________________________________________________________________
|
||
|
||
B.2.2.4.1. Using nedit
|
||
|
||
When you open your DocBook file, nedit should already have syntax
|
||
highlighting enabled. If it does not you can turn it on explicitly
|
||
using: Preferences->Language Mode->SGML HTML
|
||
|
||
If you have line numbers turned on (using Preferences->Show Line
|
||
Numbers) then finding validation errors is much simpler. nsgmls, the
|
||
validation tool we'll use, lists errors by their line number.
|
||
________________________________________________________________
|
||
|
||
B.2.2.4.2. Configuring nedit
|
||
|
||
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 nsgmls.
|
||
For more information about nsgmls and validating documents please
|
||
read Section B.3.
|
||
|
||
* Select Preferences->Default Settings->Customize Menus->Shell
|
||
Menu.... This will bring up the Shell Command dialog box, with
|
||
all the shell commands nedit has listed under the Shell menu.
|
||
* Under Menu Entry, enter "Validate DocBook." This will be the
|
||
entry you'll see on the screen.
|
||
* Under Accelerator, press Alt-S. Once this menu item is set up,
|
||
you can press Alt-S to have the Validate DocBook automatically
|
||
run.
|
||
* Under Command Input, select window, and under Command Output,
|
||
select dialog.
|
||
* Under Command to Execute, enter nsgmls -sv. Using -v outputs the
|
||
version number is output to the screen so that you know the
|
||
command has run.
|
||
|
||
Note Check the PATH
|
||
|
||
|
||
Note that nsgmls has to be in your PATH for this to work properly.
|
||
|
||
Figure B-3. Adding shell commands to nedit
|
||
|
||
[neditshellcommand.jpg]
|
||
|
||
* Click OK and you'll now be back at the main nedit screen. Load up
|
||
an XML file, and select Shell->Validate DocBook or press Alt-S.
|
||
* The nedit program will fire up and check the contents of the
|
||
window.
|
||
* 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.
|
||
|
||
Figure B-4. nsgmls output on success
|
||
|
||
[neditsuccess.jpg]
|
||
________________________________________________________________
|
||
|
||
B.2.2.5. VIM
|
||
|
||
[http://www.vim.org] http://www.vim.org
|
||
|
||
No mention of text editors is complete without talking about vi. The
|
||
VIM (Vi IMproved) editor has the functionality of regular vi and
|
||
includes "syntax highlighting" of tags.
|
||
________________________________________________________________
|
||
|
||
B.2.2.5.1. Getting Started
|
||
|
||
There are many versions of vi. New authors will likely want one of
|
||
the more feature-packed versions for syntax highlighting and a
|
||
graphical interface including mouse control.
|
||
|
||
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 GUI menus and mouse
|
||
control) users will want gvim. The "g" in gvim is for "Graphical".
|
||
|
||
VIM compiles very easy should you need to build your own. Both vim
|
||
and gvim are built by default. Syntax highlighting is included but
|
||
not enabled by default if you have to start from scratch; use the
|
||
:syntax enable command in VIM to turn this feature on.
|
||
________________________________________________________________
|
||
|
||
B.2.2.5.2. Creating New DocBook XML Files
|
||
|
||
In both vim and gvim, .xml files will be recognized and enter into
|
||
"SGML mode". A series of known DocBook tags and attributes have been
|
||
entered into vim and will be highlighted one color if the name is
|
||
known and another if it is not (for this author the colors are yellow
|
||
and blue).
|
||
|
||
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 :set ft=sgml. If you are working with
|
||
multiple files for a single XML document you can add your document
|
||
type in <-- comments --> to the top of the file to get the correct
|
||
syntax highlighting (you will need to restart the program to see the
|
||
change in highlighting). The top line of this file
|
||
(tools-text-editors.xml) looks like this:
|
||
|
||
<!-- <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'> -->
|
||
|
||
________________________________________________________________
|
||
|
||
B.2.2.5.3. Spell Check
|
||
|
||
As in Emacs, Vim, will work quite happily with aspell. It can be run
|
||
from within Vim with the following: :! aspell -c %.
|
||
|
||
For more sophisticated spell check alternatives, give
|
||
[http://cream.sourceforge.net/] Cream or
|
||
[http://www.vim.org/scripts/script_search_results.php?keywords=vimspe
|
||
ll&script_type=&order_by=rating&direction=descending&search=search]
|
||
vimspell a try.
|
||
________________________________________________________________
|
||
|
||
B.2.2.5.4. Tag Completion
|
||
|
||
The following information is provided by
|
||
[http://www.digitalhermit.com] Kwan Lowe.
|
||
|
||
Vim has a DocBook helper script which can be easily copied into your
|
||
.vimscripts directory and used to "auto complete" tags while writing
|
||
DocBook documents. The script can be downloaded from:
|
||
[http://www.vim.org/scripts/script.php?script_id=38]
|
||
http://www.vim.org/scripts/script.php?script_id=38.
|
||
|
||
Grab the file, then untar it. Copy the dbhelper.vim to your
|
||
.vimscripts directory if you have one.
|
||
|
||
$ mkdir .vimscripts
|
||
$ cp dbhelper.vim .vimscripts
|
||
|
||
You'll also have to convert the dbhelper.vim file to unix
|
||
formatting:
|
||
|
||
$ dos2unix dbhelper.vim
|
||
|
||
Next, edit your .vimrc file and add the line: source
|
||
/home/yourname/.vimscripts/dbhelper.vim
|
||
|
||
To use the scripts, enter vi and go into insert mode. Press ,
|
||
(comma) followed by the shortcut. For example: ,dtbk
|
||
________________________________________________________________
|
||
|
||
B.2.2.6. XMLForm
|
||
|
||
[http://www.datamech.com/XMLForm/] http://www.datamech.com/XMLForm/
|
||
|
||
This web-based application allows you to put in the URL for XML
|
||
source, or copy and paste the XML directly into the web form. The
|
||
application then breaks down your document into a series of form
|
||
fields that hide the DocBook tags so that you may edit the content
|
||
directly. Version 5 is available from
|
||
[http://www.datamech.com/XMLForm/formGenerator5.html]
|
||
http://www.datamech.com/XMLForm/formGenerator5.html. This application
|
||
is best on shorter documents (less than 20 pages printed).
|
||
|
||
As this is an on-line tool, it will be good for small updates only.
|
||
________________________________________________________________
|
||
|
||
B.2.2.7. XMLmind XML Editor (XXE)
|
||
|
||
[http://www.xmlmind.com/xmleditor] http://www.xmlmind.com/xmleditor
|
||
|
||
David Horton offers the following information:
|
||
|
||
I am a big fan of XMLMind's XXE editor and XFC FO converter. It is
|
||
"free as in beer," but not necessarily "free as in speech." Very
|
||
liberal license for personal use however. It's Java-based so it
|
||
works on all sorts of OS's.
|
||
________________________________________________________________
|
||
|
||
B.3. Validation
|
||
|
||
B.3.1. Why Validate Your Document
|
||
|
||
The LDP uses a number of scripts to distribute your document. These
|
||
scripts submit your document to the LDP's CVS (a free document
|
||
version management system), and then they transform your document to
|
||
other formats that users then read. Your document will also be
|
||
mirrored on a number of sites worldwide (yet another set of scripts).
|
||
|
||
In order for these scripts to work correctly, your document must be
|
||
both "well formed" and use "valid markup". Well formed means your
|
||
document follows the rules that XML is expecting: it complies with
|
||
XML grammar rules. Valid markup means you only use elements or tags
|
||
which are "valid" for your document: XML vocabulary rules are
|
||
applied.
|
||
|
||
If your document is not well formed or uses invalid markup, the
|
||
scripts will not be able to process it. As a result, your revised
|
||
document will not be distributed.
|
||
|
||
Note The Docbook Section
|
||
|
||
|
||
There is more information about how to validate your document in the
|
||
DocBook section. Check out Section B.3 for more help with validating
|
||
your document.
|
||
________________________________________________________________
|
||
|
||
B.3.2. Validation for the Faint of Heart
|
||
|
||
Your life is already hard enough without having to install a full set
|
||
of tools just to see if you validate as well. You can upload your raw
|
||
XML files to a web site, then go to [http://validate.sf.net]
|
||
http://validate.sf.net, enter the URL to your document, then validate
|
||
it.
|
||
|
||
Note External entities
|
||
|
||
|
||
When this information was added to the Author Guide external entities
|
||
were not supported. Follow the instructions provided on the Validate
|
||
site if you have trouble.
|
||
________________________________________________________________
|
||
|
||
B.3.3. Validation for the Not So Faint Of Heart
|
||
________________________________________________________________
|
||
|
||
B.3.3.1. Catalogs
|
||
|
||
XML and SGML files contain most of the information you need; however,
|
||
there are sometimes entities which are specific to SGML in general.
|
||
To match these entities to their actual values you need to use a
|
||
catalog. The role of a catalog is to tell your system where to find
|
||
the files it is looking for. You may want to think of a catalog as a
|
||
guide book (or a map) for your tools.
|
||
|
||
Most distributions (Red Hat/Fedora and Debian at least) have a common
|
||
location for the main SGML catalog file, called /etc/sgml/catalog. In
|
||
times past, it could also be found in /usr/lib/sgml/catalog.
|
||
|
||
The structure of XML catalog files is not the same as SGML catalog
|
||
files. The section on tailoring a catalog (see Section B.3.4) will
|
||
give more details about what these files actually contain.
|
||
|
||
If your system cannot find the catalog file, or you are using custom
|
||
catalog files, you may need to set the SGML_CATALOG_FILES and
|
||
XML_CATALOG_FILES environment variables. Using echo
|
||
$SGML_CATALOG_FILES, check to see if it is currently set. If a blank
|
||
line is returned, the variable has not been set. Use the same command
|
||
to see if XML_CATALOG_FILES is set as well. If the variables are not
|
||
set, use the following example to set them now.
|
||
|
||
Example B-1. Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES
|
||
Environmental Variables
|
||
|
||
bash$ export SGML_CATALOG_FILES="/etc/sgml/catalog"
|
||
|
||
To make this change permanent, you can add the following lines to
|
||
your ~/.bashrc file.
|
||
SGML_CATALOG_FILES="/etc/sgml/catalog"
|
||
export SGML_CATALOG_FILES
|
||
|
||
If you installed XML tools via a RedHat or Debian package, you
|
||
probably don't need to do this step. If you are using a custom XML
|
||
catalog you will definitely need to do this. There is more on custom
|
||
catalogs in the next section. To ensure my backup scripts grab this
|
||
custom file, I have added mine in a sub-directory of my home
|
||
directory named "docbook".
|
||
|
||
bash$ export XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"
|
||
|
||
You can also change your .bashrc if you want to save these changes.
|
||
XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"
|
||
export XML_CATALOG_FILES
|
||
|
||
If you are adding the changes to your .bashrc you will not see the
|
||
changes until you open a new terminal window. To make the changes
|
||
immediate in the current terminal, "source" the configuration file.
|
||
________________________________________________________________
|
||
|
||
B.3.4. Creating and modifying catalogs
|
||
|
||
In the previous section I mentioned a catalog is like a guide book
|
||
for your tools. Specifically, a catalog maps the rules from the
|
||
public identifier to your system's files.
|
||
|
||
At the top of every DocBook (or indeed every XML) file there is a
|
||
DOCTYPE which tells the processing tool what kind of document it is
|
||
about to be processed. At a minimum this declaration will include a
|
||
public identifier, such as -//OASIS//DTD DocBook V4.2//EN. This
|
||
public identifier has a number of sections all separated by //. It
|
||
contains the following information: ISO standard if any (- -- in this
|
||
case there is no ISO standard), author (OASIS), type of document (DTD
|
||
DocBook V4.2), language (English). Your DOCTYPE may also include a
|
||
URL.
|
||
|
||
A public identifier is useless to a processing tool, as it needs to
|
||
be able to access the actual DTD. A URL is useless if the processing
|
||
tool is off-line. To help your processor deal with these problems you
|
||
can download all of the necessary files and then "map" them for your
|
||
processing tools by using a catalog.
|
||
|
||
If you are using SGML processing tools (for instance Jade), you will
|
||
need an SGML catalog. If you are using XML processing tools (like
|
||
XSLT), you will need an XML catalog. Information on both is included.
|
||
________________________________________________________________
|
||
|
||
B.3.4.1. SGML Catalogs
|
||
|
||
Example B-2. Example of an SGML catalog
|
||
(1)
|
||
-- Catalog for the Conectiva Styles --
|
||
|
||
OVERRIDE YES
|
||
(2)
|
||
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN"
|
||
"/home/ldp/styles/books.dtd"
|
||
|
||
DELEGATE "-//OASIS"
|
||
"/home/ldp/SGML/dtds/catalog.dtd"
|
||
(3)
|
||
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
|
||
|
||
-- EOF --
|
||
|
||
(1)
|
||
Comment. Comments start with "--" and follow to the end of the
|
||
line.
|
||
(2)
|
||
The public type association "-//Conectiva SA//DTD books
|
||
V1.0//EN" with the file books.dtd on the directory
|
||
/home/ldp/styles.
|
||
(3)
|
||
Comment signifying the end of the file.
|
||
|
||
As in the example above, to associate an identifier to a file just
|
||
follow the sequence shown:
|
||
|
||
1. Copy the identifier PUBLIC
|
||
2. Type the identifying text
|
||
3. Indicate the path to the associated file
|
||
________________________________________________________________
|
||
|
||
B.3.4.1.1. Useful commands for catalogs
|
||
|
||
The most common mappings to be used in catalogs are:
|
||
|
||
PUBLIC
|
||
The keyword PUBLIC maps public identifiers for identifiers on
|
||
the system.
|
||
|
||
SYSTEM
|
||
The SYSTEM keyword maps system identifiers for files on the
|
||
system.
|
||
|
||
SYSTEM
|
||
"http://nexus.conectiva/utilidades/publicacoes/livros.dtd"
|
||
"publicacoes/livros.dtd"
|
||
|
||
SGMLDECL
|
||
The keyword SGMLDECL designates the system identifier of the
|
||
SGML statement that should be used.
|
||
|
||
SGMLDECL "publishings/books.dcl"
|
||
|
||
DTDDECL
|
||
Similar to the SGMLDECL the keyword DTDDECL identifies the
|
||
SGML statement that should be used. DTDDECL makes the
|
||
association of the statement with a public identifier to a
|
||
DTD. 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.
|
||
|
||
DTDDECL "-//Conectiva SA//DTD livros V1.0//EN"
|
||
"publicacoes/livros.dcl"
|
||
|
||
CATALOG
|
||
The keyword CATALOG 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.
|
||
|
||
OVERRIDE
|
||
The keyword OVERRIDE 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.
|
||
|
||
DELEGATE
|
||
The keyword DELEGATE allows the association of a catalog to a
|
||
specific type of public identifier. The clause DELEGATE is
|
||
very similar to the CATALOG, except for the fact that it
|
||
doesn't do anything until a specific pattern is specified.
|
||
|
||
DOCTYPE
|
||
If a document starts with a type of document, but has no
|
||
public identifier and no system identifier the clause DOCTYPE
|
||
associates this document with a specific DTD.
|
||
________________________________________________________________
|
||
|
||
B.3.4.2. XML Catalogs
|
||
|
||
The following sample catalog was provided by Martin A. Brown.
|
||
|
||
Example B-3. Sample XML Catalog file
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
|
||
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd
|
||
">
|
||
|
||
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
|
||
|
||
<public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
|
||
uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/>
|
||
<uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||
uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/>
|
||
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook
|
||
.xsl"
|
||
uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/>
|
||
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.x
|
||
sl"
|
||
uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/>
|
||
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/profile
|
||
-chunk.xsl"
|
||
uri="/home/mabrown/docbook/xsl/xhtml/profile-chunk.xsl"/>
|
||
</catalog>
|
||
________________________________________________________________
|
||
|
||
B.3.5. Validating XML
|
||
|
||
B.3.5.1. nsgmls
|
||
|
||
You can use nsgmls, which is part of the jade suite (on Debian
|
||
apt-get the docbook-utils package, see Section B.4.2), to validate
|
||
SGML or XML documents.
|
||
bash$ nsgmls -s HOWTO.xml
|
||
|
||
If there are no issues, you'll just get your command prompt back. The
|
||
-s tells nsgmls to show only the errors.
|
||
|
||
Tip Function not found
|
||
|
||
|
||
If you get errors about a function not being found, or something
|
||
about an ISO character not having an authoritative source, you may
|
||
need to point nsgmls to your xml.dcl file. For Red Hat 9, it will
|
||
look like this: nsgmls -s /usr/share/sgml/xml.dcl HOWTO.xml
|
||
|
||
For more information on processing files with Jade/OpenJade please
|
||
read
|
||
[http://www.tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/index.html
|
||
] DocBook XML/SGML Processing Using OpenJade.
|
||
________________________________________________________________
|
||
|
||
B.3.5.2. onsgmls
|
||
|
||
This is an alternative to nsgmls. It ships with the OpenJade package.
|
||
This program gives more options than nsgmls and allows you to quietly
|
||
ignore a number of problems that arise while trying to validate an
|
||
XML file (as opposed to an SGML file). This also means you don't have
|
||
to type out the location of your xml.dcl file each time.
|
||
|
||
I was able to simply use the following to validate a file with only
|
||
error messages that were related to my markup errors.
|
||
bash$ onsgmls -s HOWTO.xml
|
||
|
||
According to Bob Stayton you can also turn off specific error
|
||
messages. The following example turns off XML-specific error
|
||
messages.
|
||
bash$ onsgmls -s -wxml -wno-explicit-sgml-decl HOWTO.xml
|
||
________________________________________________________________
|
||
|
||
B.3.5.3. xmllint
|
||
|
||
You can also use the xmllint command-line tool from the libxml2
|
||
package to validate your documents. This tool does a simple check on
|
||
completeness of tags and whether all tags that are opened, are also
|
||
closed again. By default xmllint will output a results tree. So if
|
||
your document comes out until the last line, you know there are no
|
||
heavy errors having to do with tag mismatches, opening and closing
|
||
errors and the like.
|
||
|
||
To prevent printing the entire document to your screen, add the
|
||
--noout parameter.
|
||
bash$ xmllint --noout HOWTO.xml
|
||
|
||
If nothing is returned, your document contains no syntax errors.
|
||
Else, start with the first error that was reported. Fix that one
|
||
error, and run the tool again on your document. If it still returns
|
||
output, again fix the first error that you see, don't botter with the
|
||
rest since further errors are usually generated because of the first
|
||
one.
|
||
|
||
If you would like to check your document for any errors which are
|
||
specific to your Document Type Definition, add --valid.
|
||
bash$ xmllint --noout --valid HOWTO.xml
|
||
|
||
The xmllint tool may also be used for checking errors in the XML
|
||
catalogs, see the man pages for more info on how to set this
|
||
behavior.
|
||
|
||
If you are a Mac OSX or Windows user, you may also want to check out
|
||
tkxmllint, a GUI version of xmllint. More information is available
|
||
from: [http://tclxml.sourceforge.net/tkxmllint.html]
|
||
http://tclxml.sourceforge.net/tkxmllint.html.
|
||
|
||
Example B-4. Debugging example using xmllint
|
||
|
||
The example below shows how you can use xmllint to check your
|
||
documents. I've created some errors that I made a lot, as a beginning
|
||
XML writer. At first, the document doesn't come through, and errors
|
||
are shown:
|
||
bash$ xmllint ldp-history.xml
|
||
ldp-history.xml:22: error: Opening and ending tag mismatch: articlinfo line 6
|
||
and articleinfo
|
||
</articleinfo>
|
||
^
|
||
ldp-history.xml:37: error: Opening and ending tag mismatch: listitem line 36 a
|
||
nd orderedlist
|
||
</orderedlist>
|
||
^
|
||
ldp-history.xml:39: error: Opening and ending tag mismatch: orderedlist line 3
|
||
4 and sect2
|
||
</sect2>
|
||
^
|
||
ldp-history.xml:46: error: Opening and ending tag mismatch: sect1 line 41 and
|
||
para
|
||
for many authors to contribute their part in their area of specialization.</pa
|
||
ra
|
||
|
||
^
|
||
ldp-history.xml:57: error: Opening and ending tag mismatch: para line 55 and s
|
||
ect1
|
||
</sect1>
|
||
^
|
||
ldp-history.xml:59: error: Opening and ending tag mismatch: sect2 line 31 and
|
||
article
|
||
</article>
|
||
^
|
||
ldp-history.xml:61: error: Premature end of data in tag sect1 line 24
|
||
|
||
^
|
||
ldp-history.xml:61: error: Premature end of data in tag article line 5
|
||
|
||
^
|
||
|
||
Now, as we already mentioned, don't worry about anything except the
|
||
first error. The first error says there is an inconsistency between
|
||
the tags on line 6 and line 22 in the file. Indeed, on line 6 we left
|
||
out the "e" in "articleinfo". Fix the error, and run xmllint again.
|
||
The first complaint now is about the offending line 37, where the
|
||
closing tag for list items has been forgotten. Fix the error and run
|
||
the validation tool again, until all errors are gone. Most common
|
||
errors include forgetting to open or close the paragraph tag,
|
||
spelling errors in tags and messed up sections.
|
||
________________________________________________________________
|
||
|
||
B.4. Transformations
|
||
|
||
Warning TLDP will convert your document
|
||
|
||
|
||
This section is about how to transform documents from DocBook to
|
||
other formats. If you do not need to transform documents for your own
|
||
web site, or to proof read the content, please skip this section.
|
||
|
||
If you would like to transform your documents for proofreading
|
||
purposes, please use the XML to HTML on-line converter. You will need
|
||
to upload your XML file(s) to a web site. Then simply drop the URL
|
||
into the form and click the submit button. Your document will be
|
||
magically transformed into a beautiful (and legible) HTML document.
|
||
External files are supported. You may use either absolute or relative
|
||
URIs.
|
||
|
||
Another easy-to-use package is xmlto. It is a front-end for xsltproc.
|
||
It is available as a RedHat, Debian (etc) package or can be
|
||
downloaded from [http://cyberelk.net/tim/xmlto/]
|
||
http://cyberelk.net/tim/xmlto/. You can use it to convert documents
|
||
with:
|
||
bash$ xmlto html mydoc.xml
|
||
bash$ xmlto txt mydoc.xml
|
||
|
||
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.
|
||
|
||
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 set up and ready
|
||
to transform your latest document into other formats. This is very
|
||
useful is you want to see your document before you release it to the
|
||
world.
|
||
|
||
There are currently two ways to transform your document: Document
|
||
Style Semantics and Specification Language (DSSSL); and XML Style
|
||
sheets (XSLT). Although the LDP web site uses DSSSL to convert
|
||
documents you may use XSLT if you want. You only need to choose one
|
||
of these methods. For more information about DSSSL read: Section
|
||
B.4.1, for more information about XSLT read: Section B.4.3.
|
||
________________________________________________________________
|
||
|
||
B.4.1. DSSSL
|
||
|
||
There are three basic requirements to transform a document using
|
||
DSSSL:
|
||
|
||
* The Document Style and Semantics Specification Language files
|
||
(these are plain text files). Section B.4.1.1
|
||
* The Document Type Definition file which matches the DOCTYPE of
|
||
your document (this is a plain text file). Section B.5
|
||
* A processor to do the actual work. Section B.4.1.2
|
||
________________________________________________________________
|
||
|
||
B.4.1.1. The Style Sheets
|
||
|
||
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.
|
||
|
||
Norman Walsh DSSSL [http://docbook.sourceforge.net/projects/dsssl/]
|
||
http://docbook.sourceforge.net/projects/dsssl/. The Document Style
|
||
Semantics and Specification Language tells Jade (see Section B.4.1.2)
|
||
how to render a DocBook document into print or on-line form. The
|
||
DSSSL is what converts a title tag into an <h1> HTML tag, or to 14
|
||
point bold Times Roman for RTF, for example. Documentation for DSSSL
|
||
is located at the same site. Note that modifying the DSSSL doesn't
|
||
modify DocBook itself. It merely changes the way the rendered text
|
||
looks. The LDP uses a modified DSSSL (see below).
|
||
|
||
LDP DSSSL [http://www.tldp.org/authors/tools/ldp.dsl]
|
||
http://www.tldp.org/authors/tools/ldp.dsl. The LDP DSSSL requires the
|
||
Norman Walsh version (see above) but is a slightly modified DSSSL to
|
||
provide things like a table of contents.
|
||
|
||
Example B-5. "Installing" DSSSL style sheets
|
||
|
||
Create a base directory to store everything such as /usr/share/sgml/.
|
||
Copy the DSSSL style sheets into a sub-directory named dsssl.
|
||
________________________________________________________________
|
||
|
||
B.4.1.2. DSSSL Processors
|
||
|
||
There are two versions of the Jade processor: the original version by
|
||
James Clark; and an open-source version of approximately the same
|
||
program, OpenJade. You only need one of these programs. It should be
|
||
installed after the DTD and DSSSL have been "installed."
|
||
|
||
DSSSL Transformation Tools
|
||
|
||
Jade
|
||
[ftp://ftp.jclark.com/pub/jade/]
|
||
ftp://ftp.jclark.com/pub/jade/
|
||
|
||
Currently, the latest version of the package is
|
||
jade-1.2.1.tar.gz.
|
||
|
||
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.
|
||
|
||
OpenJade
|
||
[http://openjade.sourceforge.net/]
|
||
http://openjade.sourceforge.net/
|
||
|
||
An extension of Jade written by the DSSSL community. Some
|
||
applications require jade, but are being updated to support
|
||
either software package.
|
||
________________________________________________________________
|
||
|
||
B.4.1.3. System Setup for DSSSL Transformations
|
||
|
||
1. Tell your system where to find the SGML_CATALOG_FILES (yes, even
|
||
if you are using XML). You can find an example of how to do this
|
||
in Example B-1.
|
||
2. Download the DSSSL and DTD files and copy them into your working
|
||
directory. You can find an example of how to do this in Example
|
||
B-5 and Example B-7.
|
||
________________________________________________________________
|
||
|
||
B.4.1.4. Transformations with DSSSL
|
||
|
||
Once your system is configured (see the previous section), you should
|
||
be able to start using jade to transform your files from XML to
|
||
XHTML.
|
||
|
||
To create individual HTML files, point jade at the correct DSL (style
|
||
sheet). The following example uses the LDP style sheet.
|
||
bash$ jade -t xml -i html \
|
||
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
||
HOWTO.xml
|
||
|
||
If you would like to produce a single-file HTML page, add the -V
|
||
nochunks parameter. You can specify the name of the final HTML file
|
||
by appending the command with > output.html.
|
||
bash$ jade -t xml -i html -V nochunks \
|
||
-d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \
|
||
HOWTO.sgml > output.html
|
||
|
||
Note Not a function name errors
|
||
|
||
|
||
If you get an error about "is not a function name", you will need to
|
||
add a pointer to xml.dcl. It has to be listed immediately before the
|
||
pointer to your XML document. Try one of the following locations:
|
||
/usr/lib/sgml/declaration/xml.dcl, or
|
||
/usr/share/sgml/declaration/xml.dcl. Use locate to find the file if
|
||
it is not in either of those two places. The modified command would
|
||
be as follows:
|
||
bash$ jade -t xml -i html \
|
||
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
|
||
/usr/lib/sgml/declaration/xml.dcl HOWTO.xml
|
||
|
||
If you would like to create print-friendly files instead of HTML
|
||
files, simply change the style sheet that you are using. In the file
|
||
name above, note "html/ldp.dsl" at the end. Change this to
|
||
"print/docbook.dsl", or if you want XHTML output, instead of HTML,
|
||
change the file name to "xhtml/docbook.dsl".
|
||
________________________________________________________________
|
||
|
||
B.4.1.4.1. Changing CSS Files
|
||
|
||
If you want your HTML files to use a specific CSS stylesheet, you
|
||
will need to edit ldp.dsl. Immediately after ;; End of
|
||
$verbatim-display$ redefinition add the following lines:
|
||
(define %stylesheet-type%
|
||
;; The type of the stylesheet to use
|
||
"text/css")
|
||
|
||
(define %stylesheet%
|
||
;; Name of the css stylesheet to use, use value #f if you don't want to
|
||
;; use css stylesheets
|
||
"base.css")
|
||
|
||
Replace base.css with the name of the CSS file you would like to use.
|
||
________________________________________________________________
|
||
|
||
B.4.2. The docbook-utils Package
|
||
|
||
The docbook-utils provide commands like db2html, db2pdf and db2ps,
|
||
based on the jw scripts, that is a front-end to Jade. These tools
|
||
ease the everyday management of documentation and add comfortable
|
||
features.
|
||
|
||
The package, originally created by RedHat and available from
|
||
[http://sources.redhat.com/docbook-tools/]
|
||
http://sources.redhat.com/docbook-tools/ can be installed on most
|
||
systems.
|
||
|
||
Example B-6. Example creating HTML output
|
||
|
||
After validating your document, simply issue the command db2html
|
||
mydoc.xml to create (a) HTML file(s). You can also use the
|
||
docbook-utils as validation tools. Remember: when errors occur,
|
||
always start by solving only the first problem. The rest of the
|
||
problems may be fixed when you fix the first error.
|
||
|
||
If you get errors about a function name, please read .
|
||
________________________________________________________________
|
||
|
||
B.4.2.1. Using CSS and DSL for pretty output
|
||
|
||
You can define your own additional DSL instructions, which can
|
||
include a pointer to a personalized CSS file. Sample DSL and CSS
|
||
files are provided in Appendix A.
|
||
|
||
The sample DSL file will create a table of contents, and have all
|
||
HTML files start with the prefix intro2linux- and end with a suffix
|
||
of .html. The %stylesheet% variable points to the CSS file which
|
||
should be called by your HTML file.
|
||
|
||
To use a specific DSL style sheet the following command should be
|
||
used:
|
||
|
||
db2html -d mystyle.dsl mydoc.xml
|
||
|
||
You can compare the result here:
|
||
[http://tille.xalasys.com/training/unix/]
|
||
http://tille.xalasys.com/training/unix/ is a book formatted with the
|
||
standard tools; [http://tille.xalasys.com/training/tldp/]
|
||
http://tille.xalasys.com/training/tldp/ is one using personalized DSL
|
||
and CSS files. Soft tones and special effects, for instance in
|
||
buttons, were used to achieve maximum effect.
|
||
________________________________________________________________
|
||
|
||
B.4.3. XSL
|
||
|
||
There are alternatives to DSSSL and Jade/OpenJade.
|
||
|
||
When working with DocBook XML, the LDP offers a series of XSL[2]
|
||
style sheets to process documents into HTML. These style sheets
|
||
create output files using the XML tool set that are similar to those
|
||
produced by the SGML tools using ldp.dsl.
|
||
|
||
The major difference between using ldp.dsl and the XSL style sheets
|
||
is the way that the generation of multiple files is handled, such as
|
||
the creation of a separate file for each chapter, section and
|
||
appendix. With the SGML tools, such as jade or openjade, the tool
|
||
itself was responsible for generating the separate files. Because of
|
||
this, only a single file, ldp.dsl was necessary as a customization
|
||
layer for the standard DocBook DSSSL style sheets.
|
||
|
||
With the DocBook XSL style sheets, generation of multiple files is
|
||
controlled by the style sheet. If you want to generate a single file,
|
||
you call one style sheet. If you want to generate multiple files, you
|
||
call a different style sheet. For that reason the LDP XSL style sheet
|
||
distribution is comprised of four files:
|
||
|
||
1. tldp-html.xsl - style sheet called to generate a single file.
|
||
2. tldp-html-chunk.xsl[3] - style sheet called to generate multiple
|
||
files based on chapter, section and appendix elements.
|
||
3. tldp-html-common.xsl - style sheet containing the actual XSLT
|
||
transformations. It is called by the other two HTML style sheets
|
||
and is never directly called.
|
||
4. tldp-print.xsl - style sheet for generation of XSL Formatting
|
||
Objects for print output.
|
||
|
||
You can find the latest copy of the files at
|
||
[http://my.core.com/~dhorton/docbook/tldp-xsl/]
|
||
http://my.core.com/~dhorton/docbook/tldp-xsl/. The package includes
|
||
installation instructions which are duplicated at
|
||
[http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html
|
||
]
|
||
http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html.
|
||
The short version of the install instructions is as follows: Download
|
||
and unzip the latest package from the web site. Take the files from
|
||
the html directory of TLDP-XSL and put them in the html directory of
|
||
Norman Walsh's stylesheets. Take the file from the TLDP-XSL fo
|
||
directory and put it in the Norman Walsh fo directory.
|
||
|
||
Once you have installed these files you can use xsltproc to generate
|
||
HTML files from your XML documents. To transform your XML file(s)
|
||
into a single-page HTML document use the following command:
|
||
bash$ xsltproc -o HOWTO.html /usr/local/sgml/stylesheets/tldp-html.xsl HOWTO.
|
||
xml
|
||
|
||
To generate a set of linked HTML pages, with a separate page for each
|
||
chapter, sect1 or appendix, use the following command:
|
||
bash$ xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl HOWTO.xml
|
||
|
||
Note that you never directly call the style sheet
|
||
tldp-html-common.xsl. It is called by both of the other two style
|
||
sheets.
|
||
________________________________________________________________
|
||
|
||
B.4.3.1. Changing CSS Files
|
||
|
||
If you want your HTML files to use a specific CSS stylesheet, you
|
||
will need to edit tldp-html-common.xsl. Look for a line that
|
||
ressembles <xsl:param name="html.stylesheet" select="'style.css'"/>.
|
||
|
||
Replace style.css with the name of the CSS file you would like to
|
||
use.
|
||
________________________________________________________________
|
||
|
||
B.5. DocBook DTD
|
||
|
||
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 warnings are to warn 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 para or perhaps a list).
|
||
|
||
Caution Versions
|
||
|
||
|
||
It is important that you download the version(s) that match your
|
||
document. You may want to configure your system now to deal with
|
||
"all" 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.
|
||
|
||
The XML DTD is available from
|
||
[http://www.oasis-open.org/docbook/xml/4.2]
|
||
http://www.oasis-open.org/xml/4.2/. The LDP prefers this version of
|
||
the DocBook DTD.
|
||
|
||
If you are going to be working with SGML versions of DocBook you will
|
||
need one (or both) of:
|
||
[http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip]
|
||
http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip or
|
||
[http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip]
|
||
http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip
|
||
|
||
Example B-7. "Installing" DocBook Document Type Definitions
|
||
|
||
Create a base directory to store everything such as /opt/local/sgml/.
|
||
Copy the DTDs into a sub-directory named dtd.
|
||
|
||
Warning Do not edit DTD files
|
||
|
||
|
||
The DocBook standard is described in these files. If you change these
|
||
files, you are no longer working with DocBook.
|
||
________________________________________________________________
|
||
|
||
B.6. Formatting Documents
|
||
|
||
B.6.1. Inserting a summary on the initial articles page
|
||
|
||
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.
|
||
|
||
To enable this, it is necessary to modify the style sheet file.
|
||
|
||
Example B-8. Style sheet to insert summaries in articles
|
||
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
||
<!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Styleshee
|
||
t//EN" CDATA DSSSL>
|
||
<!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesh
|
||
eet//EN" CDATA DSSSL>
|
||
]>
|
||
|
||
<style-sheet>
|
||
<style-specification use="html">
|
||
<style-specification-body>
|
||
|
||
; Includes a summary at the beginning of an item.
|
||
(define %generate-article-toc% #t)
|
||
|
||
</style-specification-body>
|
||
</style-specification>
|
||
<style-specification use="print">
|
||
<style-specification-body>
|
||
|
||
; Includes a summary at the beginning of an item.
|
||
(define %generate-article-toc% #t)
|
||
|
||
</style-specification-body>
|
||
</style-specification>
|
||
<external-specification id="html" document="html-docbook">
|
||
<external-specification id="print" document="print-docbook">
|
||
</style-sheet>
|
||
|
||
________________________________________________________________
|
||
|
||
B.6.2. Inserting indexes automatically
|
||
|
||
Although DocBook has markups for the composition of them, indexes are
|
||
not generated automatically. The collateindex.pl command allows
|
||
indexes to be generated from the source DocBook for inclusion into
|
||
the finished/transformed document.
|
||
|
||
1. Process the document with jade using the style to HTML with the
|
||
option -V html-index.
|
||
|
||
bash$ jade -t sgml \
|
||
-d html/docbook.dsl -V html-index document.sgml
|
||
|
||
2. Generate the index.sgml file with collateindex.pl.
|
||
|
||
bash$ perl collateindex.pl \
|
||
-o index.sgml HTML.index
|
||
|
||
For the above example to work, it is necessary to define an external
|
||
entity by calling the file index.sgml.
|
||
|
||
Example B-9. Configuring an external entity to include the index
|
||
<!DOCTYPE article PUBLIC "-//OASIS//DTD
|
||
DocBook V3.1//EN" [
|
||
|
||
<!-- Insertion of the index --> <!entity index SYSTEM
|
||
"index.sgml"> ]>
|
||
|
||
See also Section D.4 for information on how to insert necessary
|
||
information on the text.
|
||
|
||
Note Odd behavior generating indexes for print versions
|
||
|
||
|
||
Remember that if you're trying to get Tables of Contents or Indexes
|
||
on PS or PDF output you'll need to run jadetex or pdfjadetex at least
|
||
three times. This is required by TeX but not by DocBook or related
|
||
applications.
|
||
________________________________________________________________
|
||
|
||
Appendix C. Concurrent Version System (CVS)
|
||
|
||
The LDP provides optional CVS access to its authors. This enables
|
||
collaborative writing and has the following positive effects:
|
||
|
||
1. 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.
|
||
2. However difficult from an organizational point of view, it's
|
||
great to have multiple people working on the same document. CVS
|
||
enables you to do this. You can have CVS tell you what changes
|
||
were made by another author while you were editing your copy, and
|
||
integrate those changes.
|
||
3. CVS keeps a log of what changes were made. These logs (and a date
|
||
stamp) can be placed automatically inside your documents when
|
||
they are published.
|
||
4. CVS can be combined with scripts 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 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,
|
||
because the whole publishing process has not been fully automated
|
||
yet.)
|
||
|
||
Note Access to our CVS repository
|
||
|
||
|
||
Only authors with at least three submissions get access to our CVS,
|
||
see Appendix C.
|
||
|
||
You can browse the LDP CVS repository via the web at
|
||
[http://cvs.tldp.org/] http://cvs.tldp.org/.
|
||
________________________________________________________________
|
||
|
||
C.1. Getting a CVS account
|
||
|
||
Caution CVS accounts will not be granted to all applicants
|
||
|
||
|
||
To be granted a CVS account you must qualify under one of the
|
||
following categories:
|
||
|
||
* authors with documents already in the collection who have made a
|
||
minimum of three submits to the LDP through <submit@en.tldp.org>
|
||
* technical and language reviewers approved by one of the Review
|
||
Coordinators
|
||
* new authors in the review process (also requires approval from
|
||
one of the Review Coordinators)
|
||
|
||
Please do not apply for a CVS account if you do not qualify.
|
||
|
||
If you qualify for a CVS account you may apply for one contacting CVS
|
||
master Sergiusz [mailto:ser@gnu.org] mailto:ser@gnu.org Include
|
||
information about which documents you maintain.
|
||
________________________________________________________________
|
||
|
||
C.2. Using CVS
|
||
|
||
C.2.1. Setting Up Your CVS Account
|
||
|
||
First you'll need to get an account at the LDP's CVS Repository.
|
||
Please see the notes above on obtaining an account. This repository
|
||
houses various documents including HOWTOs and Guides. Documents are
|
||
sorted by the type of document (for example a HOWTO or a Guide), and
|
||
by the markup language the document uses (for example DocBook or
|
||
LinuxDoc).
|
||
|
||
When your account is ready you can log in using one of the following
|
||
commands. In all instances your_userid should be replaced by the user
|
||
name you were issued in the response email. You will be prompted for
|
||
a password after this first step.
|
||
|
||
Initializing Your CVS Account
|
||
|
||
Linux system
|
||
cvs -d :pserver:your_userid@cvs.tldp.org:/cvsroot login
|
||
|
||
Windows system
|
||
set CVSROOT=":pserver:your_userid@cvs.tldp.org:/cvsroot"
|
||
|
||
cvs -d %CVSROOT% login
|
||
|
||
Wait patiently while the system tries to log you in. It can often
|
||
take more that 10-20 seconds for the system to either accept (or
|
||
reject) your password. Once you've used cvs login for the first time
|
||
and have been given access to the system, your password is stored in
|
||
.cvspass and you will not have to use cvs login again. Just set the
|
||
CVSROOT with the export command listed above and continue on. If
|
||
TLDP's CVS server is the only one you work with, you might also add
|
||
an export CVSROOT line to your ~/.bashrc shell configuration file.
|
||
________________________________________________________________
|
||
|
||
C.2.2. Getting the Documents
|
||
|
||
You can get the entire repository (about 150 MB) with: cvs checkout
|
||
LDP
|
||
|
||
Or you can get the source for your own document with: cvs checkout
|
||
LDP/howto/docbook/YOUR-HOWTO.xml OR cvs checkout
|
||
LDP/guide/docbook/YOURGUIDE
|
||
|
||
Windows users will need to use a modified version of this command.
|
||
Instead they should use: cvs -d %CVSROOT% checkout
|
||
LDP/howto/docbook/YOUR-HOWTO.xml
|
||
|
||
Note Keep an overview
|
||
|
||
|
||
checkout will add the full directory structure from tldp.org on down.
|
||
Although it doesn't really matter where you put these files on your
|
||
local file system you may not want to bury the directories too
|
||
deeply.
|
||
________________________________________________________________
|
||
|
||
C.2.3. CVS Commands
|
||
|
||
CVS Commands: a brief reminder
|
||
|
||
commit
|
||
This CVS command will upload your changes to the CVS server.
|
||
|
||
Please be sure to include a useful description of the changes
|
||
that have been made to your document.
|
||
|
||
If you want to bypass the editor screen you can use
|
||
|
||
cvs commit -m "A description of the work done on this version
|
||
of the document."
|
||
|
||
Note Ready for publication warning
|
||
|
||
|
||
You must still email <submit@en.tldp.org> when you are ready to have
|
||
your changes appear on the live site. Your email should include the
|
||
relative path to the file(s) in the LDP CVS tree that you wish to
|
||
update.
|
||
|
||
add
|
||
You can add new files to your CVS repository. These may be
|
||
image files or additional XML files. First check that your
|
||
HOWTO is in its own directory. You may want to coordinate with
|
||
the people at <submit@en.tldp.org> to ensure you can add
|
||
graphics or other files to your HOWTO.
|
||
|
||
Copy the files you want to add into your local CVS repository
|
||
(where all of your downloaded/working files are). Then:
|
||
|
||
cvs add filename
|
||
|
||
After you've added the files, you still need to commit them to
|
||
the repository (see above).
|
||
|
||
remove
|
||
|
||
$Id: cvs.xml,v 1.32 2011/01/14 16:24:52 serek Exp $
|
||
While this is not a CVS "command" it can be used to
|
||
automatically insert information about the file including the
|
||
time and date it was last modified, the version number it was
|
||
assigned by the CVS and the filename of this particular file.
|
||
The output will look like this: $Id: cvs.xml,v 1.9 2002/04/21
|
||
09:44:26 serek Exp $
|
||
|
||
If you need to change a file name, you still need to use the add
|
||
command. First remove the copy of the file from your local disk. Then
|
||
remove it from the CVS tree with: cvs remove filename. As with the
|
||
add command, you need to >commit your removed file. Finally, now that
|
||
the old file has been removed, add your new file using the
|
||
instructions above (first add and then commit the additional file).
|
||
________________________________________________________________
|
||
|
||
C.2.3.1. Recovering old versions
|
||
|
||
There you are, typing away, when you screw up. Real bad. Doesn't
|
||
matter what it is, but suffice it to say that you've toasted not only
|
||
the version on your local drive, but created a new version on the CVS
|
||
server. What you need to do is go back in time and resurrect an older
|
||
version of your file.
|
||
|
||
To do this, you'll need to know the version number of the file you
|
||
want to retrieve. cvs diff will give a list of revisions if there are
|
||
differences. You can pick the revision number, subtract one, and that
|
||
is probably the revision you want to look at.
|
||
|
||
The command
|
||
|
||
cvs -Q update -p -r revision filename
|
||
|
||
will output to stdout the contents of the revision version of
|
||
filename. You can pipe it to more or redirect the output to a file.
|
||
Conveniently, you can redirect stdout to a file called filename. Your
|
||
local file is now the revision you want, and
|
||
|
||
cvs update
|
||
|
||
will update the CVS server with the new (old) version of filename.
|
||
________________________________________________________________
|
||
|
||
C.3. CVS Resources
|
||
|
||
If you're completely new to CVS, there are a few web pages you may
|
||
want to look at which can help you out:
|
||
|
||
* [http://cvshome.org/docs/blandy.html]
|
||
http://cvshome.org/docs/blandy.html
|
||
* [http://www.loria.fr/~molli/cvs/doc/cvs_toc.html]
|
||
http://www.loria.fr/~molli/cvs/doc/cvs_toc.html
|
||
________________________________________________________________
|
||
|
||
Appendix D. DocBook: Sample Markup
|
||
|
||
D.1. General Tips and Tricks
|
||
|
||
For a general overview of what markup is all about, please read
|
||
Chapter 5
|
||
|
||
* An editor capable of inserting elements according to the DTD will
|
||
help a lot since it will enforce the DTD. This way you can be
|
||
sure that no invalid elements were added anywhere in your
|
||
document.
|
||
* In order to ensure that future changes are as easy as possible,
|
||
authors should try to keep compatibility with the XML version of
|
||
the DocBook DTD. This means keeping element names in lower case,
|
||
using double quotes in all attributes, and not omitting end tags.
|
||
Most tools that automatically insert elements (like psgml+emacs)
|
||
follow these rules automatically or with some fine tuning.
|
||
* Each type of document created has a specific structure. This
|
||
document is in "book" format. Most authors, however, will want to
|
||
use the shorter "article" format instead. Templates are available
|
||
from Appendix A.
|
||
________________________________________________________________
|
||
|
||
D.1.1. Useful markup
|
||
|
||
Table D-1 shows some markup that is useful for generating generic
|
||
documents. Remember that some elements are valid only on some
|
||
contexts.
|
||
|
||
Tip Check several formats
|
||
|
||
|
||
Sometimes the appearance of a particular tag changes from one
|
||
conversion format to another. As a beginner in DocBook writing, you
|
||
may wish to see how your document looks in several formats before you
|
||
publish them. You are advised to look at how your document is
|
||
presented in HTML, PDF and PostScript, since these formats will be
|
||
made available by TLDP once you publish your document.
|
||
|
||
Note Better too much than not enough
|
||
|
||
|
||
Since the formatting depends on the output style chosen, it's
|
||
recommended to use as much markup as possible. Even if the appearance
|
||
of the output doesn't seem to change with the standard output style,
|
||
there may be specific output formats that will make these tags stand
|
||
out.
|
||
|
||
Table D-1. Useful markup
|
||
Description Sample markup Result
|
||
E-mail address <email>address@domain</email> <address@domain>
|
||
About the author <author>...</author> (see example below)
|
||
Author's name
|
||
<firstname>Mary</firstname>
|
||
<othername>Margaret</othername>
|
||
<surname>O'Hara</surname>
|
||
|
||
Mary Margaret O'Hara
|
||
Keys' name (printings on the keyboard) <keycap>F1</keycap> F1
|
||
Symbol represented by the keys <keysym>KEY_F1</keysym> KEY_F1
|
||
Key's code <keycode>0x3B</keycode> 0x3B
|
||
Combinations or sequences of keys
|
||
<keycombo>
|
||
<keycap>Ctrl</keycap>
|
||
<keycap>S</keycap>
|
||
</keycombo>
|
||
|
||
Ctrl-S
|
||
Program Menus <guimenu>File</guimenu> File
|
||
Menu Items <guimenuitem>Save</guimenuitem> Save
|
||
Menu Sequences
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo>
|
||
<keycap>Ctrl</keycap>
|
||
<keycap>S</keycap>
|
||
</keycombo>
|
||
</shortcut>
|
||
<guimenu>File</guimenu>
|
||
<guimenuitem>Save</guimenuitem>
|
||
</menuchoice>
|
||
|
||
File->Save (Ctrl-S)
|
||
Mouse Button <mousebutton>left</mousebutton> left
|
||
Application Names <application>application</application> application
|
||
Text Bibliographical Reference <citation>reference</citation>
|
||
[reference]
|
||
Quote
|
||
<blockquote>
|
||
<attribution>Text Author</attribution>
|
||
<para>Quote Text.</para>
|
||
</blockquote>
|
||
|
||
|
||
|
||
Quote Text.
|
||
|
||
--Text Author
|
||
Index (NA) See Section D.4.
|
||
File Names
|
||
<filename>file</filename>
|
||
|
||
file
|
||
Directories
|
||
<filename id="directory">directory</filename>
|
||
|
||
directory/
|
||
Emphasize Text[a]
|
||
<emphasis>text</emphasis>
|
||
|
||
text
|
||
Footnotes
|
||
<footnote>
|
||
<para>Footnote text</para>
|
||
</footnote>
|
||
|
||
(See note at the end of this table for an example)
|
||
URLs
|
||
<ulink url="http://www.conectiva.com">Conectiva S.A.</>
|
||
|
||
[http://www.conectiva.com] Conectiva S.A.
|
||
Itemized (unnumbered) List
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>item</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>item</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
* item
|
||
* item
|
||
|
||
Ordered (numbered) List
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>item</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>item</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
1. item
|
||
2. item
|
||
|
||
Segmented List
|
||
<segmentedlist>
|
||
<title>Binary to decimal conversion</title>
|
||
<segtitle>Binary</segtitle>
|
||
<segtitle>Decimal</segtitle>
|
||
</seglistitem><seg>00</seg><seg>0</seg>
|
||
</seglistitem>
|
||
<seglistitem><seg>01</seg><seg>1</seg>
|
||
</seglistitem>
|
||
<seglistitem><seg>10</seg><seg>2</seg>
|
||
</seglistitem>
|
||
</segmentedlist>
|
||
|
||
Binary to Decimal Conversion
|
||
|
||
Binary: 00
|
||
|
||
Decimal: 0
|
||
|
||
Binary: 01
|
||
|
||
Decimal: 1
|
||
|
||
Binary: 10
|
||
|
||
Decimal: 2
|
||
Variable List
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Entry 1</term>
|
||
<listitem>
|
||
<para>Description</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Entry 2</term>
|
||
<listitem>
|
||
<para>Description</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
Entry 1
|
||
Description
|
||
|
||
Entry 2
|
||
Description
|
||
|
||
Simple Lists
|
||
<simplelist type="horiz" columns="3">
|
||
<member>1</member>
|
||
<member>2</member>
|
||
<member>3</member>
|
||
<member>4</member>
|
||
<member>5</member>
|
||
<member>6</member>
|
||
</simplelist>
|
||
<simplelist type="inline">
|
||
<member>A</member>
|
||
<member>B</member>
|
||
<member>C</member>
|
||
<member>D</member>
|
||
<member>E</member>
|
||
<member>F</member>
|
||
</simplelist>
|
||
|
||
1 2 3
|
||
4 5 6
|
||
|
||
A, B, C, D, E, F
|
||
Pictures (NA) See Section D.5
|
||
Glossary
|
||
<glossentry>
|
||
<glossterm>Term</glossterm>
|
||
<glossdef>
|
||
<para>Definition</para>
|
||
</glossdef>
|
||
</glossentry>
|
||
|
||
(See the glossary at the end of this document)
|
||
Crossed References
|
||
<section id="secao">
|
||
...
|
||
</section>
|
||
<section id="reference the other section">
|
||
...
|
||
<para>Please, see<xref linkend="secao" /> for more information.
|
||
|
||
(NA)
|
||
Notes:
|
||
a. Text can be emphasized in a few ways. The most common ways are
|
||
italics and bold. DocBook, however, supports only italics. The use of
|
||
bold requires additional settings on the style sheet used.
|
||
________________________________________________________________
|
||
|
||
D.2. <section> and <sectN>: what's the difference?
|
||
|
||
Note Acknowledgment
|
||
|
||
|
||
These notes were provided by: [http://geekhavoc.com] John Daily and
|
||
Saqib Ali (<saqib@seagate.com>).
|
||
|
||
<section> versus <sectN> is largely a question of flexibility. The
|
||
stylesheets can make a <section> in a <section> look just like a
|
||
<sect2> within a <sect1>, so there's no output advantage.
|
||
|
||
But, a <section> within a <section> can be extracted into its own
|
||
top-level section, nested even more deeply, or moved to an entirely
|
||
different part of the document, without it and its own <section>
|
||
children being renamed. That is not true of the numbered section
|
||
tags, which are very sensitive to rearrangements. This can be easier
|
||
for authors who are new to DocBook than using <sectN>.
|
||
|
||
The main idea behind creating structured data is that it should be
|
||
easy to access and query. One should be able to retrieve a subsection
|
||
of any structured data, by using querying languages for XML (XPath
|
||
and XQuery). <sectN> are useful when traversing a document using
|
||
XPath/XQuery. <sectN> gives more flexibility, and control while
|
||
writing an XPath expression.
|
||
|
||
A well-defined, valid and well-structured document makes it easier
|
||
for one to write XPath/Query to retreive "specific" data from a
|
||
document. For example you can use XPath to retrieve information in
|
||
the <sect3> block with certain attributes. However if you just used
|
||
<section> for all subsections, it becomes harder to retrieve the
|
||
block of information that you need.
|
||
|
||
So which one should you use? The one you feel most comfortable with
|
||
is a good place to start. This document is written with <section>s.
|
||
You may, or may not, think this is a good idea. :)
|
||
________________________________________________________________
|
||
|
||
D.3. Command Prompts
|
||
|
||
There are likely as many ways of doing this as there are DocBook
|
||
authors; however, here are two ways that you might find useful.
|
||
Thanks to [http://www.appaji.net/] Y Giridhar Appaji Nag and
|
||
[http://linux-ip.net/] Martin Brown for the markup used here.
|
||
|
||
Example D-1. Command Prompt with programlisting
|
||
<programlisting>
|
||
<prompt># </prompt><userinput><command>cd</command> /some/dir</userinp
|
||
ut>
|
||
<prompt># </prompt><userinput><command>ls</command> -l</userinput>
|
||
</programlisting>
|
||
|
||
Displays as:
|
||
# cd /some/dir
|
||
# ls -l
|
||
|
||
Example D-2. Command Prompt with screen
|
||
|
||
First create a general entity in the internal subset at the very
|
||
beginning of your document. This entity will define a name for the
|
||
shortcut which you can use to display the full prompt at any point in
|
||
your document. <!ENTITY prompt "<prompt>[user@machine
|
||
~/dir]$</prompt>">
|
||
|
||
For more information about entities, read Section D.8.
|
||
<screen>
|
||
&prompt; <userinput>cd /some/dir</userinput>
|
||
&prompt; <userinput>ls -l</userinput> </screen>
|
||
|
||
Displays as:
|
||
|
||
[user@machine ~/dir]$ cd /some/dir
|
||
[user@machine ~/dir]$ ls -l
|
||
|
||
If you would like to add the output of your commands you can add
|
||
<computeroutput> text</computeroutput> within the <screen> or
|
||
<programlisting> as appropriate.
|
||
________________________________________________________________
|
||
|
||
D.4. Encoding Indexes
|
||
|
||
The generation of indexes depends on the markups inserted in the
|
||
text.
|
||
|
||
Such markups will be processed afterwards by an external tool and
|
||
will generate the index. An example of such a tool is the
|
||
collateindex.pl script (see Section B.6.2). Details about the process
|
||
used to generate these indexes are shown in Section B.6.2.
|
||
|
||
The indexes have nesting levels. The markup of an index is done by
|
||
the code Example D-3.
|
||
|
||
Example D-3. Code for the generation of an index
|
||
<indexterm>
|
||
<primary>Main level</primary>
|
||
<secondary>Second level</secondary>
|
||
<tertiary>Third level</tertiary>
|
||
</indexterm>
|
||
|
||
It is possible to refer to chapters, sections, and other parts of the
|
||
document using the attribute zone.
|
||
|
||
Example D-4. Use of the attribute zone
|
||
<section id="encoding-index">
|
||
<title>Encoding Indexes</title>
|
||
<indexterm zone="encoding-index">
|
||
<primary>edition</primary> <secondary>index</secondary>
|
||
</indexterm>
|
||
|
||
<para>
|
||
The generation of indexes depend on the inserted markups on the text.
|
||
</para>
|
||
|
||
The Example D-4 has the code used to generate the entry of this
|
||
edition on the index. In fact, since the attribute zone is used, the
|
||
index statement could be located anywhere in the document or even in
|
||
a separate file.
|
||
|
||
However, to facilitate maintenance the entries for the index were all
|
||
placed after the text to which it refers.
|
||
|
||
Example D-5. Usage of values startofrange and endofrange on the
|
||
attributeclass
|
||
<para>Typing the text normally
|
||
sometimes there's the need of
|
||
<indexterm class="startofrange"
|
||
id="example-band-index">
|
||
<primary>examples</primary> <secondary>index</secondary>
|
||
</indexterm> mark large amounts of
|
||
text.</para>
|
||
|
||
<para>Keep inserting the paragraphs
|
||
normally.</para>
|
||
|
||
<para>Until the end of the section
|
||
intended to be indexed. <indexterm
|
||
startref="example-band-index" class="endofrange">.
|
||
</para>
|
||
________________________________________________________________
|
||
|
||
D.5. Inserting Pictures
|
||
|
||
It is necessary to insert pictures formats for all possible finished
|
||
document types. For example: JPG files for web pages and EPS for
|
||
PostScript and PDF files.
|
||
|
||
If you use the TeX format you'll need the images as a PostScript
|
||
file. For on-line publishing you can use any kind of common image
|
||
file, such as JPG, GIF or PNG.
|
||
|
||
The easiest way to insert pictures is to use the fileref attribute.
|
||
Usually pictures are generated in JPG and in PostScript (PS or EPS).
|
||
|
||
Example D-6. Inserting a picture
|
||
<figure>
|
||
<title>Picture's
|
||
Title</title> <graphic fileref="images/file"></graphic>
|
||
</figure>
|
||
|
||
Replacing <figure> by <informalfigure> eliminates the need to insert
|
||
a title for the picture.
|
||
|
||
There's still the float attribute on which the value 0 indicates that
|
||
the picture should be placed exactly where the tag appears. The value
|
||
1 allows the picture to be moved to a more convenient location (this
|
||
location can be described on the style sheet, or it can be controlled
|
||
by the application).
|
||
________________________________________________________________
|
||
|
||
D.5.1. Graphics formats
|
||
|
||
When submitting graphics to the LDP, please submit one set of
|
||
graphics in .eps, and another in .gif, .jpg or .png. The preferred
|
||
format is .png or .jpg due to patent problems with .gif.
|
||
|
||
You can use .jpg files for continuous-tone images such as photos or
|
||
images with gradual changes in color. Use .png for simple images like
|
||
diagrams, some screen shots, and images with a low number of colors.
|
||
________________________________________________________________
|
||
|
||
D.5.2. Alternative Methods
|
||
|
||
The first alternative to Example D-6 is to eliminate the <figure> or
|
||
<informalfigure> elements.
|
||
|
||
Another interesting alternative when you have decided to publish the
|
||
text on media where pictures are not accepted, is the use of a
|
||
wrapper, <imageobject>.
|
||
|
||
Example D-7. Using <imageobject>
|
||
<figure>
|
||
<title>Title</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/file.eps" format="EPS">
|
||
</imageobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/file.jpg" format="JPG">
|
||
</imageobject>
|
||
<textobject>
|
||
<phrase>Here there's an image of this example</phrase>
|
||
</textobject>
|
||
<caption>
|
||
<para>Image Description. Optional. </para>
|
||
</caption>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
Files using the following formats are available BMP, CGM-BINARY,
|
||
CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, GIF87A,
|
||
GIF89A, IGES, JPEG, JPG, LINESPECIFIC, PCX, PIC, PS, SGML, TBL, TEX,
|
||
TIFF, WMF, WPG.
|
||
|
||
This method presents an advantage: a better control of the
|
||
application. The elements <imageobject> are consecutively tested
|
||
until one of them is accepted. If the output format does not support
|
||
images the <textobject> element will be used. However, the biggest
|
||
advantage in usage of the format Example D-7 is that in DocBook 5.0,
|
||
the <graphic> element will cease to exist.
|
||
|
||
As a disadvantage, there is the need for more than one representation
|
||
code of the same information. It is up to the author to decide how
|
||
they will implement illustrations and pictures in the document, but
|
||
for compatibility with future versions I recommend the use of this
|
||
method for pictures and graphics.
|
||
|
||
Warning Title page exception
|
||
|
||
|
||
<mediaobject>s will not display if they are used on a title page. For
|
||
more information read:
|
||
[http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage]
|
||
http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage
|
||
|
||
Note ASCII Images
|
||
|
||
|
||
You may also want to try converting your image to an ASCII
|
||
representation of the file. JavE (Java ASCII Versatile Editor) can do
|
||
this conversion for you. It can be downloaded from
|
||
[http://www.jave.de/] http://www.jave.de/. It has an easy to use GUI
|
||
interface.
|
||
|
||
If you're more command-line oriented you may want to try: tgif
|
||
([http://bourbon.usc.edu:8001/tgif/]
|
||
http://bourbon.usc.edu:8001/tgif/) and AA-Lib
|
||
([http://aa-project.sourceforge.net/]
|
||
http://aa-project.sourceforge.net/).
|
||
________________________________________________________________
|
||
|
||
D.6. Markup for Metadata
|
||
|
||
D.6.1. Crediting Translators, Converters and Co-authors
|
||
|
||
There are several ways that these folks, as well as other
|
||
contributors to your document, can be given some recognition for the
|
||
help they've given you.
|
||
________________________________________________________________
|
||
|
||
D.6.1.1. <othercredit>
|
||
|
||
All translators, converters and co-authors should be credited with an
|
||
<othercredit> tag entry. To properly credit a translator or
|
||
converter, use the <othercredit> tag with the role attribute set to
|
||
"converter" or "translator", as indicated in the example below:
|
||
|
||
Example D-8. Other Credit
|
||
<othercredit role='converter'>
|
||
<firstname>David</firstname>
|
||
<surname>Merrill</surname>
|
||
<contrib>Conversion from HTML to DocBook v3.1 (SGML).</contrib>
|
||
</othercredit>
|
||
________________________________________________________________
|
||
|
||
D.6.1.2. Crediting Editors and Reviewers
|
||
|
||
To help track the review process all new documents must include a
|
||
reference to the reviewers for the
|
||
[http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html]
|
||
technical,
|
||
[http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/languagereview.html]
|
||
language and
|
||
[http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/metadatareview.html]
|
||
metadata reviews.
|
||
|
||
Example D-9. Editor
|
||
<editor>
|
||
<firstname>Tabatha</firstname>
|
||
<surname>Marshall</surname>
|
||
<contrib>Language review of version 0.8</contrib>
|
||
</editor>
|
||
________________________________________________________________
|
||
|
||
D.6.2. <revremark>s
|
||
|
||
Within the <revision> tag hierarchy is a tag called <revremark>.
|
||
Within this tag, you can make any brief notes you wish about each
|
||
particular revision of your document.
|
||
________________________________________________________________
|
||
|
||
D.6.3. Revision History
|
||
|
||
The <revhistory> tag should be used to denote the various revisions
|
||
of the document. Specify the date, revision number and comments
|
||
regarding what has changed.
|
||
|
||
Revisions should be listed with the most-recent version at the top
|
||
(list in descending order).
|
||
________________________________________________________________
|
||
|
||
D.6.4. Date formats
|
||
|
||
The <pubdate> tag in your header should list the publication date of
|
||
this particular version of the document (coincide with the revision
|
||
date). It should be in the following format:
|
||
<pubdate>2002-04-25</pubdate>
|
||
|
||
The date is in the format YYYY-MM-DD, which is one of the
|
||
[http://www.w3.org/TR/NOTE-datetime] ISO 8601 standard formats for
|
||
representing dates. For you Yanks out there (me too), think of it as
|
||
going from the largest unit of time to the smallest.
|
||
________________________________________________________________
|
||
|
||
D.6.5. Sample Article (or Book) Information Element
|
||
|
||
Here is a sample of a complete DocBook (SGML or XML) <articleinfo>
|
||
element which contains some of the items and constructs previously
|
||
described.
|
||
|
||
Example D-10. Sample Meta Data
|
||
<!--
|
||
Above these lines in a typical DocBook article would be the article
|
||
element (the immediate parent of the articleinfo element) and above
|
||
that typically, the DOCTYPE declaration and internal subset.
|
||
-->
|
||
|
||
<articleinfo>
|
||
|
||
<!--
|
||
Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
|
||
-->
|
||
|
||
<title>Sample HOWTO</title>
|
||
|
||
<author>
|
||
<firstname>Your Firstname</firstname>
|
||
<surname>Your Surname</surname>
|
||
<affiliation>
|
||
<address><email>your email</email></address>
|
||
</affiliation>
|
||
</author>
|
||
|
||
<editor>
|
||
<firstname>Tabatha</firstname>
|
||
<surname>Marshall</surname>
|
||
<contrib>Language review of version 0.8</contrib>
|
||
</editor>
|
||
|
||
<othercredit role='converter'>
|
||
<firstname>David</firstname>
|
||
<surname>Merrill</surname>
|
||
<contrib>Conversion from HTML to DocBook v3.1 (SGML).</contrib>
|
||
</othercredit>
|
||
|
||
<pubdate>YYYY-MM-DD</pubdate>
|
||
|
||
<revhistory>
|
||
<revision>
|
||
<revnumber>1.0</revnumber>
|
||
<date>YYYY-MM-DD</date>
|
||
<authorinitials>ABC</authorinitials>
|
||
</revremark>first official release</revremark>
|
||
</revision>
|
||
|
||
<revision>
|
||
<revnumber>0.9</revnumber>
|
||
<date>YYYY-MM-DD</date>
|
||
<authorinitials>ABC</authorinitials>
|
||
<revremark>First draft</revremark>
|
||
</revision>
|
||
</revhistory>
|
||
|
||
<!--
|
||
Provide a good abstract; a couple of sentences is sufficient
|
||
-->
|
||
|
||
<abstract>
|
||
<para>
|
||
This is a sample DocBook (SGML or XML) HOWTO which has been
|
||
constructed to serve as a template.
|
||
</para>
|
||
</abstract>
|
||
|
||
</articleinfo>
|
||
________________________________________________________________
|
||
|
||
D.7. Bibliographies
|
||
|
||
Not everyone will choose to use the correct formatting for a
|
||
bibliography. Most will use a list of some kind. And that's ok. But
|
||
when you're ready to move to the next level, here's how to do it.
|
||
|
||
Below are two examples of bibliographic entries. The first is a very
|
||
simple entry. It has only a title, URL and possibly a short
|
||
description (abstract). The second is a little more complex and is
|
||
for a full entry (for instance a book) with an ISBN, publisher and
|
||
copyright date.
|
||
|
||
Note DocBook requirements for bibliographic references
|
||
|
||
|
||
At least one element within <biblioentry> is required, but it doesn't
|
||
matter which one you have. So you might have a <title>, or a URL
|
||
(<bibliosource>), or an <author>, or, ...
|
||
|
||
For a full list of all options, visit
|
||
[http://docbook.org/tdg/en/html/biblioentry.html]
|
||
http://docbook.org/tdg/en/html/biblioentry.html. For more examples
|
||
visit [http://docbook.org/tdg/en/html/bibliography.html]
|
||
http://docbook.org/tdg/en/html/bibliography.html.
|
||
|
||
Caution Displaying <abstract> content
|
||
|
||
|
||
By default <abstract>s do not display on web pages. You need to
|
||
modify the biblio.xsl file. Do a search for the word "abstract" and
|
||
then add this information inside the <xsl:template> tags. If that
|
||
doesn't make sense, don't worry about it too much, but do be aware
|
||
that it's required for the abstracts to show up.
|
||
<div xmlns="http://www.w3.org/1999/xhtml" class="{name(.)}">
|
||
<xsl:apply-templates mode="bibliography.mode"/>
|
||
</div>
|
||
|
||
Example D-11. A Bibliography
|
||
<bibliography>
|
||
<title>Bibliography title</title>
|
||
|
||
<bibliodiv>
|
||
<title>Section title</title>
|
||
<biblioentry>
|
||
<title>Book or Web Site Title</title>
|
||
<bibliosource><ulink url=""/></bibliosource>
|
||
<abstract></abstract>
|
||
</biblioentry>
|
||
|
||
<biblioentry>
|
||
<title></title>
|
||
<bibliosource><ulink url=""/></bibliosource>
|
||
<author><firstname></firstname><surname></surname></author>
|
||
<copyright><year></year>
|
||
<holder></holder></copyright>
|
||
<editor><firstname></firstname><surname></surname></editor>
|
||
<isbn></isbn>
|
||
<publisher>
|
||
<publishername></publishername>
|
||
</publisher>
|
||
<abstract></abstract>
|
||
</biblioentry>
|
||
</bibliodiv>
|
||
</bibliography>
|
||
|
||
View References to see this in action.
|
||
________________________________________________________________
|
||
|
||
D.8. Entities (shortcuts, text macros and re-usable text)
|
||
|
||
There may be some segments of text, or markup that you want to use
|
||
over and over again. Instead of typing it up multiple times (and then
|
||
having to edit it multiple times if you want to make a change) you
|
||
can use external entities. Entities can give you a short cut to:
|
||
re-using whole documents, text snippets, and special markup. Some
|
||
common ways to use an entity would be for:
|
||
|
||
* text macros for markup. An example would be a company URL. By
|
||
using a parameter entity you could refer simply to
|
||
&my-company-url; instead of typing out the full <ulink
|
||
url="http://foo.bar">Foo.bar</ulink> each time.
|
||
* software license. Such as the GNU Free Documentation License: it
|
||
is long. And must be included in full in each document. By
|
||
leaving the license in a separate file you can easily include it
|
||
in many documents without having to redo the markup each time.
|
||
* repeated text. For instance an introduction to a topic which is
|
||
included both as a summary in one section and as an introduction
|
||
to the full information in another. Saves on editing time if you
|
||
need to make changes to both sets of text.
|
||
|
||
Example D-12. Adding Entities
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||
<-- I can add comments here -->
|
||
<!ENTITY shortcut "Replace 'shortcut' with this text.">
|
||
|
||
<!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
|
||
<-- note: the square bracket on the third line is closed on the next
|
||
line--> ]>
|
||
|
||
To use these entities simply insert the name you gave the entity
|
||
between a "&" (ampersand) and a ";" (semicolon). For example:
|
||
"&shortcut;" would expand into "Replace 'shortcut' with this text";
|
||
"&sc-to-a-file;" would include the full contents of whatever is in
|
||
anotherfile.xml.
|
||
|
||
An important feature while writing a text is the ability to check
|
||
whether or not it will be presented in the final draft. It is common
|
||
to have several parts of the text marked as draft, especially when
|
||
updating an already existing document.
|
||
|
||
With the use of parameter entities, you can include or eliminate
|
||
these drafts by altering only one line at the beginning of a
|
||
document.
|
||
|
||
Example D-13. Use of parameter entities
|
||
<!ENTITY % review "INCLUDE"> ...
|
||
<![%review;[ <para>This paragraph will
|
||
be included on the draft when the entity "review" is defined with the
|
||
value "INCLUDE". </para> ]]>
|
||
|
||
The entity review might have several texts defined, as in Example
|
||
D-13. When the changes to the text are considered final, you need
|
||
only to remove parts of the text between the 3^rd. and 6^th. lines.
|
||
|
||
To keep the draft definitions and hide the text in the final draft,
|
||
just alter the specification of the entity from INCLUDE to IGNORE.
|
||
________________________________________________________________
|
||
|
||
D.9. Customizing your HTML files
|
||
|
||
D.9.1. HTML file names
|
||
|
||
By default, when separate HTML files are made, the SGML processor
|
||
will assign arbitrary names to the resulting files. This can be
|
||
confusing to readers who may bookmark a page only to have it change.
|
||
Whatever your reasoning, here's how to make separate files named the
|
||
way you want:
|
||
|
||
In your first <article> tag (which should be the only one) include an
|
||
id parameter and call it "index". This will make your tag look like
|
||
this:
|
||
<article id="index">
|
||
|
||
Do not modify the first <chapter> tag, as it's usually an
|
||
introduction and you want that on the first page. For each other
|
||
<section> tag, include the id parameter and name it. A name should
|
||
include only alphanumeric characters, and it should be short enough
|
||
to understand what it is.
|
||
|
||
<chapter id="tips">
|
||
|
||
Note Pick section IDs intelligently
|
||
|
||
|
||
We all know that Cool URIs Don't Change. This means your ids should
|
||
not change either. Unless of course the content for the id has
|
||
changed substantially and the id name is no longer relevant.
|
||
|
||
Warning HTML file name generation using Jade
|
||
|
||
|
||
If you are using Jade to transform your DocBook into HTML you must
|
||
use the following parameter: -V %use-id-as-filename%.
|
||
________________________________________________________________
|
||
|
||
D.9.2. Headers and Footers
|
||
|
||
There is no "easy" way to add headers and footers to your document.
|
||
If you are using DocBook XSL and doing your own document
|
||
transformations you may customize the XSL template to suit your
|
||
needs. For more information read
|
||
[http://www.sagehill.net/docbookxsl/HTMLHeaders.html]
|
||
http://www.sagehill.net/docbookxsl/HTMLHeaders.html.
|
||
________________________________________________________________
|
||
|
||
Appendix E. Converting Documents to DocBook XML
|
||
|
||
A variety of free and commercial tools exist for doing "up
|
||
conversion" of non-XML formats to DocBook. A few are listed here for
|
||
your convenience. A more comprehensive list is available from
|
||
[http://wiki.docbook.org/topic/ConvertOtherFormatsToDocBook] Convert
|
||
Other Formats to DocBook.
|
||
________________________________________________________________
|
||
|
||
E.1. Text to DocBook
|
||
|
||
The txt2docbook tool allows one to convert a ascii (README-like) file
|
||
to a valid docbook xml document. It simplifies the publishing of
|
||
rather small papers significantly. The input format was inspired by
|
||
the APT-Convert tool from [http://www.xmlmind.com/aptconvert.html]
|
||
http://www.xmlmind.com/aptconvert.html.
|
||
|
||
The script can be downloaded from
|
||
[http://txt2docbook.sourceforge.net/]
|
||
http://txt2docbook.sourceforge.net/.
|
||
________________________________________________________________
|
||
|
||
E.2. OpenOffice.org to DocBook
|
||
|
||
As of [http://www.openoffice.org] OpenOffice.org (OOo) 1.1RC there
|
||
has been support for exporting files to DocBook format.
|
||
|
||
Although OOo uses the full DocBook document type declaration, it does
|
||
not actually export the full list of DocBook elements. It uses a
|
||
"simplified" DocBook tag set which is geared to on-the-fly rendering.
|
||
(Although it is not the official Simplified DocBook which is
|
||
described in Section B.5.) The OpenOffice simplified (or "special"
|
||
docbook) is available from [http://www.chez.com/ebellot/ooo2sdbk/]
|
||
http://www.chez.com/ebellot/ooo2sdbk/.
|
||
________________________________________________________________
|
||
|
||
E.2.1. Open Office 1.0.x
|
||
|
||
OOo has been tested by LDP volunteers with mostly positive results.
|
||
Thanks to Charles Curley ([http://www.charlescurley.com]
|
||
charlescurley.com) for the following notes on using OOo version
|
||
1.0.x:
|
||
|
||
Note Check the version of your OpenOffice
|
||
|
||
|
||
These notes may not apply to the version of OOo you are using.
|
||
|
||
* 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.
|
||
Contrary to the OOo documentation, the Linux OOo did not come
|
||
with a JRE. I got one from Sun.
|
||
* The exported file has lots of empty lines. My 54 line exported
|
||
file had 5 lines of actual XML code.
|
||
* There was no effort at pretty printing.
|
||
* The header is: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE
|
||
article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
||
* The pull-down menu in the File->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?
|
||
* There is NO documentation on the DocBook export filter or whether
|
||
OOo will import it again.
|
||
|
||
Conclusions: OOo 1.1RC is worth looking at if you want a word
|
||
processor for preparing DocBook documents.
|
||
|
||
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.
|
||
________________________________________________________________
|
||
|
||
E.2.2. Open Office 1.1
|
||
|
||
[http://www.merlinmonroe.com] Tabatha Marshall offers the following
|
||
additional information for OOo 1.1.
|
||
|
||
The first problem was when I tried to do everything on version
|
||
1.0.1. That was obviously a problem. I have RH8, and it was
|
||
installed via rpm packages, so I ripped it out and did a full, new
|
||
install of OpenOffice 1.1. It took a while to find out 1.1 was a
|
||
requirement for XML to work.
|
||
|
||
During the install process I believe I was offered the choice to
|
||
install the XML features. I have a tendency to do full installs of
|
||
my office programs, so I selected everything.
|
||
|
||
I can't offer any advice to those trying to update their current
|
||
OO 1.1. Their "3 ways" aren't documented very well at the site
|
||
([http://xml.openoffice.org] xml.openoffice.org) and as of this
|
||
writing, I can't even find THAT on their site anymore. I think
|
||
more current documentation is needed there to walk people through
|
||
the process. Most of this was unclear and I had to pretty much
|
||
experiment to get things working.
|
||
|
||
Well, after I installed everything I had some configuration to do.
|
||
I opened the application, and got started by opening a new file,
|
||
choosing templates, then selecting the DocBook template. A nice
|
||
menu of Paragraph Styles popped up for me, which are the names for
|
||
all those tags, I noticed (you can see I don't use WYSIWYG often).
|
||
|
||
With a blank doc before me (couldn't get to the XML Filter
|
||
Settings menu unless some type of doc was opened), I went into
|
||
Tools->XML Filter Settings, and edited the entry for DocBook file.
|
||
I configured mine as follows:
|
||
|
||
* Doctype -//OASIS//DTD DocBook XML V4.2//EN
|
||
* DTD http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd
|
||
* XSLT for export
|
||
/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl
|
||
* XSLT for import
|
||
/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffhe
|
||
adings.xsl (this is the default)
|
||
* Template for import
|
||
/home/tabatha/OpenOffice/user/template/DocBook
|
||
File/DocBookTemplate.stw
|
||
|
||
At first, if I opened an XML file that had even one parsing error,
|
||
it would just open the file anyway and display the markup in OO. I
|
||
have many XML files that use © and other types of entities
|
||
which show up as parse errors (depending on the encoding) even
|
||
though they can be processed through. But today I was unable to
|
||
open any of those files. I got input/output errors instead. Still
|
||
investigating that one.
|
||
|
||
However when you do successfully open a document (one parsing with
|
||
no errors), it puts it automatically into WYSIWYG based on the
|
||
markup, and you can then work from the paragraph styles menu like
|
||
any other such editor.
|
||
|
||
To validate the document, I used Tools->XML Filter Settings, then
|
||
clicked the Test XSLTs button. On my screen, I set up the XSLT for
|
||
export to be ldp-html.xsl. If you test and there are errors, a new
|
||
window pops up with error messages at the bottom, and the lines
|
||
that need to be changed up at the top. You can change them there
|
||
and progress through the errors until they're all gone, and keep
|
||
testing until they're gone.
|
||
|
||
If you want to open a file to see the source instead of the
|
||
processed results, go to Tools->XML Filter Settings->Test XSLTs,
|
||
and then under the Import section, check the Display Source box.
|
||
My import XSLT is currently docbooktosoffheadings.xsl (the
|
||
default) and the template for import is DocBookTemplate.stw (also
|
||
default).
|
||
|
||
I think this might work for some people, but unfortunately not for
|
||
me. I've never used WYSIWYG to edit markup. Emacs with PSGML can
|
||
tell me what my next tag is no matter where I am, validate by
|
||
moving through the trouble spots, and I can parse and process from
|
||
command line.
|
||
|
||
With OpenOffice, you have to visit
|
||
[http://xml.openoffice.org/filters.html]
|
||
http://xml.openoffice.org/filters.html to find conversion tools.
|
||
________________________________________________________________
|
||
|
||
E.3. Microsoft Word to DocBook
|
||
|
||
Even if you want to use MS Word to write your documents, you may find
|
||
[http://www.docsoft.com/w2xmlv2.htm] w2XML useful. Note that this is
|
||
not free software--the cost is around $130USD. There is, however, a
|
||
trial version of the software.
|
||
________________________________________________________________
|
||
|
||
E.4. LaTeX to DocBook
|
||
|
||
Siep Kroonenberg reports that there is a package tex4ht
|
||
[http://www.cse.ohio-state.edu/~gurari/TeX4ht/]
|
||
http://www.cse.ohio-state.edu/~gurari/TeX4ht/ that converts TeX and
|
||
LaTeX to various flavors of XML. Currently, its support for DocBook
|
||
output is limited. If you want to use tex4ht in its current state for
|
||
LDP you will probably have to hack your LaTeX source beforehand and
|
||
the generated XML afterwords.
|
||
________________________________________________________________
|
||
|
||
E.5. LyX to DocBook
|
||
|
||
This section is contributed by Chris Karakas.
|
||
|
||
You can use the LyX-to-X package to write your document conveniently
|
||
in LyX (a visual editor originally developped as a graphical frontend
|
||
to LaTeX), then export it to DocBook SGML and submit it to The LDP.
|
||
This method is presented by [http://www.karakas-online.de] Chris
|
||
Karakas Document processing with LyX and SGML.
|
||
|
||
In the LyX-to-X project, LyX is used as a comfortable graphical SGML
|
||
editor. Once the document is exported to SGML from LyX, it undergoes
|
||
a series of transformations through sed and awk scripts that correct
|
||
the SGML code, computes the Index, inserts the Bibliography and the
|
||
Appendix and takes care of the correct invocation of openjade,
|
||
pdftex, pdfjadetex and all the other necessary programs for the
|
||
generation of HTML (chunked or not), PDF (with images, bookmarks,
|
||
thumbnails and hyperlinks), PS, RTF and TXT versions.
|
||
|
||
All aspects of document processing are handled, including automatic
|
||
Index generation, display of Mathematics in TeX quality both online
|
||
and in print formats, as well as the use of bibliographic databases
|
||
with [http://refdb.sourceforge.net/] RefDB. Special care is taken so
|
||
that the document processing is as transparent to the user as
|
||
possible - the aim being that the user writes in LyX, then presses a
|
||
button, and the LyX-to-X script does the rest. Download the
|
||
documentation and the LyX-to-X package from the
|
||
[http://www.karakas-online.de/mySGML/formats.html] Formats section.
|
||
________________________________________________________________
|
||
|
||
E.6. DocBook to DocBook Transformations
|
||
|
||
E.6.1. XML and SGML DocBook
|
||
|
||
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.
|
||
|
||
For others, here is a list of what you should keep in mind when
|
||
converting your documents from SGML to XML.
|
||
|
||
Note Differences between XML and SGML elements
|
||
|
||
|
||
An XML 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.
|
||
<filename class="directory">/usr/local<filename>
|
||
|
||
The start tag contains one attribute (class) with a value of
|
||
"directory". The end tag (also filename) must not contain any
|
||
attributes.
|
||
|
||
* Element names (tags) and their attributes are
|
||
case-dependent--typically lowercase. The following will not
|
||
validate because the end tag <PARA> is uppercase:
|
||
|
||
<para>This part will fail XML validation</PARA>
|
||
|
||
* All attributes in the start tag must be "quoted". This can be
|
||
either single (') or double (") quotes, but not reverse (`) or
|
||
"smart quotes". 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.
|
||
* Tags that have a start tag, but no end tag are referred to as
|
||
"empty" because they do not contain (wrap around) anything. These
|
||
tags must still be closed with a trailing slash (/). For example:
|
||
xref must be written as <xref linkend="software"/>. You may not
|
||
have any spaces between the / and >. (Although you may have a
|
||
space after the final attribute: <xref linkend="foo" />.)
|
||
* Processing instructions that get sent to the transformation
|
||
engine (DSSSL or XSLT) and must have a question mark at the end
|
||
of the tag. All processing instructions are removed from the
|
||
output stream. The XML version of this tag would look like this:
|
||
|
||
<?dbhtml filename="foo"?>
|
||
|
||
* 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.
|
||
* Tag minimizations were used in SGML instead of writing out the
|
||
element name in the end tag. Example: <para>This is foo.</> Tag
|
||
minimizations are not supported in XML and their use is
|
||
discouraged in DocBook.
|
||
________________________________________________________________
|
||
|
||
E.6.2. Changing DTDs
|
||
|
||
The significant changes between version changes in the DTD involve
|
||
changes to the elements (tags). Elements may be: deprecated (which
|
||
means they will be removed in future versions); removed; modified; or
|
||
added. Almost all authors will run into a changed or deprecated tag
|
||
when going from a lower version of DocBook to a higher version.
|
||
|
||
DocBook: The Definitive Guide 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 note must contain a para. If
|
||
you try to write <note>Content in a note</note> your document will
|
||
not validate. Learning how elements are assembled will make it a lot
|
||
easier to understand any validation errors that are thrown at you. If
|
||
you get truly stuck you can also email the LDP's docbook mailing list
|
||
for extra hints. Information on subscribing is available from Section
|
||
2.2
|
||
|
||
All tags that have been deprecated or changed for 4.x are listed in
|
||
DocBook: The definitive guide, published by O'Reilly and Associates.
|
||
This book is also available on-line from [http://www.docbook.org]
|
||
http://www.docbook.org.
|
||
________________________________________________________________
|
||
|
||
E.6.2.1. Differences between version 3.x and 4.x
|
||
|
||
Here are a few elements that are of particular relevance to LDP
|
||
authors:
|
||
|
||
* artheader. has been changed to articleinfo. Most other header
|
||
elements have been renamed to info.
|
||
* graphic. has been deprecated and will be removed as of DocBook
|
||
5.x. To prepare for this, start using mediaobject. There is more
|
||
information about mediaobject in Section D.5.
|
||
* imagedata. file formats must now be written in UPPERCASE letters.
|
||
If you use lowercase or mixed-case spellings for your file
|
||
formats, it will fail.
|
||
Valid:
|
||
|
||
<imagedata format="EPS" fileref="foo.eps">
|
||
|
||
Invalid:
|
||
|
||
<imagedata format="eps" fileref="foo.eps">
|
||
|
||
Glossary
|
||
|
||
Abiword
|
||
Open Source word processor.
|
||
|
||
aspell
|
||
Spell check program.
|
||
|
||
attribute
|
||
An attribute makes available extra information regarding the
|
||
element on which it appears. The attributes always appear as a
|
||
name-value pair on the initialization pointers (i.e. the
|
||
"start tag"). Example of an attribute is id="identification",
|
||
which gives the attribute id the value identification.
|
||
|
||
Cascading Style Sheet (CSS)
|
||
Set of overlay rules that are read by your HTML browser, which
|
||
uses these rules for doing the display, layout and formatting
|
||
of the XML-generated HTML file(s). CSS allows for fast changes
|
||
in look and feel without having to plunge in the HTML file(s).
|
||
|
||
Catalog
|
||
Helper file for the display and transformation tools, which
|
||
maps public identifiers and URLs to the local file system.
|
||
|
||
Concurrent Versions System (CVS)
|
||
A common document management system used by the LDP.
|
||
|
||
DocBook
|
||
An SGML (and XML) application, describing a document format
|
||
that allows easy management of documentation.
|
||
|
||
docbook-utils
|
||
Software package easing XML conversions.
|
||
|
||
Document Type Definition (DTD)
|
||
A group of statements that define element names and their
|
||
attributes specifying the rules for combinations and
|
||
sequences. It's the DTD that defines which elements can or
|
||
cannot be inserted in the given context.
|
||
|
||
DSSSL
|
||
DSSSL stands for Document Style Semantics and Specification
|
||
Language. It's an ISO standard (ISO/IEC 10179:1996). The DSSSL
|
||
standard is internationally used as a language for documents
|
||
style sheets pages for SGML.
|
||
|
||
element
|
||
The elements describe the content's structure in a document.
|
||
Most elements contain a start tag, content and a closing tag.
|
||
For example a paragraph element includes all of the following
|
||
<para>This is the paragraph.</para>. Some elements are "empty"
|
||
and do not contain content and a closing tag. An example of
|
||
this is a link to an external document where the URL is
|
||
printed to the page. This element would include only the
|
||
following <ulink url="http://google.com/>.
|
||
|
||
Emacs
|
||
Popular text editor, especially on UNIX systems or alikes.
|
||
|
||
entity
|
||
An entity is a name designated for some part of data so that
|
||
it can be referenced by a name. The data could be anything
|
||
from from simple characters to chapters to sets of statements
|
||
in a DTD. Entity parameters can be generic, external, internal
|
||
or SGML data. An entity is similar to a variable in a
|
||
programming language, or a macro.
|
||
|
||
epcEdit
|
||
Cross-platform XML editor.
|
||
|
||
external entity
|
||
An external entity points to an external document. External
|
||
entities are used to include texts on certain locations of a
|
||
SGML document. It could be used to include sample screens,
|
||
legal notes, and chapters for example.
|
||
|
||
float
|
||
Objects such as side bars, pictures, tables, and charts are
|
||
called floats when they don't have a fixed placement on the
|
||
text. For printed text, a chart can appear either at the top
|
||
or at the bottom of the page. It can also be placed on the
|
||
next page if it is too large.
|
||
|
||
Frequently Asked Questions (FAQ)
|
||
LDP hosts a number of documents that are a list in the form of
|
||
questions and answers. These documents are called FAQs. A FAQ
|
||
is usually a single-page document.
|
||
|
||
generic entities
|
||
An entity referenced by a name, which starts with "&" and ends
|
||
with semicolon is a generic entity. Most of the time this type
|
||
of entity is used in the document and not on the DTD. There
|
||
are two types of entities: external and internal. They can
|
||
refer to special characters or to text objects such as
|
||
repeated sentences, names or chapters.
|
||
|
||
GNU Free Documentation License (GFDL)
|
||
Like the GNU Public License for free software, but with
|
||
specifics for written text and documentation with software.
|
||
|
||
GNU Public License (GPL)
|
||
License type for software that guarantees that the software
|
||
remains freely distributable, that the source code is
|
||
available, that you can make changes to it and redistribute
|
||
those changes if you want, on the condition that you keep on
|
||
using the same license for your derived works.
|
||
|
||
Guide
|
||
TLDP documents that are too long to be a HOWTO are usually
|
||
stored as guides. These are more like entire books that treat
|
||
a particular subject in-dept.
|
||
|
||
HOWTO
|
||
Documents that discuss how to do something with a system or
|
||
application. Most documents hosted at TLDP are HOWTOs,
|
||
explaining how to install, configure or manage tens of
|
||
applications on a variety of systems. HOWTOs are typically
|
||
10-25 pages.
|
||
|
||
internal entity
|
||
An internal entity refers to part of the text and is often
|
||
used as a shortcut for frequently repeated text.
|
||
|
||
ispell
|
||
Spell check program.
|
||
|
||
Jade
|
||
An application which applies the rules defined in a DSSSL
|
||
style sheet to an SGML or XML document, transforming the
|
||
document into the desired output.
|
||
|
||
Markup, markup language (ML)
|
||
Code added to the content of a document, describing its
|
||
structure.
|
||
|
||
Metadata
|
||
Text in your document that is not important for understanding
|
||
the subject, but that should be there anyway, such as version
|
||
information, co-authors, credits to people etc.
|
||
|
||
nedit
|
||
Text editor oriented to programmers.
|
||
|
||
nsgmls, onsgmls
|
||
SGML document parser and validator program.
|
||
|
||
OpenOffice (OOo)
|
||
Open Source office suite, compatible with Microsoft Office.
|
||
|
||
parameter entity
|
||
An entity type often used in the DTD or a document's internal
|
||
subset. The entity's name starts with a percent sign (%) and
|
||
ends with a semicolon.
|
||
|
||
PSGML
|
||
Emacs major mode that customizes Emacs for editing SGML
|
||
documents.
|
||
|
||
Organization for the Advancement of Structured Information Standards
|
||
(OASIS)
|
||
OASIS is a non-profit, global consortium that drives the
|
||
development, convergence and adoption of e-business standards.
|
||
|
||
Outline
|
||
Draft of your document that conceptualizes the subject and
|
||
scope. Summary and To-Do list for the work to come.
|
||
|
||
Portable Document Format (PDF)
|
||
Standard document type supported on a wide range of operating
|
||
systems.
|
||
|
||
processing instruction
|
||
A processing instruction is a command passed to the document
|
||
formatting tool. It starts with "<?". This document uses
|
||
processing instructions for naming files when it is rendered
|
||
into HTML: <?dbhtml filename="file.html">
|
||
|
||
PostScript (PS)
|
||
Document format designed for printable documents. PS is the
|
||
standard print format on UNIX(-alikes).
|
||
|
||
Reviewer, review process
|
||
TLDP doesn't accept just anything. Once you submit a document,
|
||
it will be checked for consistency, grammar, spelling and
|
||
style by a reviewer, a volunteer assigned by the review
|
||
coordinator.
|
||
|
||
SGML
|
||
Standard Generalized Markup Language. It is an international
|
||
standard (ISO8879) that specifies rules for the creation of
|
||
electronic documents in markup systems, regardless of the
|
||
platform used.
|
||
|
||
Subject and scope
|
||
Obviously, the subject is what your documentation is about.
|
||
The scope defines which areas of the subject you are going to
|
||
discuss, and how much detail will be involved.
|
||
|
||
tag
|
||
An SGML element bounded by the marks "<" and ">". Tags are
|
||
used to mark the semantic or logical structure of a document.
|
||
A sample is the tag <title> to mark the beginning of a title.
|
||
|
||
TeX
|
||
Popular UNIX text formatting and typesetting tool.
|
||
|
||
Transformation
|
||
The process of converting a document from its original DocBook
|
||
XML form to another format, such as PDF, HTML or PostScript.
|
||
|
||
Validation
|
||
The process of checking your XML code to ensure it complies
|
||
with the XML DTD you declared at the top of your document.
|
||
|
||
vi Improved (vIm)
|
||
Popular text editor on UNIX and alike systems.
|
||
|
||
WordPerfect (WP)
|
||
Popular word processor, runs on many systems.
|
||
|
||
XML
|
||
eXtensible Markup Language. A sub-product of SGML created
|
||
specifically for Internet use.
|
||
|
||
xmllint
|
||
Command line XML parser and validator.
|
||
|
||
XMLmind XML Editor (XXE)
|
||
Free but not Open XML editor.
|
||
|
||
xmlto
|
||
Command line XML transformation program.
|
||
|
||
XSL
|
||
XML Style Language. XSL is to a XML document what a DSSSL
|
||
style is for a SGML document. The XSL is written in XML.
|
||
|
||
Extensible Stylesheet Transformation (XSLT)
|
||
Framework for managing documents, consisting of the XSLT
|
||
transformation language, the XPath expression language and XSL
|
||
formatting objects.
|
||
________________________________________________________________
|
||
|
||
Appendix F. GNU Free Documentation License
|
||
|
||
F.1. 0. PREAMBLE
|
||
|
||
The purpose of this License is to make a manual, textbook, or other
|
||
written document "free" in the sense of freedom: to assure everyone
|
||
the effective freedom to copy and redistribute it, with or without
|
||
modifying it, either commercially or noncommercially. Secondarily,
|
||
this License preserves for the author and publisher a way to get
|
||
credit for their work, while not being considered responsible for
|
||
modifications made by others.
|
||
|
||
This License is a kind of "copyleft", which means that derivative
|
||
works of the document must themselves be free in the same sense. It
|
||
complements the GNU General Public License, which is a copyleft
|
||
license designed for free software.
|
||
|
||
We have designed this License in order to use it for manuals for free
|
||
software, because free software needs free documentation: a free
|
||
program should come with manuals providing the same freedoms that the
|
||
software does. But this License is not limited to software manuals;
|
||
it can be used for any textual work, regardless of subject matter or
|
||
whether it is published as a printed book. We recommend this License
|
||
principally for works whose purpose is instruction or reference.
|
||
________________________________________________________________
|
||
|
||
F.2. 1. APPLICABILITY AND DEFINITIONS
|
||
|
||
This License applies to any manual or other work that contains a
|
||
notice placed by the copyright holder saying it can be distributed
|
||
under the terms of this License. The "Document", below, refers to any
|
||
such manual or work. Any member of the public is a licensee, and is
|
||
addressed as "you".
|
||
|
||
A "Modified Version" of the Document means any work containing the
|
||
Document or a portion of it, either copied verbatim, or with
|
||
modifications and/or translated into another language.
|
||
|
||
A "Secondary Section" is a named appendix or a front-matter section
|
||
of the Document that deals exclusively with the relationship of the
|
||
publishers or authors of the Document to the Document's overall
|
||
subject (or to related matters) and contains nothing that could fall
|
||
directly within that overall subject. (For example, if the Document
|
||
is in part a textbook of mathematics, a Secondary Section may not
|
||
explain any mathematics.) The relationship could be a matter of
|
||
historical connection with the subject or with related matters, or of
|
||
legal, commercial, philosophical, ethical or political position
|
||
regarding them.
|
||
|
||
The "Invariant Sections" are certain Secondary Sections whose titles
|
||
are designated, as being those of Invariant Sections, in the notice
|
||
that says that the Document is released under this License.
|
||
|
||
The "Cover Texts" are certain short passages of text that are listed,
|
||
as Front-Cover Texts or Back-Cover Texts, in the notice that says
|
||
that the Document is released under this License.
|
||
|
||
A "Transparent" copy of the Document means a machine-readable copy,
|
||
represented in a format whose specification is available to the
|
||
general public, whose contents can be viewed and edited directly and
|
||
straightforwardly with generic text editors or (for images composed
|
||
of pixels) generic paint programs or (for drawings) some widely
|
||
available drawing editor, and that is suitable for input to text
|
||
formatters or for automatic translation to a variety of formats
|
||
suitable for input to text formatters. A copy made in an otherwise
|
||
Transparent file format whose markup has been designed to thwart or
|
||
discourage subsequent modification by readers is not Transparent. A
|
||
copy that is not "Transparent" is called "Opaque".
|
||
|
||
Examples of suitable formats for Transparent copies include plain
|
||
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
||
or XML using a publicly available DTD, and standard-conforming simple
|
||
HTML designed for human modification. Opaque formats include
|
||
PostScript, PDF, proprietary formats that can be read and edited only
|
||
by proprietary word processors, SGML or XML for which the DTD and/or
|
||
processing tools are not generally available, and the
|
||
machine-generated HTML produced by some word processors for output
|
||
purposes only.
|
||
|
||
The "Title Page" means, for a printed book, the title page itself,
|
||
plus such following pages as are needed to hold, legibly, the
|
||
material this License requires to appear in the title page. For works
|
||
in formats which do not have any title page as such, "Title Page"
|
||
means the text near the most prominent appearance of the work's
|
||
title, preceding the beginning of the body of the text.
|
||
________________________________________________________________
|
||
|
||
F.3. 2. VERBATIM COPYING
|
||
|
||
You may copy and distribute the Document in any medium, either
|
||
commercially or noncommercially, provided that this License, the
|
||
copyright notices, and the license notice saying this License applies
|
||
to the Document are reproduced in all copies, and that you add no
|
||
other conditions whatsoever to those of this License. You may not use
|
||
technical measures to obstruct or control the reading or further
|
||
copying of the copies you make or distribute. However, you may accept
|
||
compensation in exchange for copies. If you distribute a large enough
|
||
number of copies you must also follow the conditions in section 3.
|
||
|
||
You may also lend copies, under the same conditions stated above, and
|
||
you may publicly display copies.
|
||
________________________________________________________________
|
||
|
||
F.4. 3. COPYING IN QUANTITY
|
||
|
||
If you publish printed copies of the Document numbering more than
|
||
100, and the Document's license notice requires Cover Texts, you must
|
||
enclose the copies in covers that carry, clearly and legibly, all
|
||
these Cover Texts: Front-Cover Texts on the front cover, and
|
||
Back-Cover Texts on the back cover. Both covers must also clearly and
|
||
legibly identify you as the publisher of these copies. The front
|
||
cover must present the full title with all words of the title equally
|
||
prominent and visible. You may add other material on the covers in
|
||
addition. Copying with changes limited to the covers, as long as they
|
||
preserve the title of the Document and satisfy these conditions, can
|
||
be treated as verbatim copying in other respects.
|
||
|
||
If the required texts for either cover are too voluminous to fit
|
||
legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto adjacent
|
||
pages.
|
||
|
||
If you publish or distribute Opaque copies of the Document numbering
|
||
more than 100, you must either include a machine-readable Transparent
|
||
copy along with each Opaque copy, or state in or with each Opaque
|
||
copy a publicly-accessible computer-network location containing a
|
||
complete Transparent copy of the Document, free of added material,
|
||
which the general network-using public has access to download
|
||
anonymously at no charge using public-standard network protocols. If
|
||
you use the latter option, you must take reasonably prudent steps,
|
||
when you begin distribution of Opaque copies in quantity, to ensure
|
||
that this Transparent copy will remain thus accessible at the stated
|
||
location until at least one year after the last time you distribute
|
||
an Opaque copy (directly or through your agents or retailers) of that
|
||
edition to the public.
|
||
|
||
It is requested, but not required, that you contact the authors of
|
||
the Document well before redistributing any large number of copies,
|
||
to give them a chance to provide you with an updated version of the
|
||
Document.
|
||
________________________________________________________________
|
||
|
||
F.5. 4. MODIFICATIONS
|
||
|
||
You may copy and distribute a Modified Version of the Document under
|
||
the conditions of sections 2 and 3 above, provided that you release
|
||
the Modified Version under precisely this License, with the Modified
|
||
Version filling the role of the Document, thus licensing distribution
|
||
and modification of the Modified Version to whoever possesses a copy
|
||
of it. In addition, you must do these things in the Modified Version:
|
||
|
||
* A. Use in the Title Page (and on the covers, if any) a title
|
||
distinct from that of the Document, and from those of previous
|
||
versions (which should, if there were any, be listed in the
|
||
History section of the Document). You may use the same title as a
|
||
previous version if the original publisher of that version gives
|
||
permission.
|
||
* B. List on the Title Page, as authors, one or more persons or
|
||
entities responsible for authorship of the modifications in the
|
||
Modified Version, together with at least five of the principal
|
||
authors of the Document (all of its principal authors, if it has
|
||
less than five).
|
||
* C. State on the Title Page the name of the publisher of the
|
||
Modified Version, as the publisher.
|
||
* D. Preserve all the copyright notices of the Document.
|
||
* E. Add an appropriate copyright notice for your modifications
|
||
adjacent to the other copyright notices.
|
||
* F. Include, immediately after the copyright notices, a license
|
||
notice giving the public permission to use the Modified Version
|
||
under the terms of this License, in the form shown in the
|
||
Addendum below.
|
||
* G. Preserve in that license notice the full lists of Invariant
|
||
Sections and required Cover Texts given in the Document's license
|
||
notice.
|
||
* H. Include an unaltered copy of this License.
|
||
* I. Preserve the section entitled "History", and its title, and
|
||
add to it an item stating at least the title, year, new authors,
|
||
and publisher of the Modified Version as given on the Title Page.
|
||
If there is no section entitled "History" in the Document, create
|
||
one stating the title, year, authors, and publisher of the
|
||
Document as given on its Title Page, then add an item describing
|
||
the Modified Version as stated in the previous sentence.
|
||
* J. Preserve the network location, if any, given in the Document
|
||
for public access to a Transparent copy of the Document, and
|
||
likewise the network locations given in the Document for previous
|
||
versions it was based on. These may be placed in the "History"
|
||
section. You may omit a network location for a work that was
|
||
published at least four years before the Document itself, or if
|
||
the original publisher of the version it refers to gives
|
||
permission.
|
||
* K. In any section entitled "Acknowledgements" or "Dedications",
|
||
preserve the section's title, and preserve in the section all the
|
||
substance and tone of each of the contributor acknowledgements
|
||
and/or dedications given therein.
|
||
* L. Preserve all the Invariant Sections of the Document, unaltered
|
||
in their text and in their titles. Section numbers or the
|
||
equivalent are not considered part of the section titles.
|
||
* M. Delete any section entitled "Endorsements". Such a section may
|
||
not be included in the Modified Version.
|
||
* N. Do not retitle any existing section as "Endorsements" or to
|
||
conflict in title with any Invariant Section.
|
||
|
||
If the Modified Version includes new front-matter sections or
|
||
appendices that qualify as Secondary Sections and contain no material
|
||
copied from the Document, you may at your option designate some or
|
||
all of these sections as invariant. To do this, add their titles to
|
||
the list of Invariant Sections in the Modified Version's license
|
||
notice. These titles must be distinct from any other section titles.
|
||
|
||
You may add a section entitled "Endorsements", provided it contains
|
||
nothing but endorsements of your Modified Version by various
|
||
parties--for example, statements of peer review or that the text has
|
||
been approved by an organization as the authoritative definition of a
|
||
standard.
|
||
|
||
You may add a passage of up to five words as a Front-Cover Text, and
|
||
a passage of up to 25 words as a Back-Cover Text, to the end of the
|
||
list of Cover Texts in the Modified Version. Only one passage of
|
||
Front-Cover Text and one of Back-Cover Text may be added by (or
|
||
through arrangements made by) any one entity. If the Document already
|
||
includes a cover text for the same cover, previously added by you or
|
||
by arrangement made by the same entity you are acting on behalf of,
|
||
you may not add another; but you may replace the old one, on explicit
|
||
permission from the previous publisher that added the old one.
|
||
|
||
The author(s) and publisher(s) of the Document do not by this License
|
||
give permission to use their names for publicity for or to assert or
|
||
imply endorsement of any Modified Version .
|
||
________________________________________________________________
|
||
|
||
F.6. 5. COMBINING DOCUMENTS
|
||
|
||
You may combine the Document with other documents released under this
|
||
License, under the terms defined in section 4 above for modified
|
||
versions, provided that you include in the combination all of the
|
||
Invariant Sections of all of the original documents, unmodified, and
|
||
list them all as Invariant Sections of your combined work in its
|
||
license notice.
|
||
|
||
The combined work need only contain one copy of this License, and
|
||
multiple identical Invariant Sections may be replaced with a single
|
||
copy. If there are multiple Invariant Sections with the same name but
|
||
different contents, make the title of each such section unique by
|
||
adding at the end of it, in parentheses, the name of the original
|
||
author or publisher of that section if known, or else a unique
|
||
number. Make the same adjustment to the section titles in the list of
|
||
Invariant Sections in the license notice of the combined work.
|
||
|
||
In the combination, you must combine any sections entitled "History"
|
||
in the various original documents, forming one section entitled
|
||
"History"; likewise combine any sections entitled "Acknowledgements",
|
||
and any sections entitled "Dedications". You must delete all sections
|
||
entitled "Endorsements."
|
||
________________________________________________________________
|
||
|
||
F.7. 6. COLLECTIONS OF DOCUMENTS
|
||
|
||
You may make a collection consisting of the Document and other
|
||
documents released under this License, and replace the individual
|
||
copies of this License in the various documents with a single copy
|
||
that is included in the collection, provided that you follow the
|
||
rules of this License for verbatim copying of each of the documents
|
||
in all other respects.
|
||
|
||
You may extract a single document from such a collection, and
|
||
dispbibute it individually under this License, provided you insert a
|
||
copy of this License into the extracted document, and follow this
|
||
License in all other respects regarding verbatim copying of that
|
||
document.
|
||
________________________________________________________________
|
||
|
||
F.8. 7. AGGREGATION WITH INDEPENDENT WORKS
|
||
|
||
A compilation of the Document or its derivatives with other separate
|
||
and independent documents or works, in or on a volume of a storage or
|
||
distribution medium, does not as a whole count as a Modified Version
|
||
of the Document, provided no compilation copyright is claimed for the
|
||
compilation. Such a compilation is called an "aggregate", and this
|
||
License does not apply to the other self-contained works thus
|
||
compiled with the Document , on account of their being thus compiled,
|
||
if they are not themselves derivative works of the Document. If the
|
||
Cover Text requirement of section 3 is applicable to these copies of
|
||
the Document, then if the Document is less than one quarter of the
|
||
entire aggregate, the Document's Cover Texts may be placed on covers
|
||
that surround only the Document within the aggregate. Otherwise they
|
||
must appear on covers around the whole aggregate.
|
||
________________________________________________________________
|
||
|
||
F.9. 8. TRANSLATION
|
||
|
||
Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section 4.
|
||
Replacing Invariant Sections with translations requires special
|
||
permission from their copyright holders, but you may include
|
||
translations of some or all Invariant Sections in addition to the
|
||
original versions of these Invariant Sections. You may include a
|
||
translation of this License provided that you also include the
|
||
original English version of this License. In case of a disagreement
|
||
between the translation and the original English version of this
|
||
License, the original English version will prevail.
|
||
________________________________________________________________
|
||
|
||
F.10. 9. TERMINATION
|
||
|
||
You may not copy, modify, sublicense, or distribute the Document
|
||
except as expressly provided for under this License. Any other
|
||
attempt to copy, modify, sublicense or distribute the Document is
|
||
void, and will automatically terminate your rights under this
|
||
License. However, parties who have received copies, or rights, from
|
||
you under this License will not have their licenses terminated so
|
||
long as such parties remain in full compliance.
|
||
________________________________________________________________
|
||
|
||
F.11. 10. FUTURE REVISIONS OF THIS LICENSE
|
||
|
||
The Free Software Foundation may publish new, revised versions of the
|
||
GNU Free Documentation License from time to time. Such new versions
|
||
will be similar in spirit to the present version, but may differ in
|
||
detail to address new problems or concerns. See
|
||
[http://www.gnu.org/copyleft] http://www.gnu.org/copyleft/.
|
||
|
||
Each version of the License is given a distinguishing version number.
|
||
If the Document specifies that a particular numbered version of this
|
||
License "or any later version" applies to it, you have the option of
|
||
following the terms and conditions either of that specified version
|
||
or of any later version that has been published (not as a draft) by
|
||
the Free Software Foundation. If the Document does not specify a
|
||
version number of this License, you may choose any version ever
|
||
published (not as a draft) by the Free Software Foundation.
|
||
________________________________________________________________
|
||
|
||
F.12. Addendum
|
||
|
||
To use this License in a document you have written, include a copy of
|
||
the License in the document and put the following copyright and
|
||
license notices just after the title page:
|
||
|
||
Copyright <20> YEAR YOUR NAME.
|
||
|
||
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 the Invariant Sections being LIST THEIR TITLES,
|
||
with the Front-Cover Texts being LIST, and with the Back-Cover
|
||
Texts being LIST. A copy of the license is included in the section
|
||
entitled "GNU Free Documentation License".
|
||
|
||
If you have no Invariant Sections, write "with no Invariant Sections"
|
||
instead of saying which ones are invariant. If you have no
|
||
Front-Cover Texts, write "no Front-Cover Texts" instead of
|
||
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
|
||
|
||
If your document contains nontrivial examples of program code, we
|
||
recommend releasing these examples in parallel under your choice of
|
||
free software license, such as the GNU General Public License, to
|
||
permit their use in free software.
|
||
|
||
Notes
|
||
|
||
[1]
|
||
|
||
Please, take a look at the
|
||
[http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide
|
||
/] source to see how to get similar results on your documents. You
|
||
should also remember that the way this appears to you depends on the
|
||
format in which you are reading this document: online appearance is
|
||
slightly different from the PostScript or PDF ones.
|
||
[2]
|
||
|
||
In truth, "XSL" is actually comprised of three components: the XSLT
|
||
transformation language, the XPath expression language (used by
|
||
XSLT), and XSL Formatting Objects (FO) that are used for describing a
|
||
page. The style sheets are actually written in XSLT and generate
|
||
either HTML or (for print output) FO. The FO file is then run through
|
||
a FO processor to create the actual print (PDF or PostScript) output.
|
||
See the W3C web site for more information.
|
||
[3]
|
||
|
||
In XSL terminology, the process of generating multiple files is
|
||
referred to as "chunking".
|