mirror of https://github.com/tLDP/LDP
791 lines
30 KiB
XML
791 lines
30 KiB
XML
<?xml version='1.0' encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'
|
|
"/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd" [
|
|
|
|
<!--
|
|
A note to future authors and editors of this document:
|
|
Thank you a hundred times over for contributing!
|
|
-->
|
|
|
|
<!-- Chapter One: About this guide -->
|
|
<!ENTITY aboutthisguide SYSTEM "abouttheguide.xml">
|
|
<!ENTITY tldp SYSTEM "tldp.xml">
|
|
<!ENTITY thankyous SYSTEM "thankyous.xml">
|
|
<!ENTITY conventions SYSTEM "conventions.xml">
|
|
|
|
<!-- Chapter Two: Authoring TLDP Documents: An Introduction -->
|
|
<!ENTITY authoring-overview SYSTEM "authoring-overview.xml">
|
|
|
|
<!-- Chapter Three: Propose -->
|
|
<!ENTITY authoring-proposal SYSTEM "authoring-proposal.xml">
|
|
|
|
<!-- Chapter Four: Write -->
|
|
<!ENTITY authoring-writing SYSTEM "authoring-writing.xml">
|
|
<!ENTITY cvs SYSTEM "cvs.xml">
|
|
|
|
<!-- Appendix B. Editors, Validation and System Setup -->
|
|
<!ENTITY tools SYSTEM "tools.xml">
|
|
|
|
|
|
<!ENTITY using-docbook SYSTEM "using-docbook.xml">
|
|
<!ENTITY doc-index SYSTEM "index.xml">
|
|
<!ENTITY gfdl SYSTEM "fdl-appendix.xml">
|
|
|
|
<!-- Include macros -->
|
|
<!ENTITY conventions SYSTEM "conventions.xml">
|
|
<!ENTITY example-article SYSTEM "example-article.xml">
|
|
<!ENTITY example-book SYSTEM "example-book.xml">
|
|
<!ENTITY example-compile-sgml SYSTEM "compiles-sgml.xml">
|
|
<!ENTITY example-table SYSTEM "example-table.xml">
|
|
<!ENTITY dsl-example SYSTEM "dsl-example.xml">
|
|
<!ENTITY glossary SYSTEM "glossary.xml">
|
|
<!ENTITY xml SYSTEM "docbook-xml.xml">
|
|
<!ENTITY style-guide SYSTEM "style-guide.xml">
|
|
<!ENTITY using-ldp-dsssl SYSTEM "using-ldp-dsssl.xml">
|
|
<!ENTITY using-ldp-xsl SYSTEM "using-ldp-xsl.xml">
|
|
<!-- Text Macros -->
|
|
<!ENTITY conectivasa '<ulink url="http://www.conectiva.com">Conectiva S.A.</ulink>'>
|
|
<!ENTITY conectiva "Conectiva">
|
|
|
|
]>
|
|
|
|
|
|
<book id="index">
|
|
<bookinfo>
|
|
<title>LDP Author Guide</title>
|
|
<pubdate>2002-04-25</pubdate>
|
|
<author>
|
|
<firstname>Mark</firstname>
|
|
<othername>F.</othername>
|
|
<surname>Komarinski</surname>
|
|
<affiliation>
|
|
<address><email>mkomarinski@wayga.org</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>Jorge</firstname>
|
|
<surname>Godoy</surname>
|
|
<affiliation>
|
|
<orgname>&conectivasa;</orgname>
|
|
<orgdiv>Publishing Department</orgdiv>
|
|
<address><email>godoy@conectiva.com</email></address>
|
|
<address><email>godoy@metalab.unc.edu</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>David</firstname>
|
|
<othername>C.</othername>
|
|
<surname>Merrill</surname>
|
|
<affiliation>
|
|
<address><email>dcmerrill@mindspring.com</email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<abstract>
|
|
<para>List the tools, procedures, and hints to get LDP authors
|
|
up to speed and writing. </para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>4.0</revnumber>
|
|
<date>2003-08-13</date>
|
|
<authorinitials>ejh</authorinitials>
|
|
<revremark>Revised the structure of the document and shuffled
|
|
elements into place.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.15</revnumber>
|
|
<date>2002-12-16</date>
|
|
<authorinitials>gjf</authorinitials>
|
|
<revremark>Contribution by Jaime Irving Davila regarding ldp.dsl
|
|
usage. </revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.14</revnumber>
|
|
<date>2002-05-16</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Added information about LDP Reviewer HOWTO. New reviewers are asked to read this document.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.14</revnumber>
|
|
<date>2002-04-25</date>
|
|
<authorinitials>gf</authorinitials>
|
|
<revremark>Update meta-data information, resources; add articleinfo content</revremark>
|
|
</revision>
|
|
<!--
|
|
<revision>
|
|
<revnumber>3.13</revnumber>
|
|
<date>2002-04-21</date>
|
|
<authorinitials>sp</authorinitials>
|
|
<revremark>We are now tldp.org</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.12</revnumber>
|
|
<date>2002-03-11</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Bug fixes, learning PSGML, update e-mail address</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.11</revnumber>
|
|
<date>2002-01-26</date>
|
|
<authorinitials>sp</authorinitials>
|
|
<revremark>
|
|
Updated CVS information.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.10</revnumber>
|
|
<date>2001-12-15</date>
|
|
<authorinitials>dcm</authorinitials>
|
|
<revremark>
|
|
Updated contacting LDP information.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.9</revnumber>
|
|
<date>2001-11-27</date>
|
|
<authorinitials>sp</authorinitials>
|
|
<revremark>
|
|
Updated CVS information.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.8</revnumber>
|
|
<date>2001-09-25</date>
|
|
<authorinitials>dy</authorinitials>
|
|
<revremark>
|
|
XML/XSLT information.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.7</revnumber>
|
|
<date>2001-06-20</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>
|
|
Now under the GFDL.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.62</revnumber>
|
|
<date>2001-03-13</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>
|
|
Spelling and grammar changes from Dave Edwards (amoamasam@sympatico.ca).
|
|
Also performed some housecleaning from comments of discuss@en.tldp.org.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.6</revnumber>
|
|
<date>2001-01-10</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>
|
|
First revision in DocBook XML. Added section covering writing
|
|
in DB XML, since first rev is 4.1.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.51</revnumber>
|
|
<date>2001-01-05</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>sgedit (now tksgml) is not free, included link for pricing, more XML info</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.5</revnumber>
|
|
<date>Dec 4, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Changed mailing list pointers to new lists.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.4</revnumber>
|
|
<date>Dec 1, 2000</date>
|
|
<authorinitials>dcm</authorinitials>
|
|
<revremark>Added Crediting Translators and Converters</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.3</revnumber>
|
|
<date>Nov 11, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Added links to SGML GPL and FDL</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.1</revnumber>
|
|
<date>Oct 10, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Spelling changes, changed list of LDP policies to now
|
|
accept DocBook XML. More information about how to use *jade
|
|
with XML will follow.
|
|
</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>3.0</revnumber>
|
|
<date>Aug 24, 2000</date>
|
|
<authorinitials>gjf</authorinitials>
|
|
<revremark>Integrated David Merrill's style guide document. Further clean-up and additions.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>2.0</revnumber>
|
|
<date>Jul 13, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Cleaned up using-docbook a bit. Moved some chapters</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>1.9</revnumber>
|
|
<date>Jun 26, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Integrated Jorge's using-docbook document.</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>1.5</revnumber>
|
|
<date>Jun 14, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Documented sgedit</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>1.4</revnumber>
|
|
<date>Jun 12, 2000</date>
|
|
<authorinitials>mfk</authorinitials>
|
|
<revremark>Documented vim and sgedit. Spelling and other
|
|
changes from ldp list. Also added LDP guidelines under style
|
|
guide.</revremark>
|
|
</revision>
|
|
-->
|
|
|
|
</revhistory>
|
|
</bookinfo>
|
|
|
|
|
|
<!-- Chapter one: about this guide
|
|
This chapter includes:
|
|
-->
|
|
&aboutthisguide;
|
|
|
|
<!-- Chapter two: authoring overview
|
|
This chapter includes:
|
|
-->
|
|
&authoring-overview;
|
|
|
|
<!-- Chapter three: propose
|
|
This chapter includes:
|
|
-->
|
|
&authoring-proposal;
|
|
|
|
<!-- Chapter four: write
|
|
This chapter includes:
|
|
-->
|
|
&authoring-writing;
|
|
|
|
<!-- Appendix B: Editors, Validation and System Setup -->
|
|
&tools;
|
|
|
|
<section id="other">
|
|
<title>Other/Reference</title>
|
|
<para>The items in this section are reference books or other
|
|
utilities that can't quite be categorized (yet).</para>
|
|
|
|
<section id="docbooktdg">
|
|
<title>DocBook: The Definitive Guide</title>
|
|
<para><ulink
|
|
url="http://www.docbook.org/">http://www.docbook.org/</ulink></para>
|
|
<para>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, and much of the emphasis is on XML, but
|
|
the DocBook tags for version 3.1 are all listed in a handy
|
|
format. You can pick it up at the book vendor of choice. The
|
|
entire book is also available online (in HTML and SGML
|
|
formats) at the above URL. </para>
|
|
</section>
|
|
|
|
<section id="templates">
|
|
<title>LDP templates, tools & links</title>
|
|
<para>Optional - <ulink url="http://www.tldp.org/authors/index.html#resources">http://www.tldp.org/authors/index.html#resources</ulink></para>
|
|
<para>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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="aspell">
|
|
<title>Aspell</title>
|
|
<para>Optional - <ulink
|
|
url="http://aspell.sourceforge.net/">http://aspell.sourceforge.net/</ulink></para>
|
|
<para>This spell checking application can work around SGML
|
|
tags, and only spell check the content within the
|
|
tags. Older version of ispell will try to spell
|
|
check the tags, causing errors at every new tag.</para>
|
|
</section>
|
|
<section id="ispell">
|
|
<title>ispell</title>
|
|
<para>Optional - <ulink url="http://www.cs.hmc.edu/~geoff/ispell.html">http://www.cs.hmc.edu/~geoff/ispell.html</ulink></para>
|
|
<para>The ispell program is distributed with RedHat (and possibly other
|
|
distros) and also ignores markup tags.</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
&using-docbook;
|
|
|
|
&style-guide;
|
|
|
|
<chapter id="other-style">
|
|
<title> Additional Style-related Items</title>
|
|
<para> This section contains additional style-oriented topics to
|
|
consider when preparing your document. </para>
|
|
|
|
<section id="accepteddates">
|
|
<title> Date formats </title>
|
|
<para> The <sgmltag class="starttag">pubdate</sgmltag> 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: </para>
|
|
<programlisting format="linespecific"><sgmltag class="starttag">pubdate</sgmltag>2002-04-25<sgmltag class="endtag">pubdate</sgmltag></programlisting>
|
|
<para>
|
|
The date is in the format YYYY-MM-DD, which is one of the
|
|
<ulink url="http://www.w3.org/TR/NOTE-datetime">ISO 8601</ulink> 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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="acceptedrev">
|
|
<title> Revision History </title>
|
|
<para> The <sgmltag class="starttag">revhistory</sgmltag> tag should be
|
|
used to denote the various revisions of the document. Specify the
|
|
date, revision number and comments regarding what has changed.</para>
|
|
<para>
|
|
Revisions should be listed with the most-recent version at the
|
|
top (list in descending order).
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sampleai">
|
|
<title> Sample Article (or Book) Information Element </title>
|
|
<para> Here is a sample of a complete DocBook (SGML or XML)
|
|
<sgmltag class="starttag">articleinfo</sgmltag>
|
|
element which contains some of the items and constructs previously
|
|
described. </para>
|
|
<programlisting format="linespecific">
|
|
<articleinfo>
|
|
|
|
<!-- Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate -->
|
|
<title>Sample HOWTO</title>
|
|
|
|
<author>
|
|
<firstname>your_firstname</firstname>
|
|
<surname>your_surname</surname>
|
|
<affiliation>
|
|
<!-- Valid email...spamblock/scramble if so desired -->
|
|
<address><email>xxx (at) xxx.xxx</email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<pubdate>2002-04-25</pubdate>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>1.0</revnumber>
|
|
<date>2002-04-25</date>
|
|
<authorinitials>xx</authorinitials>
|
|
<revremark>first official release</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>0.9</revnumber>
|
|
<date>2002-04-15</date>
|
|
<authorinitials>xx</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></programlisting>
|
|
</section>
|
|
|
|
<section id="acceptedgfx">
|
|
<title>Graphics formats</title>
|
|
<para> When submitting graphics to the LDP, please submit one
|
|
set of graphics in <filename>.eps</filename>, and another in
|
|
<filename moreinfo="none">.gif</filename>, <filename
|
|
moreinfo="none">.jpg</filename> or <filename moreinfo="none">
|
|
.png</filename>. The preferred format is <filename moreinfo="none">
|
|
.png</filename> or <filename moreinfo="none">.jpg</filename> due to
|
|
patent problems with <filename moreinfo="none">.gif</filename>.
|
|
</para>
|
|
<para>
|
|
You can use <filename moreinfo="none">.jpg</filename> file for
|
|
continuous-tone images such as photos or images with gradual
|
|
changes in color. Use <filename moreinfo="none">.png</filename>
|
|
for simple images like diagrams, some screen shots, and images
|
|
with a low number of colors.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="acceptedversions">
|
|
<title>DocBook Versions</title>
|
|
<para>
|
|
The LDP supports and accepts documentation in the following formats:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
SGML DocBook versions 4.x and 3.1
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
SGML LinuxDoc
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
XML DocBook version 4.1.2
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>When writing your DocBook header, it should look like
|
|
this:</para>
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</sgmltag>
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="nooldtags">
|
|
<title>Obsolete Tags</title>
|
|
<para>Some tags listed in <emphasis>DocBook: The Definitive
|
|
Guide</emphasis> may be listed as being discarded in future
|
|
revisions of DocBook. To maintain future compatability, the
|
|
LDP recommends against using tags that will be discarded in
|
|
the future. Some ways to use newer tags are listed in the
|
|
tip and tricks section.</para>
|
|
</section>
|
|
|
|
<section id="notagmin">
|
|
<title>Tag Minimization</title>
|
|
<para>Tag minimization is using <sgmltag
|
|
class="endtag"></sgmltag> instead of the full end of a tag (such
|
|
as <sgmltag class="endtag">para</sgmltag>. Since this makes the
|
|
document more confusing for future authors and LDP members, and
|
|
is not allowed in XML DocBook, please refrain from this
|
|
practice.</para>
|
|
</section>
|
|
|
|
<section id="usingconventions">
|
|
<title>Conventions</title>
|
|
<para>Conventions for different kinds of text is as
|
|
follows:</para>
|
|
<para>If you're going to show the use of a command, format the
|
|
command so it looks like a user's command line. The prompt must
|
|
contain the shell type (bash, tcsh, zsh, etc) followed by a $
|
|
for commands to be run as a normal (non-root) user or a # for a
|
|
root user.</para>
|
|
<para> A command would then look like this: </para>
|
|
<screen format="linespecific">
|
|
<prompt>bash$</prompt> <command>command "run as a normal user"</command>
|
|
<prompt>bash#</prompt> <command>command "run as a root user"</command>
|
|
<prompt>tcsh#</prompt> <command>setenv DISPLAY :0.0</command>
|
|
</screen>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="tips">
|
|
<title>Tips and Tricks with DocBook</title>
|
|
<para>This section covers a few quirks of DocBook that you may run
|
|
into when writing your documents.</para>
|
|
|
|
<section id="images">
|
|
<title>Including Images</title>
|
|
<para>If you plan on including images in your HOWTOs, you can
|
|
now do this, as LinuxDoc didn't support images. Here's a sample
|
|
way of including an image in your HOWTOS:</para>
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">figure</sgmltag>
|
|
<sgmltag class="starttag">title</sgmltag>LyX screen shot<sgmltag class="endtag">title</sgmltag>
|
|
<sgmltag class="starttag">mediaobject</sgmltag>
|
|
<sgmltag class="starttag">imageobject</sgmltag>
|
|
<sgmltag class="starttag">imagedata fileref="lyx_screenshot.eps" format="eps"</sgmltag>
|
|
<sgmltag class="endtag">imageobject</sgmltag>
|
|
<sgmltag class="starttag">imageobject</sgmltag>
|
|
<sgmltag class="starttag">imagedata fileref="lyx_screenshot.jpg" format="jpg"</sgmltag>
|
|
<sgmltag class="endtag">imageobject</sgmltag>
|
|
<sgmltag class="starttag">textobject</sgmltag>
|
|
<sgmltag class="starttag">phrase</sgmltag>Screen shot of the LyX document processing program<sgmltag class="endtag">phrase</sgmltag>
|
|
<sgmltag class="endtag">textobject</sgmltag>
|
|
<sgmltag class="endtag">mediaobject</sgmltag>
|
|
<sgmltag class="endtag">figure</sgmltag>
|
|
</programlisting>
|
|
<para>This is a better way than using <sgmltag
|
|
class="starttag">graphic</sgmltag> for two reasons. First,
|
|
<sgmltag class="starttag">graphic</sgmltag> will be removed in
|
|
DocBook 5.0 in favor of the <sgmltag
|
|
class="starttag">mediaobject</sgmltag> tag. So you may as well
|
|
get started with the right way now. Second, <sgmltag
|
|
class="starttag">mediaobject</sgmltag> allows for different kinds
|
|
of media based on what the output is. In this example, the first
|
|
<sgmltag class="starttag">imageobject</sgmltag> is an encapsulated
|
|
PostScript(eps) file for use with formats derived from TeX such as
|
|
DVI, PS, and PDF. The second <sgmltag
|
|
class="starttag">imageobject</sgmltag> is a JPEG image for visual
|
|
display, mostly for HTML output. The <sgmltag
|
|
class="starttag">textobject</sgmltag> is presented if the output
|
|
doesn't support graphics (TXT). Think of it as an HTML <sgmltag
|
|
class="starttag">alt</sgmltag> tag.</para>
|
|
</section>
|
|
|
|
<section id="namedfiles">
|
|
<title>Naming separate HTML files</title>
|
|
<para>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:</para>
|
|
<para>In your first <sgmltag class="starttag">article</sgmltag>
|
|
tag (which should be the only one) include an id parameter and
|
|
call it index. This will make your tag look like this:</para>
|
|
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">article id="index"</sgmltag>
|
|
</programlisting>
|
|
|
|
<para>On the first <sgmltag class="starttag">chapter</sgmltag>
|
|
tag, do not modify it, as it's usually an introduction and you
|
|
want that on the first page. For each other <sgmltag
|
|
class="starttag">section</sgmltag> 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.</para>
|
|
|
|
<programlisting format="linespecific">
|
|
<sgmltag class="starttag">chapter id="tips"</sgmltag>
|
|
</programlisting>
|
|
</section>
|
|
|
|
&using-ldp-dsssl;
|
|
|
|
&using-ldp-xsl;
|
|
|
|
</chapter>
|
|
|
|
<chapter id="distribution">
|
|
<title> Distributing your documentation </title>
|
|
|
|
<section id="beforeyoudistribute">
|
|
<title> Before you distribute </title>
|
|
<para> Before you distribute your code to millions of potential
|
|
readers there are a few things you should do. </para>
|
|
<para> First, be sure to spell-check your document. Most
|
|
utilities that you would use to write SGML have plug-ins to
|
|
perform a spell check. If not, there's always the aspell
|
|
program. </para>
|
|
<para> Second, get someone to review your documentation for
|
|
factual correctness. You can also ask for general
|
|
comments. The documentation that is
|
|
published by the LDP needs to be as factually correct as
|
|
possible, as there are millions of Linux users that may be
|
|
reading it. If you're part of a larger mailing list talking
|
|
about the subject, ask others from the list to help you
|
|
out. </para>
|
|
<para> Third, create a web site where you can distribute your
|
|
documentation. This isn't required, but is helpful for people to
|
|
find the original location of your document. </para>
|
|
|
|
<section id="validatecode">
|
|
<title>Validating SGML code </title>
|
|
<para> Using jade, or really the nsgmls command, you can
|
|
validate your .sgml code against the DTD to make sure there
|
|
aren't any errors. </para>
|
|
|
|
<screen>
|
|
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.sgml</command>
|
|
</screen>
|
|
|
|
<para> If there are no issues, you'll just get your command
|
|
prompt back. </para>
|
|
</section>
|
|
<section id="validatexml">
|
|
<title>Validating XML code</title>
|
|
<para>Validating XML is a touch harder than validating SGML
|
|
code, but it can be done. You will need to have XML DocBook
|
|
installed, and then set the <envar>SGML_CATALOG_FILES</envar>
|
|
to the location of xml.soc (included with jade) and to
|
|
the location of the DocBook XML catalog file.
|
|
</para>
|
|
<screen>
|
|
<prompt>bash$</prompt> <command>export <envar>SGML_CATALOG_FILES</envar>=/usr/lib/sgml/declaration/xml.soc:/usr/lib/xml/catalog</command>
|
|
<prompt>bash$</prompt> <command>nsgmls -s HOWTO-HOWTO.xml</command>
|
|
</screen>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="makingcopyright">
|
|
<title> Copyright and Licensing issues </title>
|
|
<para> In order for an LDP document to be accepted by the LDP,
|
|
it must be licensed to conform to the "LICENSE REQUIREMENTS"
|
|
section of the LDP Manifesto located at <ulink
|
|
url="http://www.tldp.org/manifesto.html">http://www.tldp.org/manifesto.html</ulink>.
|
|
As an author, you may retain the copyright and add other
|
|
restrictions (for example, you must approve any translations or
|
|
derivative works). </para>
|
|
|
|
<para> We recommend using the <ulink
|
|
url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation
|
|
License (GFDL)</ulink> or the <ulink
|
|
url="http://opencontent.org/openpub/">Open Publication License
|
|
(OPL)</ulink> <emphasis>without</emphasis> options A and B. If
|
|
you choose, you can get DocBook markups of both the GNU GPL
|
|
and the GNU FDL from <ulink url="http://developer.gnome.org/projects/gdp/licenses.html">
|
|
the GNOME Documentation Project</ulink>. You can then merely
|
|
include the license in its entirety in your document. Due
|
|
to its length, you may just want to provide a link
|
|
to the source.</para>
|
|
|
|
<para>If you choose to use a boilerplate copyright, simply copy it
|
|
into your source code under a section called <quote>Copyright
|
|
and Licenses</quote> or similar. Also include a copyright
|
|
statement of your own (since you still own it). If you are a new
|
|
maintainer of an already-existing HOWTO, you must include the
|
|
previous copyright statements of the previous author(s) and the
|
|
dates they maintained that document. </para>
|
|
|
|
<para>You'll note that the licensing for the LDP Author Guide
|
|
requires notification to the author of any derivative works or
|
|
translations. I also explicitly place any source code (aside
|
|
from the SGML the Guide was written in) under the GPL. If your
|
|
HOWTO includes bits of source code that you want others to use,
|
|
you may do the same.</para>
|
|
</section>
|
|
|
|
<section id="submission">
|
|
<title> Submission to LDP </title>
|
|
<para> Once your LDP document has been carefully reviewed, you
|
|
can release your document to the LDP. Send an e-mail with the
|
|
SGML source code as an attachment (you may gzip it if you like)
|
|
to <email>submit@en.tldp.org</email>. </para>
|
|
|
|
<para> Be sure to include the name of your HOWTO in the subject
|
|
line, and use the body to outline changes you've made and attach
|
|
your HOWTO. This allows the maintainers to do their jobs faster,
|
|
so you will not have to wait for your HOWTO to be updated on the
|
|
LDP web site. If you don't hear anything in 5 calendar days,
|
|
please follow up with an e-mail to make sure things are still in
|
|
process. </para>
|
|
|
|
<para>If your HOWTO contains extras, such as graphics or a
|
|
special catalog, create a.tar.gz file with all the files in it
|
|
including the .sgml source code and mail it as an attachment to
|
|
the ldp-submit list.</para>
|
|
|
|
<para>If you are using the LDP CVS tree while developing
|
|
your document, the LDP will still need to be notified when your
|
|
document is ready to be published. E-mail should be sent to
|
|
<email>submit@en.tldp.org</email>. Indicate
|
|
the title of your document and the relative path to the
|
|
file(s) in the LDP CVS tree within your message. </para>
|
|
</section>
|
|
|
|
<section id="maintentance">
|
|
<title>Maintaining Your HOWTO</title>
|
|
|
|
<para>
|
|
Just because your HOWTO has now been published doesn't mean your
|
|
job is done. HOWTOs need regular maintenance, to make sure they
|
|
are up to date, and to improve them in response to readers' ideas
|
|
and suggestions. A HOWTO is a living, growing body of knowledge,
|
|
not just a publish-and-forget-it static document.
|
|
</para>
|
|
|
|
<para>
|
|
You put your email address in the HOWTO, and politely requested
|
|
feedback from your readers, right? Once you are officially published,
|
|
you will begin to receive notes with suggestions. Some will be
|
|
very valuable; others will request personal assistance. You should
|
|
feel free to decline personal assistance if you cannot spare the
|
|
time. Writing a HOWTO for the LDP doesn't commit you to a lifetime
|
|
of free support for anyone on the net. It is polite to refer
|
|
questioners to another resource, if you can. And, if you see a
|
|
pattern in the questions you receive, it might indicate a topic
|
|
you should add to your HOWTO.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="faq">
|
|
<title> FAQs about the LDP </title>
|
|
|
|
<qandaset defaultlabel="qanda">
|
|
<qandaentry>
|
|
<question>
|
|
<para>I want to help the LDP. How can I do this?</para>
|
|
</question>
|
|
<answer>
|
|
<para> The easiest way is to find something and document
|
|
it. Also check the unmaintained HOWTOs and see if there is a
|
|
subject there that you know about and can continue
|
|
documenting. </para>
|
|
</answer>
|
|
</qandaentry>
|
|
<qandaentry>
|
|
<question>
|
|
<para> I want to publish a collection of LDP documents in a
|
|
book. How is the LDP content licensed? </para>
|
|
</question>
|
|
<answer>
|
|
<para> Please see <ulink
|
|
url="http://www.tldp.org/manifesto.html#pub">http://www.tldp.org/manifesto.html#pub</ulink> for more information about publishing LDP documents.
|
|
</para>
|
|
</answer>
|
|
</qandaentry>
|
|
<qandaentry>
|
|
<question>
|
|
<para> I found an error in an LDP document. Can I fix it? </para>
|
|
</question>
|
|
<answer>
|
|
<para> Contact the author of the document, or the LDP
|
|
coordinator at <email>feedback@en.tldp.org</email> and
|
|
mention the problem and how you think it needs to be
|
|
fixed. </para>
|
|
</answer>
|
|
</qandaentry>
|
|
<qandaentry>
|
|
<question>
|
|
<para>But I don't know SGML/Can't get the tools working/Don't
|
|
like SGML</para>
|
|
</question>
|
|
<answer>
|
|
<para> That's okay. You have the option of writing your first
|
|
draft of the HOWTO in the format of your choice, then submit
|
|
that to the LDP. An LDP volunteer will review the document,
|
|
then convert it into DocBook for you. Once that's done,it will
|
|
be easier for you to maintain the HOWTO. If you have
|
|
questions, you can always drop a line to the LDP volunteer or the
|
|
LDP Docbook list
|
|
at <email>docbook@en.tldp.org</email>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
</chapter>
|
|
|
|
&gfdl;
|
|
|
|
&glossary;
|
|
|
|
&doc-index;
|
|
|
|
</book>
|
|
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-set-face: 1
|
|
sgml-validate-command: "nsgmls -s /usr/share/sgml/xml.dcl %s %s"
|
|
End:
|
|
-->
|