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

Recommended changes from Martin Brown.

This commit is contained in:
emmajane 2004-01-05 08:29:02 +00:00
parent 0eebb37b13
commit 669dc4ebd7
19 changed files with 239 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -40,6 +40,7 @@
<!-- Chapter Five: Publish and Distribute -->
<!ENTITY ag-distribute SYSTEM "ag-distribute.xml">
<!ENTITY ag-submit SYSTEM "ag-submit.xml">
<!ENTITY disclaimer SYSTEM "disclaimer.xml">
<!-- Chapter Six: Maintain -->
<!ENTITY ag-maintain SYSTEM "ag-maintain.xml">
@ -151,11 +152,22 @@ what's on the LDP web site as I'm currently *gasp* offline. -->
</othercredit>
<abstract>
<para>List the tools, procedures and hints to get LDP authors
up to speed and writing. </para>
<para>
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.
</para>
</abstract>
<revhistory>
<revision>
<revnumber>4.0.11</revnumber>
<date>2004-01-04</date>
<authorinitials>ejh</authorinitials>
<revremark>Incorporated notes and corrections from Martin A. Brown.</revremark>
</revision>
<revision>
<revnumber>4.0.10</revnumber>
<date>2004-01-01</date>

11
LDP/guide/docbook/LDP-Author-Guide/accepted-markup.xml
View File

@ -24,8 +24,11 @@
</listitem>
</orderedlist>
<note><title>Initial input format versus published format</title>
<para>You may submit the first version of your document to the LDP in any
format. If it is not one of the accepted formats, an LDP volunteer will
add DocBook XML markup to your document before storing it on the LDP site.</para>
<note><title>New Documents</title>
<para>
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.
</para>
</note>

22
LDP/guide/docbook/LDP-Author-Guide/ag-about.xml
View File

@ -10,10 +10,10 @@
to work. If even one LDP author is helped by this, then I did my
job.</para>
<para>
Version 4 of this document was released in late 2003 by Emma Jane
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 six months.
approximately eight months.
</para>
<para>
The newest version of this document can be found at the LDP
@ -21,12 +21,18 @@
<ulink url="http://www.tldp.org/">http://www.tldp.org</ulink>.
The original DocBook, HTML, and other formats can be found there.
</para>
<para>There are many ways to contribute to the Linux movement
without actually writing code. One of the most important is
writing documentation, allowing each person to share their
knowledge with thousands of others around the world. This Guide
is designed to help you get familiar with how the LDP works, and
what tools you'll need to write your own HOWTO.</para>
<para>
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.
</para>
</section>
<!-- Because I haven't decided where to put it, the

25
LDP/guide/docbook/LDP-Author-Guide/ag-distribute.xml
View File

@ -132,12 +132,6 @@
licensing, please check <xref linkend="ref-licenses" />.
</para>
<note><title>Example</title>
<para>You'll note that the licensing for this guide
requires notification to the author of any derivative works or
translations.</para>
</note>
<tip><title>Share and enjoy</title><para>
If your HOWTO includes bits of source code that you want others to use,
you may choose to release the source code under GPL.</para></tip>
@ -154,24 +148,7 @@
to use the following:</para>
<blockquote>
<para>
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 damange claimed to be caused by doing so.
</para>
<para>
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.
</para>
&disclaimer;
</blockquote>
</section>

13
LDP/guide/docbook/LDP-Author-Guide/ag-overview.xml
View File

@ -125,7 +125,7 @@
discussion group of the LDP.</para></listitem>
<listitem><para>Another is the <email>docbook@en.tldp.org</email> list, which is for
markup or other questions about the DocBook format itself. If you run into
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.</para></listitem>
</itemizedlist>
@ -140,11 +140,12 @@
<email>docbook-unsubscribe@en.tldp.org</email>.</para>
<para>
There is also a mailing list run by <ulink url="http://www.oasis-open.org/">OASIS</ulink> that can
answer DocBook questions. Please see <ulink url="http://docbook.org/mailinglist/index.html">http://docbook.org/mailinglist/index.html</ulink>
for more information about the mailing lists. We prefer our own list,
but only because the LDP list focuses more on tag usage
than other questions such as formatting.
If you are interested in DocBook beyond the simple markup of your
LDP document, you may want to consider joining one of the <ulink
url="http://www.oasis-open.org/">OASIS</ulink> DocBook mailing
lists. Please see <ulink
url="http://docbook.org/mailinglist/index.html">http://docbook.org/mailinglist/index.html</ulink>
for more information.
</para>
</section>
</chapter>

47
LDP/guide/docbook/LDP-Author-Guide/ag-proposal.xml
View File

@ -19,13 +19,9 @@
and it took many posts to resolve the problem -- that might be an incentive to write documentation.
</para>
<para>
Regardless of how you picked your subject, it is
important that you feel there is a need for the
documentation. It also helps if you can convince a few people on the
LDP discuss
mailing list that your proposed documentation will be a valuable
contribution to the LDP.
If someone has requested documentation, or you worked
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.
@ -68,11 +64,12 @@
</formalpara>
<para>
If your subject matter is very small, it might be better
included as part of another HOWTO. This makes it easier
for readers to find the HOWTO they need. Search the LDP repository
for HOWTOs on related topics, and see if you can place
your information in an existing HOWTO.
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.
</para>
</listitem>
@ -81,8 +78,13 @@
<title>Undocumented.</title>
<para>
Before documenting a particular subject, always check other documents at the LDP
and see if the topic is already discussed. If it is, avoid confusion by refering to an existing HOWTO instead of rewriting documentation.
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.
</para>
</formalpara>
@ -91,7 +93,9 @@
contact the author and offer to help. See also <xref linkend="unmaintained" /> for taking over old or unmaintained documents.</para>
<para>
Most authors appreciate any help offered. Additionally, sending comments and remarks to the author is usually regarded both as a reassurance and an reward: to the author, feedback is the ultimate proof that writing the documentation was not a pointless effort.</para>
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.</para>
</listitem>
<listitem>
@ -196,8 +200,15 @@
</listitem>
</itemizedlist>
<note><title>Integrated mini-HOWTOs</title><para>
The mini-HOWTOs have been rolled into the HOWTOs.
<note><title>mini-HOWTOs and HOWTOs</title><para>
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.
</para></note>
</section> <!-- end of types of docs -->
@ -310,8 +321,6 @@ contact us (preferably on the discuss mailing list) and let us know.</para></not
</para>
<tip><title>Writing a HOWTO made easy</title>
<para>Because most submissions are in the form of a HOWTO,
TLDP provides some tools for easing your life.</para>
<para>
For help writing your HOWTO outline, and getting a head start on
the markup of your document, check out <ulink

22
LDP/guide/docbook/LDP-Author-Guide/ag-writing.xml
View File

@ -20,10 +20,10 @@
It has taken quite a bit of work to get to the point where you can
actually start writing, hasn't it? Well, the hard work begins to pay
off for you now. At this stage, you can begin to really use your
imagination and creativity to communicate this heap of dry,
boring information in your own unique way. Don't be too clever
though! Your readers are already struggling with new concepts, so don't
make them struggle to understand your language.
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.
</para>
<para>
@ -89,10 +89,14 @@
conventions for LDP documents and it is as close as it
gets to an official LDP Style Guide.
</para>
<tip><title>Your personalized editor notes</title><para>It helps to make a list of terms that you doubted about and looked
up. You can refer to your personal list of conventions while writing the text.
Lateron, you might also send this list as an extra aid to the person reviewing
your text.</para></tip>
<tip><title>A personal glossary</title>
<para>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.
</para></tip>
<para>
You can save yourself a lot of time in the editing phase if you
decide how you will write your document ahead of time. If you are
@ -112,7 +116,7 @@ your text.</para></tip>
</section>
<section id="writing-resources">
<title>Online Writing Resources</title>
<title>On-line Writing Resources</title>
<para>
In the <xref linkend="ref-techwriting" />

59
LDP/guide/docbook/LDP-Author-Guide/cvs.xml
View File

@ -14,20 +14,20 @@
<section id="getaccount">
<title> Getting a CVS account </title>
<para> First you'll need to get an account at the LDP's CVS
Repository. This is pretty much the root directory that is used
by CVS, with various projects (HOWTOs, guides, etc.)
created as subdirectories of it. </para>
<para>Please fill the form:
<ulink url="http://tldp.org/cvs/">
http://tldp.org/cvs/</ulink>
</para>
<para>During filling the form we want you to inform us about
your plans. Among other things, LDP likes to know which HOWTO or other document you maintain.
Repository. 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).
</para>
<para>
Please complete the form at <ulink url="http://tldp.org/cvs/" />
Include information about which documents you maintain.
Remember your password, it will <emphasis>not</emphasis>
be sent in the confirmation email.
</para>
<para>Your unique
CVSROOT directory will be created and you'll get an e-mail with
a response. Remember your password, it will <emphasis>not</emphasis>
be sent in the email. When you get your response, log into your CVSROOT
CVSROOT directory will be created and you will get an e-mail
confirming your account is ready. When you get your response, log into your CVSROOT
and make sure everything is set up properly. Use either of these
options:</para>
@ -88,20 +88,10 @@
<variablelist>
<title>CVS Commands: a brief reminder</title>
<varlistentry>
<term>$Id$</term>
<listitem><para>
Automatically insert the date and version directly into the
document when a document is committed. Example: $Id: cvs.xml,v 1.9
2002/04/21 09:44:26 serek Exp $
</para></listitem>
</varlistentry>
<varlistentry>
<term>commit</term>
<listitem><para>
This option will upload your changes to the CVS server. If you
This CVS command will upload your changes to the CVS server. If you
want to bypass the editor screen you can use </para>
<cmdsynopsis><command>
cvs <option>commit</option> <option>-m "comment"</option>
@ -137,6 +127,27 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>remove</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$Id$</term>
<listitem><para>
While this is not a CVS <quote>command</quote> 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:
<computeroutput>$Id: cvs.xml,v 1.9 2002/04/21 09:44:26 serek Exp
$</computeroutput>
</para></listitem>
</varlistentry>
</variablelist>
<para>
@ -157,7 +168,7 @@
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 and older
to do is go back in time and resurrect an older
version of your file.
</para>
<para>

19
LDP/guide/docbook/LDP-Author-Guide/disclaimer.xml Normal file
View File

@ -0,0 +1,19 @@
<!-- A Standard Disclaimer -->
<para>
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 damange claimed to be caused by
doing so.
</para>
<para>
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.
</para>

44
LDP/guide/docbook/LDP-Author-Guide/glossary.xml
View File

@ -45,7 +45,8 @@
<glossentry>
<glossterm>Catalog</glossterm>
<glossdef>
<para>Helper file for the display and transformation tools.
<para>Helper file for the display and transformation tools, which
maps public identifiers and URLs to the local file system.
</para>
</glossdef>
</glossentry>
@ -54,7 +55,7 @@
<glossterm>Concurrent Versions System
(<acronym>CVS</acronym>)</glossterm>
<glossdef>
<para>Document management system used by TLDP.
<para>A common document management system used by the LDP.
</para>
</glossdef>
</glossentry>
@ -62,7 +63,8 @@
<glossentry>
<glossterm>DocBook</glossterm>
<glossdef>
<para>A subset of SGML, designed as a document format that allows easy management of documentation.
<para>An SGML (and XML) application, describing a document format
that allows easy management of documentation.
</para>
</glossdef>
</glossentry>
@ -99,12 +101,18 @@
<glossentry>
<glossterm>element</glossterm>
<glossdef>
<para>The elements define the hierarchical structure of a document. The
majority of elements have opening and closing pointers. Within these
pointers, pieces of text or even the whole document being written can
be found. There are empty elements which contains only opening
pointers without any content.</para>
</glossdef>
<para>
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 <sgmltag
class="starttag">para</sgmltag>This is the paragraph.<sgmltag
class="endtag">para</sgmltag>. Some elements are <quote>empty</quote> 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 <sgmltag
class="emptytag">ulink url="http://google.com</sgmltag>.
</para>
</glossdef>
</glossentry>
<glossentry>
@ -121,7 +129,7 @@
<para>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 of a <acronym>DTD</acronym>.
of statements in a <acronym>DTD</acronym>.
Entity parameters can be generic, external, internal or
<acronym>SGML</acronym> data. An entity is similar to a variable
in a programming language, or a macro.
@ -236,7 +244,9 @@
<glossentry>
<glossterm>Jade</glossterm>
<glossdef>
<para>Applies a DSSSL stylesheet to an SGML or XML document.
<para>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.
</para>
</glossdef>
</glossentry>
@ -286,7 +296,8 @@
<glossentry>
<glossterm>parameter entity</glossterm>
<glossdef>
<para>An entity often used in the <acronym>DTD</acronym>. The entity's
<para>An entity type often used in the <acronym>DTD</acronym> or a
document's internal subset. The entity's
name starts with a percent sign (&#37;) and ends with a
semicolon.</para>
</glossdef>
@ -350,7 +361,7 @@
<glossentry>
<glossterm>Reviewer, review process</glossterm>
<glossdef>
<para>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 cooredinator.
<para>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.
</para>
</glossdef>
</glossentry>
@ -362,7 +373,7 @@
Language</foreignphrase>.
It is an international standard (<acronym>ISO</acronym>8879) that
specifies rules for the creation of electronic documents in markup
systems, regardless the work platform used.</para>
systems, regardless of the platform used.</para>
</glossdef>
</glossentry>
@ -405,7 +416,8 @@
<glossentry>
<glossterm>Validation</glossterm>
<glossdef>
<para>The process of checking that your XML code complies with the XML standards.
<para>The process of checking your XML code to ensure it complies
with the XML DTD you declared at the top of your document.
</para>
</glossdef>
</glossentry>
@ -439,7 +451,7 @@
<glossentry>
<glossterm>xmllint</glossterm>
<glossdef>
<para>Command line XML parser.
<para>Command line XML parser and validator.
</para>
</glossdef>
</glossentry>

4
LDP/guide/docbook/LDP-Author-Guide/references.xml
View File

@ -161,10 +161,8 @@ url="http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html" /></bibliosou
<biblioentry>
<title>Howtos-with-LinuxDoc-mini-HOWTO</title>
<bibliosource><ulink
url="http://www.faqs.org/docs/Linux-mini/Howtos-with-LinuxDoc.html" /></bibliosource>
url="http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html" /></bibliosource>
<author><firstname>David</firstname><surname>Lawyer</surname></author>
<copyright><year>2001</year>
<holder>David Lawyer</holder></copyright>
</biblioentry>
<biblioentry>

11
LDP/guide/docbook/LDP-Author-Guide/templates.xml
View File

@ -65,12 +65,21 @@
<listitem>
<formalpara>
<title>A FAQ <ulink url="t-faq.xml" /></title>
<title>FAQ <ulink url="t-faq.xml" /></title>
<para>
A standard article for writing a FAQ (Frequently Asked Questions) list.
</para>
</formalpara>
</listitem>
<listitem>
<formalpara><title>Disclaimer <ulink url="disclaimer.xml" /></title>
<para>
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.
</para></formalpara>
</listitem>
</orderedlist>
</section>

7
LDP/guide/docbook/LDP-Author-Guide/tldp.xml
View File

@ -38,9 +38,10 @@
</blockquote>
<para>
The human readable version goes more like this: The LDP consists
of a large group of volunteers that are working on documentation
for the Linux OS. The most visible documentation are the HOWTOs
located at <ulink url="http://www.tldp.org/" />.
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 <ulink url="http://www.tldp.org/" />.
This Guide focuses primarily on how to write your own HOWTOs for
submission to the LDP.
</para>

15
LDP/guide/docbook/LDP-Author-Guide/tools-text-editors.xml
View File

@ -21,12 +21,6 @@
some tweaking, handle DocBook files.
</para>
<!--
The Emacs section is long, and not really the forte of
this vim user. It's been hacked into a more reasonable
length, but definitely needs some TLC from a Real Emacs
User.
-->
&configure-emacs;
<section id="tools-vim">
@ -91,8 +85,15 @@
can add your document type in &lt;-- comments --&gt; to
the top of the file to get the correct syntax
highlighting (you will need to restart the program to see
the change in highlighting).
the change in highlighting). The top line of this file
(<filename>tools-text-editors.xml</filename>) looks like this:
</para>
<screen>
<![CDATA[
<!-- <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'> -->
]]>
</screen>
</section> <!-- vim-new-file -->
<section id="vim-spellcheck">

11
LDP/guide/docbook/LDP-Author-Guide/tools-transform.xml
View File

@ -352,7 +352,7 @@ used:</para>
<para>
There are alternatives to DSSSL and Jade/OpenJade.</para>
<para>When working with DocBook XML, the LDP uses a series of
<para>When working with DocBook XML, the LDP offers a series of
XSL<footnote><para>In truth, "XSL" is actually comprised of three
components: the <emphasis>XSLT</emphasis> transformation language,
the <emphasis>XPath</emphasis> expression language (used by XSLT),
@ -519,8 +519,10 @@ sheets create
</para>
</example>
<warning><title>Warning</title><para>
Do not edit the DTD files.
<warning><title>Do not edit DTD files</title><para>
The DocBook standard is described in these
files. If you change these files, you are no longer working
with DocBook.
</para></warning>
</section>
@ -616,7 +618,8 @@ sheets create
Although DocBook has markups for the composition of
them, indexes are not generated automatically. The
<command>collateindex.pl</command> command allows indexes
to be generated automatically.
to be generated from the source DocBook for inclusion into the
finished/transformed document.
</para>
<orderedlist>

10
LDP/guide/docbook/LDP-Author-Guide/tools-validate.xml
View File

@ -141,10 +141,12 @@ save these changes.</para>
<para>
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 line will include a public
identifier, such as <quote>-//OASIS//DTD DocBook
V4.2//EN</quote>. This public identifier has a number of sections all
separated by <quote>//</quote>. It contains the following information: ISO (none),
about to be processed. At a minimum this declaration will include a public
identifier, such as <literal>-//OASIS//DTD DocBook
V4.2//EN</literal>. This public identifier has a number of sections all
separated by <literal>//</literal>. It contains the following
information: ISO standard if any (<literal>-</literal> -- 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.
</para>

43
LDP/guide/docbook/LDP-Author-Guide/using-docbook.xml
View File

@ -467,7 +467,7 @@ structured data, by using querying languages for XML (<application>XPath</applic
</para>
<para>
A well-defined, valid and well-structured documents make it easier for
A well-defined, valid and well-structured document makes it easier for
one to write <application>XPath</application>/<application>Query</application> to retreive <quote>specific</quote> data from a document.
For example you can use <application>XPath</application> to retrieve information in the
<sgmltag class="starttag">sect3</sgmltag> block with certain attributes.
@ -514,10 +514,12 @@ structured data, by using querying languages for XML (<application>XPath</applic
<example id="ex-screen">
<title>Command Prompt with <sgmltag>screen</sgmltag></title>
<para>
First make an <quote>entity</quote> which is a shortcut
for the longer prompt which is used.
&lt;!ENTITY prompt "&lt;prompt&gt;[user@machine
~/dir]$&lt;/prompt&gt;"&gt;
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.
<literal>&lt;!ENTITY prompt "&lt;prompt&gt;[user@machine
~/dir]$&lt;/prompt&gt;"&gt;</literal>
</para>
<para>
@ -527,8 +529,8 @@ structured data, by using querying languages for XML (<application>XPath</applic
<screen>
<sgmltag class="starttag">screen</sgmltag>
<sgmltag class="starttag">prompt</sgmltag>&amp;prompt; <sgmltag class="endtag">prompt</sgmltag><sgmltag class="starttag">userinput</sgmltag>cd /some/dir<sgmltag class="endtag">userinput</sgmltag>
<sgmltag class="starttag">prompt</sgmltag>&amp;prompt; <sgmltag class="endtag">prompt</sgmltag><sgmltag class="starttag">userinput</sgmltag>ls -l<sgmltag class="endtag">userinput</sgmltag> <sgmltag class="endtag">screen</sgmltag>
&amp;prompt; <sgmltag class="starttag">userinput</sgmltag>cd /some/dir<sgmltag class="endtag">userinput</sgmltag>
&amp;prompt; <sgmltag class="starttag">userinput</sgmltag>ls -l<sgmltag class="endtag">userinput</sgmltag> <sgmltag class="endtag">screen</sgmltag>
</screen>
<para>Displays as:</para>
@ -647,8 +649,9 @@ structured data, by using querying languages for XML (<application>XPath</applic
</indexterm>
<para>It is necessary to insert pictures for all media the
document will be published for.</para>
<para>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.</para>
<para>If you use the TeX format you'll need the images as
a PostScript file. For on-line publishing you can use any
@ -728,10 +731,10 @@ structured data, by using querying languages for XML (<application>XPath</applic
<sgmltag class="starttag">title</sgmltag>Title<sgmltag class="endtag">title</sgmltag>
<sgmltag class="starttag">mediaobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.eps" format="eps"</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.eps" format="EPS"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.jpg" format="jpg"</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.jpg" format="JPG"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">textobject</sgmltag>
<sgmltag class="starttag">phrase</sgmltag>Here there's an image of this example<sgmltag class="endtag">phrase</sgmltag>
@ -885,6 +888,12 @@ structured data, by using querying languages for XML (<application>XPath</applic
<example id="sample-metadata">
<title>Sample Meta Data</title>
<programlisting>
<![CDATA[<!--
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.
-->]]>
<sgmltag class="starttag">articleinfo</sgmltag>
&lt;!--
@ -917,11 +926,11 @@ structured data, by using querying languages for XML (<application>XPath</applic
<sgmltag class="endtag">revremark</sgmltag>first official release<sgmltag class="endtag">revremark</sgmltag>
<sgmltag class="endtag">revision</sgmltag>
<sgmltag class="endtag">revision</sgmltag>
<sgmltag class="endtag">revnumber</sgmltag>0.9<sgmltag class="endtag">revnumber</sgmltag>
<sgmltag class="endtag">date</sgmltag>YYYY-MM-DD<sgmltag class="endtag">date</sgmltag>
<sgmltag class="endtag">authorinitials</sgmltag>ABC<sgmltag class="endtag">authorinitials</sgmltag>
<sgmltag class="endtag">revremark</sgmltag>First draft<sgmltag class="endtag">revremark</sgmltag>
<sgmltag class="starttag">revision</sgmltag>
<sgmltag class="starttag">revnumber</sgmltag>0.9<sgmltag class="endtag">revnumber</sgmltag>
<sgmltag class="starttag">date</sgmltag>YYYY-MM-DD<sgmltag class="endtag">date</sgmltag>
<sgmltag class="starttag">authorinitials</sgmltag>ABC<sgmltag class="endtag">authorinitials</sgmltag>
<sgmltag class="starttag">revremark</sgmltag>First draft<sgmltag class="endtag">revremark</sgmltag>
<sgmltag class="endtag">revision</sgmltag>
<sgmltag class="endtag">revhistory</sgmltag>
@ -1185,7 +1194,7 @@ value "INCLUDE". &lt;/para&gt; ]]</sgmltag>
<para>
There is no <quote>easy</quote> way to add headers and
footers to your document. If you are using DocBook XSL and
doing your own document (DocBook to HTML/etc transformations) you
doing your own document transformations you
may customize the XSL template to suit your needs. For more
information read <ulink
url="http://www.sagehill.net/docbookxsl/HTMLHeaders.html" />.

4
LDP/guide/docbook/LDP-Author-Guide/validate-why.xml
View File

@ -25,8 +25,8 @@
<para>
If your document is not well formed or uses invalid markup, the
scripts will not be able to process it. As
a result, your document will not be distributed.
scripts will not be able to process it. As a result, your revised
document will not be distributed.
</para>
<note><title>The Docbook Section</title><para> There is more information about how to validate

25
LDP/guide/docbook/LDP-Author-Guide/x2docbook.xml
View File

@ -49,14 +49,6 @@
</screen>
</listitem>
<listitem>
<para>
Most XML-specific tags (like entity)
have to be in all capital letters (ENTITY).
</para>
</listitem>
<listitem>
<para>
All attributes in the start tag must be
@ -87,9 +79,10 @@
<listitem>
<para>
Processing instructions that get sent to the DSSSL
must have a question mark at the
end of the tag. The XML version of this tag
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:
</para>
<screen>
@ -122,16 +115,16 @@
<section id="differences">
<title>Changing DTDs</title>
<para>
The big changes between version changes in the DTD
involve changed elements (tags). Elements may be:
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 to from a lower version
deprecated tag when going from a lower version
of DocBook to a higher version.
</para>
<para>
The <citetitle>DocBook: The Definitive Guide</citetitle> does
<citetitle>DocBook: The Definitive Guide</citetitle> 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
@ -175,7 +168,7 @@
<listitem>
<formalpara>
<title><sgmltag>graphic</sgmltag></title>
<para>has being deprecated and will be removed as of DocBook 5.x.
<para>has been deprecated and will be removed as of DocBook 5.x.
To prepare for this, start using
<sgmltag>mediaobject</sgmltag>. There is more
information about <sgmltag>mediaobject</sgmltag>