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

t-* are Tille's Templates. Then there are a few other files which are NOT 

finished but I wanted backed up for sanity's sake. I think this is the last
of the XML files for tonight. (Does anyone read these notes?) I'm also
going to add a few .txt files that have some notes I want preserved.
They'll be deleted when they are incorporated into the full document.
This commit is contained in:
emmajane 2003-08-13 06:28:32 +00:00
parent 9af0c270e2
commit 33b94ef0a1
12 changed files with 942 additions and 368 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -21,6 +21,7 @@
<!-- Chapter Four: Write -->
<!ENTITY authoring-writing SYSTEM "authoring-writing.xml">
<!ENTITY cvs SYSTEM "cvs.xml">
@ -36,7 +37,6 @@
<!ENTITY example-table SYSTEM "example-table.xml">
<!ENTITY dsl-example SYSTEM "dsl-example.xml">
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY cvs SYSTEM "cvs.xml">
<!ENTITY xml SYSTEM "docbook-xml.xml">
<!ENTITY style-guide SYSTEM "style-guide.xml">
<!ENTITY using-ldp-dsssl SYSTEM "using-ldp-dsssl.xml">

57
LDP/guide/docbook/LDP-Author-Guide/abouttheguide.xml Normal file
View File

@ -0,0 +1,57 @@
<chapter id="aboutthisguide">
<title>About this Guide</title>
<section id="purpose">
<title>About this Guide</title>
<para>This document was started on Aug 26, 1999 by Mark
F. Komarinski after two day's worth of frustration getting tools
to work. If even one LDP author is helped by this, then I did my
job.</para>
<para>
The newest version of this document can be found at the LDP
homepage
<ulink url="http://www.tldp.org/">http://www.tldp.org</ulink>.
The original DocBook, HTML, and other formats can be found there.
</para>
<para>There are many ways to contribute to the Linux movement
without actually writing code. One of the most important is
writing documentation, allowing each person to share their
knowledge with thousands of others around the world. This Guide
is designed to help you get familiar with how the LDP works, and
what tools you'll need to write your own HOWTO.</para>
</section>
<!-- Because I haven't decided where to put it, the
About The LDP
section has become an entity. Currently the file starts with a
<section>
-->
&tldp;
<!-- End of section about The LDP -->
<section id="feedback">
<title>Feedback</title>
<para>Comments on this Guide may be directed to the LAG coordinator
(<email>mkomarinski@wayga.org</email>).</para>
</section>
<section id="copyrights">
<title>Copyrights and Trademarks</title>
<para>Copyright 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy</para>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the appendix entitled "GNU
Free Documentation License".
</para>
</section>
<!-- The Acknowledgements section should be moved to the end according
to the LDP Author Guide Text -->
&thankyous;
<!-- Document conventions -->
&conventions;
</chapter>

225
LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml
View File

@ -225,225 +225,12 @@
</para>
</section>
<section id="cvs">
<title>Concurrent Versions System (CVS)</title>
<para>
The LDP is providing CVS access to authors. There are a few
good reasons for this:
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para> CVS will keep an off-site backup of your documents. In
the event that you hand over a document to another author,
they can just retrieve the document from CVS and continue
on. In the event you need to go back to a previous version of
a document, you can retrieve it as well. </para>
</listitem>
<listitem>
<para> It's great to have many people working on the same
document. You can have CVS tell you what changes were made
while you were editing your copy by another author, and
integrate those changes in. </para>
</listitem>
<listitem>
<para>CVS keeps a log of what changes were made. These logs (and
a date stamp) can be placed automatically inside the document
when you use some special tags that get processed before the
SGML processor. </para>
</listitem>
<listitem>
<para> It can provide for a way for a program to automatically
update the LDP web site with new documentation as it's written
and submitted. This is not in place yet, but it is a potential
goal. Currently, CVS updates signal the HOWTO coordinator to
update the LDP web page, meaning that if you use CVS, you're not
required to e-mail your SGML code. </para>
</listitem>
</orderedlist>
<para> If you're completely new to CVS, there are a few web pages
you may want to look at which can help you out: </para>
<itemizedlist>
<listitem>
<para> <ulink
url="http://cvshome.org/docs/blandy.html">http://cvshome.org/docs/blandy.html</ulink>
</para>
</listitem>
<listitem>
<para> <ulink
url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">http://tldp.org/HOWTO/CVS-RCS-HOWTO.html</ulink>
</para>
</listitem>
</itemizedlist>
<para>
You can browse the LDP CVS repository via the web at <ulink
url="http://cvsview.tldp.org/">http://cvsview.tldp.org/</ulink>.
</para>
<section id="getaccount">
<title> Getting a CVS account </title>
<para> First you'll need to get an account at the LDP's CVS
Repository. This is pretty much the root directory that is used
by CVS, with various projects (HOWTOs, guides, etc.)
created as subdirectories of it. </para>
<para>Please fill the form:
<ulink url="http://tldp.org/cvs/">
http://tldp.org/cvs/</ulink>
</para>
<para>During filling the form we want you to inform us about
your plans, eg. which HOWTO you maintain.
</para>
<para>Your unique
CVSROOT directory will be created and you'll get an e-mail with
a response. Remember your password, it will <emphasis>not</emphasis>
be sent in the email. When you get your response, log into your CVSROOT
and make sure everything is set up properly: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>export
CVSROOT=:pserver:<replaceable>your_userid</replaceable>@cvs.tldp.org:/cvsroot</command>
<prompt>bash$</prompt> <command>cvs -d $CVSROOT login</command>
</screen>
<para> (Replace the <replaceable>your_userid</replaceable> with what
you were sent in the response e-mail). </para>
<para> You will be asked for your password, and then be given
access to the CVS Repository in read-write mode. Once you've
used <command moreinfo="none">cvs login</command> once and have
been given access to the system, your password is stored in
<filename moreinfo="none">.cvspass</filename> and you will not
have to use <command moreinfo="none">cvs login</command>
again. Just set the CVSROOT and continue on. You can get the
entire repository with this command: </para>
<screen>
<prompt>bash$</prompt> <command>cvs get LDP</command>
</screen>
<para> Or you can get the source for your own document with
these commands: </para>
<screen format="linespecific">
<prompt>bash$</prompt> <command>cvs get LDP/howto/docbook/YOUR-HOWTO.sgml</command>
<prompt>bash$</prompt> <command>cvs get
guide/docbook/YOURGUIDE</command>
</screen>
</section>
<section id="usingcvs">
<title>Using CVS</title>
<para>
There are a number of documents that can help you get up and
running with CVS. The <ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">CVS-RCS-HOWTO Document for Linux (Source Code
Control System)</ulink> gives an overview of <ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO-4.html">CVS
Commands</ulink>
</para>
<variablelist>
<title>CVS Commands: a brief reminder</title>
<varlistentry>
<term>$Id&dollar;</term>
<listitem><para>
Automatically insert the date and version directly into the
document when a document is committed. e.g. $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
want to bypass the editor screen you can use
<command>
cvs <option>commit</option> <option>-m &quot;comment&quot;</option>
</command>.</para>
<note><para>You must still email <email>submit@en.tldp.org</email>
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.
</para></note>
</listitem>
</varlistentry>
<varlistentry>
<term>add</term>
<listitem><para>
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 <email>submit@en.tldp.org</email> to ensure you can
add graphics or other files to your HOWTO.
</para>
<para>
Copy the files you want to add into your local CVS repository
(where all of your downloaded/working files are). Then:
<command>cvs add <replaceable>filename</replaceable></command>.
After you've added the files, you still need to commit them to the
repository (see above).
</para>
<para>
If you need to replace an old file name with a new one, 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:
<command>cvs remove <replaceable>filename</replaceable></command>.
As with the add command, you need to <quote>commit</quote> 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).
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="recovery">
<title>Recovering old versions</title>
<para>
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 and older
version of your file.
</para>
<para>
To do this, you'll need to know the version number of the
file you want to retrieve. <command>cvs diff</command>
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.
</para>
<para>
The command <command>cvs -Q update -p -r <replaceable>revision</replaceable></command>
<replaceable>filename</replaceable> will output to stdout
the contents of the <replaceable>revision</replaceable> version
of <replaceable>filename</replaceable>. You can pipe it to
<command>more</command> or redirect the output to a file.
Conveniently, you can redirect stdout to a file called
<replaceable>filename</replaceable>. Your local file
is now the revision you want, and <command>cvs update
</command> will update the CVS server with the new (old)
version of <replaceable>filename</replaceable>.
</para>
</section>
</section> <!-- cvs -->
<!--
I really am trying to hack the CVS section down and either remove it
completely or at least move it to an appendix. too tired right now so
the entity reference remains:
-->
&cvs;
<section id="tools-other">

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

@ -1,36 +1,10 @@
A few extra shortcuts:
<!--
I really am trying to either get rid of this section, or at least move
it to an appendix. I haven't suceeded yet, but really I need some sleep.
-->
Date: Mon, 4 Aug 2003 08:18:51 -0400
From: Greg Ferguson <gferg@sgi.com>
Subject: re: DocBook SGML to XML
> Since the toolchain for XML seems to be simpler
> than the toolchain for SGML (at least on RH9) I'd
> like to move my HOWTO from SGML to XML.
>
> What's the procedure for this with CVS.
>
> Thanks,
> Glen
>
>
rm docbook/<howto>.sgml
cvs rm docbook/<howto>.sgml
cvs commit -m "removed" docbook/<howto>.sgml
cvs add docbook/<howto>.xml
cvs commit -m "removed" docbook/<howto>.xml
If you cannot perform these, I will do it for you. You can send
the (new XML) doc to submit@en.tldp.org. Indicate what you
wish to have done.
<section id="cvs">
<title> CVS </title>
<title>Concurrent Versions System (CVS)</title>
<para>
The LDP is providing CVS access to authors. There are a few
good reasons for this:
@ -79,24 +53,35 @@ wish to have done.
<para> <ulink
url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">http://tldp.org/HOWTO/CVS-RCS-HOWTO.html</ulink>
</para>
</listitem>
</itemizedlist>
<para>
You can browse the LDP CVS repository via the web at <ulink
url="http://cvsview.tldp.org/">http://cvsview.tldp.org/</ulink>.
</para>
<section id="getaccount">
<title> Getting a CVS account </title>
<para> First you'll need to get an account at the LDP's CVS
Repository. This is pretty much the root directory that is used
by CVS, with various projects (HOWTOs, mini HOWTOs, etc.)
by CVS, with various projects (HOWTOs, guides, etc.)
created as subdirectories of it. </para>
<para>Please fill the form:
<ulink url="http://tldp.org/cvs/">
http://tldp.org/cvs/</ulink>
</para>
<para>During filling the form we want you to inform us about
your plans, eg. which Howto you maintain.
your plans, eg. which HOWTO you maintain.
</para>
<para>Your unique
CVSROOT directory will be created and you'll get an e-mail with
a response. When you get your response, log into your CVSROOT
a response. Remember your password, it will <emphasis>not</emphasis>
be sent in the email. When you get your response, log into your CVSROOT
and make sure everything is set up properly: </para>
<screen format="linespecific">
@ -120,7 +105,7 @@ wish to have done.
<prompt>bash$</prompt> <command>cvs get LDP</command>
</screen>
<para> Or you can get the SGML source for your own document with
<para> Or you can get the source for your own document with
these commands: </para>
<screen format="linespecific">
@ -130,122 +115,82 @@ guide/docbook/YOURGUIDE</command>
</screen>
</section>
<section id="othercvsnotes">
<title> Other CVS repository notes </title>
<section id="usingcvs">
<title>Using CVS</title>
<para>
There are a number of documents that can help you get up and
running with CVS. The <ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">CVS-RCS-HOWTO Document for Linux (Source Code
Control System)</ulink> gives an overview of <ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO-4.html">CVS
Commands</ulink>
</para>
<section id="cvsweb">
<title> CVS Files via web </title>
<para> You can access the CVS repository via the web at <ulink
url="http://cvsview.tldp.org/">http://cvsview.tldp.org/</ulink>.
</para>
</section>
<variablelist>
<title>CVS Commands: a brief reminder</title>
<section id="cvsgraphics">
<title> Graphical access to CVS </title>
<para> There are graphical interfaces to CVS, and you can get
a list of them at <ulink
url="http://freshmeat.net/appindex">http://freshmeat.net/appindex</ulink>.
Search for CVS. </para>
</section>
</section>
<varlistentry>
<term>$Id&dollar;</term>
<listitem><para>
Automatically insert the date and version directly into the
document when a document is committed. e.g. $Id: cvs.xml,v 1.9
2002/04/21 09:44:26 serek Exp $
</para></listitem>
</varlistentry>
<section id="commoncvscommands">
<title>Common CVS Commands</title>
<section id="updatingcvs">
<title>Updating files and CVS </title>
<para> CVS has a special tag, <emphasis>$Id&dollar;</emphasis>, that you
can use to automatically insert the date and version directly
into the document. After committing, CVS will turn this tag into
<emphasis>$Id$
</emphasis>. By including this tag in your document, you
can have that automatically change each time you change the
file, allowing the revision mark to increment each time. </para>
<para> When you're ready to upload changes to the CVS server,
use the command <command moreinfo="none">cvs ci -m
&quot;comment&quot; YOUR-HOWTO.sgml</command>. The -m
&quot;comment&quot; isn't necessary, but if you don't include
it, you'll be brought into the editor (usually vi, or whatever
your <envar>EDITOR</envar> environment variable is) and be given
the chance to add a comment about the changes. </para>
<para> You can follow more of the CVS discussion on the
discuss list. </para>
<para>If you are using the LDP CVS tree while developing your
document, the LDP will need to be notified when your
document is ready to be published. There are two methods:</para>
<varlistentry>
<term>commit</term>
<listitem><para>
This option will upload your changes to the CVS server. If you
want to bypass the editor screen you can use
<command>
cvs <option>commit</option> <option>-m &quot;comment&quot;</option>
</command>.</para>
<note><para>You must still email <email>submit@en.tldp.org</email>
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.
</para></note>
</listitem>
</varlistentry>
<itemizedlist>
<listitem>
<para>You can add to the CVS commit message a text similar to
"- ready for publish."</para>
</listitem>
<listitem>
<para>You can notify us by e-mail. E-mail should be sent to
<email>submit@en.tldp.org</email>. Indicate within the message
the title of your document and the relative path to the
file(s) in the LDP CVS tree. </para>
</listitem>
</itemizedlist>
<para>We prefer CVS users to trigger a publishing operation thru their
'commits' message.</para>
</section>
<section id="addnewcvs">
<title>Adding new files</title>
<para>
If your document contains graphics or multiple files, you
may come to a point where you need to add new files to
your cvs repository.
<varlistentry>
<term>add</term>
<listitem><para>
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 <email>submit@en.tldp.org</email> to ensure you can
add graphics or other files to your HOWTO.
</para>
<para>
Copy the files you want to add into your local CVS repository
(where all of your downloaded/working files are). Then:
<command>cvs add <replaceable>filename</replaceable></command>.
After you've added the files, you still need to commit them to the
repository (see above).
</para>
<para>
To do this, make sure that your HOWTO is in its own directory.
You may want to coordinate with the people at
<email>submit@en.tldp.org</email> to ensure you can
add graphics or other files to your HOWTO.
</para>
<para>
Once this is set up, use <command>cvs get</command> to get
the latest copy of your HOWTO. In most cases, the command
will be similar to <command>cvs get LDP/howto/docbook/YOUR-HOWTO/</command>
assuming that your CVSROOT is set.
</para>
<para>
Copy in the files that you want to add to the repository.
The command <command>cvs add <replaceable>filename</replaceable></command>
will tell the CVS server that you want to add
<replaceable>filename</replaceable> to the repository.
You can now use <command>cvs commit</command> to commit
the changes to the CVS server. When finished, the files
are now part of the repository.
</para>
</section>
<section id="tagrelease">
<title>Creating Tag Releases</title>
<para>
Occasionally, you may want to create what you call a stable
release. This is an effective way to signal to the
LDP coordinator that your document is ready for release.
This tag release indicates a specific version of your
HOWTO. This allows you to continue creating new versions
of your HOWTO without them being accidentally put
on the web site.
</para>
<para>
The downside of creating a stable (or tag) release is that
it uses the current version of the files - the last
ones submitted. Use <command>cvs commit</command> to
make sure that your files are synced up, then use
<command>cvs -q tag <replaceable>Release-x_y</replaceable></command>.
</para>
<para>
You can replace the <replaceable>Release-x_y</replaceable> with
whatever you like. However, to create a wall between CVS revisions
and tag releases, the tag release nust start with a letter,
and contain letters, numbers, hyphens, or underscores.
</para>
</section>
<para>
If you need to replace an old file name with a new one, 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:
<command>cvs remove <replaceable>filename</replaceable></command>.
As with the add command, you need to <quote>commit</quote> 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).
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="recovery">
<title>Recovering old versions</title>
<para>
@ -275,7 +220,5 @@ guide/docbook/YOURGUIDE</command>
</command> will update the CVS server with the new (old)
version of <replaceable>filename</replaceable>.
</para>
</section>
</section>
</section>
</section> <!-- cvs -->

203
LDP/guide/docbook/LDP-Author-Guide/references.xml Normal file
View File

@ -0,0 +1,203 @@
resources/references
In our "author's resources" area:
http://tldp.org/authors/#resources
there are pointers to various helpful documents/books including:
DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner
http://docbook.org/tdg/en/html/docbook.html
DocBook XML/SGML Processing Using OpenJade, by Saqib Ali
http://tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/
DocBook Install mini-HOWTO, by Robert B Easter
http://tldp.org/HOWTO/mini/DocBook-Install/
and there also pointers to downloadable template files for
HOWTOs (in DocBook SGML/XML and Linuxdoc SGML).
http://tldp.org/HOWTO/HOWTO-INDEX/misc.html#MISCAUTHOR
LinuxDoc (another accepted format)
http://www.faqs.org/docs/Linux-mini/Howtos-with-LinuxDoc.html
This:
http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/frames.html
It makes DocBook XML fun!
Example of a well-written document
(http://cvsview.tldp.org/index.cgi/*checkout*/LDP/howto/docbook/RedHat-CD-HOWTO/RedHat-CD-HOWTO.sgml?rev=1.4&amp;content-type=text/plain).
> Can you tell me where I can download the .xml files? I seem to get the html pages only.
There is a link on main page, that goes to:
http://tldp.org/docs.html#howto
You can grab the source for any of the TLDP documents by searching
the CVS web interface:
http://cvsview.tldp.org/
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
<section id="newauthorresources">
<title>Resources for New Authors</title>
<para>
This section contains a list of web sites and books
that may be useful to new readers. If you have never used
DocBook before, or have never written technical documentation
before, please take a look at these.
</para>
<itemizedlist>
<listitem>
<para>
<ulink
url="http://www.tldp.org/authors/index.html#resources">LDP
Author's Resources page</ulink> - templates, links, and
tools.
</para>
</listitem>
<listitem>
<para>
<ulink
url="http://lwn.net/2000/features/DocBook/">http://lwn.net/2000/features/DocBook/</ulink>
-
DocBook tutorial from Linux Weekly News.
</para>
</listitem>
<listitem>
<para>
<ulink
url="http://docbook.org/tdg/en/html/quickref.html">http://docbook.org/tdg/en/html/quickref.h
tml</ulink> - DocBook Quick Reference (v3.1 &amp; v4.1.2)
</para>
</listitem>
</itemizedlist>
</section> <!-- newauthorresources -->
General Writing Links and Style Guides
Guide to Grammar and Style
By Jack Lynch
http://newark.rutgers.edu/~jlynch/Writing/
Purdue's Online Writing Lab
http://owl.english.purdue.edu/
Chicago Manual of Style
http://www.chicagomanualofstyle.org/
Plain Language Resources
http://www.plainlanguagenetwork.org/Resources/
PLAIN's <ulink
url="http://www.blm.gov/nhp/NPR/pe_toc.html">Writing user-friendly
documents</ulink> is quite useful. It also gives before and after
writing samples. There's also a <ulink
url="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html">PlainTrain
writing tutorial</ulink>
<ulink url="http://www.useit.com/papers/webwriting/">Writing for the
Web</ulink>,
<ulink url="http://useit.com/alertbox/20030811.html">Information
pollution</ulink>, and
<ulink url="http://useit.com/alertbox/9703b.html">Be Succinct!
(Writing for the Web)</ulink>
Classic Writing Guides
George Orwell, "Politics and the English Language."
http://www.k-1.com/Orwell/index.cgi/work/essays/language.html
Strunk and White, <ulink url="http://www.bartleby.com/141/">The
Elements of Style</ulink>.
Thomas Pinney, <ulink
url="http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics">A
Short Handbook and Style Sheet.</ulink>
Technical Writing Links
http://www.techcomplus.com/tips.htm
Technical Writing Tutorial
http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html
Strategies to succeed in technical writing
http://www.school-for-champions.com/techwriting.htm
User Guides Online Tutorial
http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml
DMOZ Technical Writing Links
http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing/
techwr-L
http://www.raycomm.com/techwhirl/magazine
<ulink url="http://www.resort.com/~prime8/Orwell/patee.html"><citetitle>Politics and the English Language</cite
title></ulink>
an omnibus of links--scrounge for goodies:
http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html
<setion id="sg-references">
<title id="sg-references.title">References</title>
<para>
There are many guides to writing style available online.
Here is a brief list of some of the best:
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://www.resort.com/~prime8/Orwell/patee.html"><citetitle>Politics and the English Language</citetitl
e></ulink>.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://bartleby.com/141"><citetitle>The Elements of Style</citetitle></ulink>
</para>
</listitem>
<listitem>
<para>
FIXME: Please send the URL of your favorite resource on technical writing.
</para>
</listitem>
</itemizedlist>
</setion>
Related TLDP Documents:
Linux Documentation Project (LDP) FAQ
Rahul Sundaram
http://tldp.org/FAQ/LDP-FAQ/index.html
HOWTOs with LinuxDoc
http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html
CVS
<itemizedlist>
<listitem>
<para> <ulink
url="http://cvshome.org/docs/blandy.html">http://cvshome.org/docs/blandy.html</ulink>
</para>
</listitem>
<listitem>
<para> <ulink
url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://tldp.org/HOWTO/CVS-RCS-HOWTO.html">http://tldp.org/HOWTO/CVS-RCS-HOWTO.html</ulink>
</para>
</listitem>
</itemizedlist>
Graphical interface:
http://tldp.org/HOWTO/CVS-RCS-HOWTO-8.html

263
LDP/guide/docbook/LDP-Author-Guide/t-abook.xml Normal file
View File

@ -0,0 +1,263 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap2 SYSTEM "chap2.xml">
<!ENTITY chap3 SYSTEM "chap3.xml">
<!ENTITY chap4 SYSTEM "chap4.xml">
<!ENTITY chap5 SYSTEM "chap5.xml">
<!ENTITY app1 SYSTEM "app1.xml">
<!ENTITY app2 SYSTEM "app2.xml">
<!ENTITY gloss SYSTEM "gloss.xml">
]>
<book>
<bookinfo>
<title>Your title</title>
<subtitle>An optional subtitle</subtitle>
<authorgroup>
<author>
<firstname>Your given name</firstname>
<surname>Your last name</surname>
<affiliation>
<orgname>Your organization</orgname>
<address>
<email>you@your.domain</email>
</address>
</affiliation>
</author>
</authorgroup>
<edition>Optional version information</edition>
<keywordset>
<keyword>Add</keyword>
<keyword>as</keyword>
<keyword>many</keyword>
<keyword>keywords</keyword>
<keyword>as</keyword>
<keyword>you</keyword>
<keyword>want</keyword>
<keyword>.</keyword>
</keywordset>
</bookinfo>
<preface>
<title>Introduction</title>
<section id="intro_01">
<title>Why was this document written?</title>
<para>Some explanations.</para>
</section>
<section id="intro_02">
<title>Audience</title>
<para>Explain for whom it has been written.</para>
</section>
<section id="intro_03">
<title>New versions of this doc</title>
<para>Point to <ulink url="http://somewhere.org">the latest version</ulink> of this document.</para>
</section>
<section id="intro_04">
<title>Revision History</title>
<para>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2002-12-29</date>
<authorinitials>MG</authorinitials>
<revremark>Initial release for TLDP</revremark>
</revision>
<revision>
<revnumber>1.1</revnumber>
<date>2003-01-22</date>
<authorinitials>MG</authorinitials>
<revremark>Stuff you changed.</revremark>
</revision>
<revision>
<revnumber>1.2</revnumber>
<date>2003-02-28</date>
<authorinitials>MG</authorinitials>
<revremark>More stuff you changed.</revremark>
</revision>
</revhistory>
</para>
</section>
<section id="intro_05">
<title>Contributions</title>
<para>Thank people who helped realizing this doc.</para>
</section>
<section id="intro_06">
<title>Feedback</title>
<para>
Missing information, missing links, missing characters? Mail it to the
maintainer of this document: <address><email>you@your.domain</email></address>
</para>
</section>
<section id="intro_07">
<title>Copyright information</title>
<para>Copyright 2002 Your_first_name Your_last_name.
</para>
<para> Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or any later
version published by the Free Software Foundation; with the Invariant Sections
being the <quote>Copyright information</quote> and <quote>Feedback</quote>
sections, with no Front-Cover Texts and no Back-Cover Texts. A copy of the
license is included in <xref linkend="app4" /> entitled <quote>GNU Free
Documentation License</quote>.
</para>
<para>Read <ulink url="http://www.fsf.org/gnu/manifesto.html">The GNU Manifesto
</ulink> if you want to know why this license was chosen for this book.
</para>
<para>The author and publisher have made every effort in the preparation of this
book to ensure the accuracy of the information. However, the information
contained in this book is offfered without warranty, either express or implied.
Neither the author nor the publisher nor any dealer or distributor will be held
liable for any damages caused or alleged to be caused either directly or
indirectly by this book.
</para>
<para>The logos, trademarks and symbols used in this book are the properties of
their respective owners.
</para>
</section>
<section id="intro_08">
<title>What do you need?</title>
<para>List requirements: materials, knowledge.</para>
</section>
<section id="intro_09">
<title>Conventions used in this document</title>
<para>The following typographic and usage conventions occur in this text:
</para>
<table id="conventions" frame="all"><title>Typographic and usage conventions</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead>
<row><entry>Text type</entry><entry>Meaning</entry></row>
</thead>
<tbody>
<row>
<entry><quote>Quoted text</quote></entry>
<entry>Quotes from people, quoted computer output.</entry>
</row>
<row>
<entry><screen>terminal view</screen></entry>
<entry>Literal computer input and output captured from the terminal,
usually rendered with a light grey background.</entry>
</row>
<row>
<entry><command>command</command></entry>
<entry>Name of a command that can be entered on the command line.</entry>
</row>
<row>
<entry><varname>VARIABLE</varname></entry>
<entry>Name of a variable or pointer to content of a variable, as in
<varname>$VARNAME</varname>.</entry>
</row>
<row>
<entry><option>option</option></entry>
<entry>Option to a command, as in <quote>the <option>-a</option> option to the
<command>ls</command> command</quote>.</entry>
</row>
<row>
<entry><parameter>argument</parameter></entry>
<entry>Argument to a command, as in <quote>read
<command>man <parameter>ls</parameter></command></quote>.</entry>
</row>
<row>
<entry><cmdsynopsis><command>command <option>options</option>
<parameter>arguments</parameter></command></cmdsynopsis></entry>
<entry>Command synopsis or general usage, on a separated line.</entry>
</row>
<row>
<entry><filename>filename</filename></entry>
<entry>Name of a file or directory, for example <quote>Change to the
<filename>/usr/bin</filename> directory.</quote></entry>
</row>
<row>
<entry><keycap>Key</keycap></entry>
<entry>Keys to hit on the keyboard, such as <quote>type <keycap>Q</keycap>
to quit</quote>.</entry>
</row>
<row>
<entry><guibutton>Button</guibutton></entry>
<entry>Graphical button to click, like the <guibutton>OK</guibutton>
button.</entry>
</row>
<row>
<entry><menuchoice><guimenu>Menu</guimenu><guimenuitem>Choice</guimenuitem>
</menuchoice></entry>
<entry>Choice to select from a graphical menu, for instance: <quote>Select
<menuchoice><guimenu>Help</guimenu><guimenuitem>About Mozilla</guimenuitem>
</menuchoice> in your browser.</quote></entry>
</row>
<row>
<entry><emphasis>Terminology</emphasis></entry>
<entry>Important term or concept: <quote>The Linux <emphasis>kernel</emphasis>
is the heart of the system.</quote></entry>
</row>
<row>
<entry>See <xref linkend="chap_01" /></entry><entry>link to related subject
within this guide.</entry>
</row>
<row>
<entry><ulink url="http://tille.soti.org">The author</ulink></entry>
<entry>Clickable link to an external web resource.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="intro_10">
<title>Organization of this document</title>
<para>List chapters (and optionally, appendices) with a short content for each (only for longer docs).</para>
<itemizedlist>
<listitem><para><xref linkend="chap_01" />: short description.</para></listitem>
<listitem><para><xref linkend="chap_02" />: short description.</para></listitem>
<listitem><para><xref linkend="chap_03" />: short description.</para></listitem>
<listitem><para><xref linkend="chap_04" />: short description.</para></listitem>
<listitem><para><xref linkend="chap_05" />: short description.</para></listitem>
</itemizedlist>
</section>
</preface>
<toc></toc>
&chap1;
&chap2;
&chap3;
&chap4;
&chap5;
&app1;
&app2;
&app3;
&app4;
&gloss;
</book>

33
LDP/guide/docbook/LDP-Author-Guide/t-appendix.xml Normal file
View File

@ -0,0 +1,33 @@
<appendix id="app1">
<title>Appendix one title</title>
<abstract>
<para>Says what this appendix is about, for instance further info on the web.</para>
</abstract>
<sect1>
<title>further info</title>
<sect2><title>about this subject</title>
<itemizedlist>
<listitem><para><ulink url="http://useful.org" />: about this and that.</para></listitem>
<listitem><para><ulink url="http://related.org" />: about other related stuff.</para></listitem>
<listitem><para><ulink url="http://other.org" />: more stuff.</para></listitem>
</itemizedlist>
</sect2>
<sect2><title>about other subject</title>
<itemizedlist>
<listitem><para><ulink url="http://useful2.org" />: about this and that.</para></listitem>
<listitem><para><ulink url="http://related2.org" />: about other related stuff.</para></listitem>
<listitem><para><ulink url="http://other2.org" />: more stuff.</para></listitem> </itemizedlist>
</sect2>
</sect1>
</appendix>

55
LDP/guide/docbook/LDP-Author-Guide/t-chap1.xml Normal file
View File

@ -0,0 +1,55 @@
<?xml version='1.0' encoding='ISO-8859-1'?>
<chapter id="chap_01"><title>Title of first chapter</title>
<abstract>
<para>What we will do in this chapter:</para>
<para>
<itemizedlist>
<listitem><para>stuff</para></listitem>
<listitem><para>more stuff</para></listitem>
<listitem><para>talk about other stuff</para></listitem>
<listitem><para>play with stuff</para></listitem>
</itemizedlist>
</para>
</abstract>
<sect1 id="sect_01_01">
<title>Section1 title</title>
<sect2 id="sect_01_01_01"><title>Section2 title</title>
<para>Blahblah</para>
<para>More blabla</para>
</sect2>
<sect2 id="sect_01_01_02"><title>Section2 title</title>
<para>Blahblah</para>
<para>More blabla</para>
</sect2>
<sect2 id="sect_01_01_03">
<title>Section2 title</title>
<para>Blahblah</para>
<para>More blabla</para>
</sect2>
</sect1>
<sect1 id="sect_01_02">
<title>Section1 title</title>
<sect2 id="sect_01_02_01">
<title>Section2 title</title>
<para>Blahblah</para>
<para>More blabla</para>
</sect2>
</sect2>
<sect2 id="sect_01_02_02">
<title>Section2 title</title>
<para>Blahblah</para>
<para>More blabla</para>
</sect2>
</sect1>
</chapter>

92
LDP/guide/docbook/LDP-Author-Guide/t-chap2.xml Normal file
View File

@ -0,0 +1,92 @@
<?xml version='1.0' encoding='ISO-8859-1'?>
<chapter id="chap_02"><title>Title of second chapter</title>
<abstract>
<para>What we will do in this chapter:</para>
<para>
<itemizedlist>
<listitem><para>stuff</para></listitem>
<listitem><para>more stuff</para></listitem>
<listitem><para>talk about other stuff</para></listitem>
<listitem><para>play with stuff</para></listitem>
</itemizedlist>
</para>
</abstract>
<sect1 id="sect_02_01">
<title>Section1 title</title>
<sect2 id="sect_02_01_01"><title>Section2 title</title>
<sect3 id="sect_02_01_01_01"><title>Section3 title</title>
<para>Blahblah</para>
<orderedlist>
<listitem><para>Summing up a few things</para></listitem>
<listitem><para>in a list</para></listitem>
<listitem><para>where items are numbered</para></listitem>
</orderedlist>
<para>More blabla</para>
</sect3>
<sect3 id="sect_02_01_01_01"><title>Section3 title</title>
<para>Blahblah</para>
<itemizedlist>
<listitem><para>Summing up a few things</para></listitem>
<listitem><para>in a list</para></listitem>
<listitem><para>where items are not numbered</para></listitem>
</itemizedlist>
<para>More blabla</para>
</sect3>
</sect2>
<sect2 id="sect_02_01_02"><title>Section2 title</title>
<para>Showing a picture in text:</para>
<figure><title></title>
<mediaobject>
<imageobject>
<imagedata fileref="your_images_dir/image.eps" format="EPS"></imagedata></imageobject>
<imageobject>
<imagedata fileref="your_images_dir/image.png" format="PNG"></imagedata></imageobject>
</mediaobject>
</figure>
<para>PNG is for on-line browsing, EPS for printing. <command>gimp</command> and/or <command>convert</command> will do the trick, starting from about any source format.</para>
</sect2>
</sect1>
<sect1 id="sect_02_02">
<title>Section1 title</title>
<sect2 id="sect_02_02_01">
<title>Section2 title</title>
<para>This is a table with two colums:</para>
<table id="tab_02_01" frame="all"><title>Table title</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<thead>
<row><entry>first colum header</entry><entry>second colum header</entry></row>
</thead>
<tbody>
<row><entry>item</entry><entry>meaning</entry></row>
<row><entry>item</entry><entry>meaning</entry></row>
<row><entry>item</entry><entry>meaning</entry></row>
</tbody>
</tgroup>
</table>
</sect2>
</sect2>
<sect2 id="sect_02_02_02">
<title>Section2 title</title>
<para>This is a link to the first section of the first chapter: <xref linkend="sect_01_01" />.</para>
<para>This is an external link: <ulink url="http://www.somewhere.org" />.</para>
<para>This is also <ulink url="http://www.somewhere.org">an external link</ulink>, only here you don't see the URL.</para>
</sect2>
</sect1>
</chapter>

86
LDP/guide/docbook/LDP-Author-Guide/t-glossary.xml Normal file
View File

@ -0,0 +1,86 @@
<glossary id="glossary"><?dbhtml filename="gloss.html"?>
<title>Glossary</title>
<abstract>
<para>This is a glossary.</para>
</abstract>
<glossdiv><title>A</title>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv><title>B</title>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv><title>C</title>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
<glossentry id="entryname">
<glossterm>entryname</glossterm>
<glossdef>
<para>definition</para>
</glossdef>
</glossentry>
</glossdiv>
etc.
</glossary>

15
LDP/guide/docbook/LDP-Author-Guide/thankyous.xml Normal file
View File

@ -0,0 +1,15 @@
<section id="acknowledgements">
<title>Acknowledgments and Thanks</title>
<para>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
<email>discuss@en.tldp.org</email> list. Some
sections I got from the <ulink
url="http://www.tldp.org/HOWTO/">HOWTO Index</ulink> and the
sgmltools documentation. The sections on network access to CVS
was partially written by Sergiusz Pawlowicz
(<email>ser@metalab.unc.edu</email>). Sections on DocBook
were written by Jorge Godoy
(<email>godoy@conectiva.com</email>). A great deal of thanks
to both of them for their help.</para>
</section>

40
LDP/guide/docbook/LDP-Author-Guide/tldp.xml Normal file
View File

@ -0,0 +1,40 @@
<section id="theldp">
<title>About The LDP</title>
<para>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 <ulink
url="http://www.tldp.org/HOWTO/Printing-HOWTO.html">Printing
HOWTO</ulink>. If you want to do find out if your Ethernet card
works with Linux, grab the <ulink
url="http://www.tldp.org/HOWTO/Ethernet-HOWTO.html">Ethernet
HOWTO</ulink>, and so on. At first, many of these works were in
text or HTML. As time went on, there had to be a better way of
managing these documents. One that would let you read it from a
web page, a text file on a CD-ROM, or even your hand-held
PDA. The answer, as it turns out, is DocBook.</para>
<blockquote>
<attribution>LDP Manifesto located at <ulink
url="http://www.tldp.org/manifesto.html">http://www.tldp.org/manifesto.html</ulink></attribution>
<para>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.</para>
</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/">http://www.tldp.org/"</ulink>.
This Guide focuses primarily on how to write your own HOWTOs for
submission to the LDP.
</para>
</section>