mirror of https://github.com/tLDP/LDP
cold storage of the old SGML files; may remove at a later time
This commit is contained in:
gferg
parent
4b876825d3
commit
829d95cf88
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,93 @@
|
|||
#!/bin/bash
|
||||
#
|
||||
# Compile DocBook documents into several output formats.
|
||||
#
|
||||
# Godoy.
|
||||
# 19991230 - Initial release.
|
||||
# 20000117 - Placed the options using "case" and parameters passed
|
||||
# via command line. The pages on the Zope are already updated.
|
||||
# --- Removed to public version (/home/ldp).
|
||||
# 20000120 - Placed the call to use the books.dtd.
|
||||
# 20000126 - Placed the commands for the index generation.
|
||||
#
|
||||
|
||||
# If the jade is already installed, disconsider the line bellow.
|
||||
<envar>JADE</envar>=/usr/bin/jade
|
||||
|
||||
# If the jade package is already installed, disconsider the line bellow.
|
||||
# <envar>JADE</envar>=/usr/bin/openjade
|
||||
|
||||
<envar>DOCUMENT</envar>=<envar>$1</envar>
|
||||
<command>shift</command> 1
|
||||
<envar>TYPE</envar>=<envar>$1</envar>
|
||||
|
||||
<command>.</command> <filename>~/.bash_profile</filename>
|
||||
<command>.</command> <filename>~/.bashrc</filename>
|
||||
|
||||
<command>case</command> <envar>$TYPE</envar> in
|
||||
html)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <literal>*.htm</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <literal>*.html</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter class="option">-o</parameter> <filename>index.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>index.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-i</parameter> <literal>html</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/livros.dsl</filename><literal>#html</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
;;
|
||||
rtf)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.rtf</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter class="option">-o</parameter> <filename>index.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>rtf</literal> <parameter class="option">-V</parameter> <literal>rtf-backend</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/books.dsl</filename><literal>#print</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
;;
|
||||
xml)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.xml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter class="option">-o</parameter> <filename>index.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-i</parameter> <literal>xml</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/xsl/docbook/html/docbook.xsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
;;
|
||||
tex)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter class="option">-o</parameter> <filename>indice.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>tex</literal> <parameter class="option">-V</parameter> <literal>tex-backend</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/livros.dsl</filename><literal>#print</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
;;
|
||||
dvi)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.dvi</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter>-o</parameter> <filename>indice.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>tex</literal> <parameter class="option">-V</parameter> <literal>tex-backend</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/livros.dsl</filename><literal>#print</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>jadetex</command> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
;;
|
||||
mirror)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.dvi</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.mirror.ps</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter>-o</parameter> <filename>indice.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>tex</literal> <parameter class="option">-V</parameter> <literal>tex-backend</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/livros.dsl</filename><literal>#print</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>jadetex</command> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>dvips</command> <parameter>-h</parameter> <filename>/home/ldp/estilos/skel/mirr.hd</filename> <parameter class="option">-O</parameter> <literal>1.5cm,3cm</literal> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.dvi</literal> <parameter class="option">-o</parameter> <envar>$DOCUMENT</envar><literal>.mirror.ps</literal>
|
||||
;;
|
||||
ps)
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.dvi</literal>
|
||||
<command>rm</command> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.ps</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-N</parameter> <parameter>-o</parameter> <filename>indice.sgml</filename>
|
||||
<command>jade</command> <parameter class="option">-t</parameter> <literal>sgml</literal> <parameter class="option">-V</parameter> <literal>html-index</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl</filename> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>perl</command> <filename>/home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl</filename> <parameter class="option">-o</parameter> <filename>indice.sgml</filename> <filename>HTML.index</filename>
|
||||
<envar>$JADE</envar> <parameter class="option">-t</parameter> <literal>tex</literal> <parameter class="option">-V</parameter> <literal>tex-backend</literal> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl</filename> <parameter class="option">-d</parameter> <filename>/home/ldp/SGML/conectiva/livros.dsl</filename><literal>#print</literal> <envar>$DOCUMENT</envar><literal>.sgml</literal>
|
||||
<command>jadetex</command> <envar>$DOCUMENT</envar><literal>.tex</literal>
|
||||
<command>dvips</command> <parameter class="option">-The</parameter> <literal>1.5cm,3cm</literal> <parameter class="option">-f</parameter> <envar>$DOCUMENT</envar><literal>.dvi</literal> <parameter class="option">-o</parameter> <envar>$DOCUMENT</envar><literal>.ps</literal>
|
||||
;;
|
||||
*)
|
||||
<command>echo</command> <computeroutput>"How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}"</computeroutput>
|
||||
<command>exit</command> <returnvalue>1</returnvalue>
|
||||
<command>esac</command>
|
||||
|
||||
<command>exit</command> <returnvalue>0</returnvalue>
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
<!-- <!doctype section PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> -->
|
||||
|
||||
<section id="conventions"><?dbhtml filename="conventions.html">
|
||||
<title>Documents</title>
|
||||
|
||||
<indexterm zone="conventions">
|
||||
<primary>conventions</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>This document uses the following conventions<footnote>
|
||||
<para>Please, take a look at the <ulink
|
||||
url="http://cvsweb.linuxdoc.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/">
|
||||
source</ulink> to see how to get
|
||||
similar results on your documents. You should also remember that
|
||||
the way this appears to you depends on the format you're reading
|
||||
this document: online appearance is slightly different from the
|
||||
PostScript or PDF ones.</para></footnote>:</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Descriptions</entry>
|
||||
<entry>Appearance</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>Warnings</entry>
|
||||
<entry><caution>
|
||||
<para>Warnings.</para>
|
||||
</caution></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Hint</entry>
|
||||
<entry><tip>
|
||||
<para>Hint.</para>
|
||||
</tip></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Notes</entry>
|
||||
<entry><note>
|
||||
<para>Note.</para>
|
||||
</note></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Information requiring special attention</entry>
|
||||
<entry><warning>
|
||||
<para>Warning.</para>
|
||||
</warning></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>File Names</entry>
|
||||
<entry><filename>file.extension</filename></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Directory Names</entry>
|
||||
<entry><filename class="directory">directory</filename></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Commands to be typed</entry>
|
||||
<entry><command>command</command></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Applications Names</entry>
|
||||
<entry><application>application</application></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><foreignphrase>Prompt</foreignphrase> of users command under bash shell</entry>
|
||||
<entry>bash$</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><foreignphrase>Prompt</foreignphrase> of root users command under bash shell</entry>
|
||||
<entry>bash#</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><foreignphrase>Prompt</foreignphrase> of user command under tcsh shell</entry>
|
||||
<entry>tcsh$</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Environment Variables</entry>
|
||||
<entry><envar>VARIABLE</envar></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Emphasized word</entry>
|
||||
<entry><emphasis>word</emphasis></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Code Example</entry>
|
||||
<entry><programlisting><sgmltag class="starttag">para</sgmltag>Beginning and end of paragraph<sgmltag class="endtag">para</sgmltag></programlisting></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
</section>
|
||||
|
|
@ -0,0 +1,165 @@
|
|||
<section id="cvs">
|
||||
<title> CVS </title>
|
||||
<para> The LDP is in the process of 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 if you 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> 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> 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 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://www.sourcegear.com/CVS/Docs/blandy">http://www.sourcegear.com/CVS/Docs/blandy</ulink>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para> <ulink
|
||||
url="https://wroclaw.art.pl/~ser/docs/cvs.html">https://wroclaw.art.pl/~ser/docs/cvs.html</ulink></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<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.)
|
||||
created as subdirectories of that. </para>
|
||||
<para> You will need to create a hashed password and userid for
|
||||
your account. The hashed password allows you to send an
|
||||
encrypted password to the CVS group without them needing to know
|
||||
your password. You can do this with the following command, from
|
||||
bash (or sh): </para>
|
||||
|
||||
<screen format="linespecific">
|
||||
<prompt>bash$</prompt> <command>echo your_password | perl -e "print crypt(<>,\
|
||||
join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\""</command>
|
||||
</screen>
|
||||
|
||||
<para>Take the output of this command, and send it with your
|
||||
proposed userid to
|
||||
<email>cvsadmin@cvslist.linuxdoc.org</email>. 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
|
||||
and make sure everything is set up properly: </para>
|
||||
|
||||
<screen format="linespecific">
|
||||
<prompt>bash$</prompt> <command>export CVSROOT=:pserver:<replaceable>your_userid</replaceable>@cvs.linuxdoc.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 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 LinuxDoc repository with this command: </para>
|
||||
|
||||
<screen>
|
||||
<prompt>bash$</prompt> <command>cvs get LDP</command>
|
||||
</screen>
|
||||
|
||||
<para> Or you can get the SGML 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="othercvsnotes">
|
||||
<title> Other CVS repository notes </title>
|
||||
|
||||
<section id="anoncvs">
|
||||
<title> Anonymous CVS access </title>
|
||||
<para> Anonymous CVS access is available for those who do not
|
||||
require an account (such as those wishing to publish LDP
|
||||
documents). This repository is read-only: </para>
|
||||
|
||||
<screen>
|
||||
<prompt>bash$</prompt> <command>cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login</command>
|
||||
</screen>
|
||||
|
||||
<para> As a password, use cvs. You can then get LinuxDoc
|
||||
modules as above. Note that changes to the anoncvs site may be
|
||||
a half an hour behind the main site. </para>
|
||||
</section>
|
||||
|
||||
<section id="cvsweb">
|
||||
<title> CVS Files via web </title>
|
||||
<para> You can access the CVS repository via the web at <ulink
|
||||
url="http://cvsweb.linuxdoc.org/index.cgi/LDP">http://cvsweb.linuxdoc.org/index.cgi/LDP</ulink>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<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>
|
||||
|
||||
<section id="updatefiles">
|
||||
<title> Updating files and CVS </title>
|
||||
<para> CVS has a special tag, <emphasis>$Id$</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
|
||||
"comment" YOUR-HOWTO.sgml</command>. The -m
|
||||
"comment" 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
|
||||
ldp-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. E-mail should be sent to
|
||||
<email>ldp-submit@lists.linuxdoc.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>
|
||||
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
||||
<!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
|
||||
<!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
|
||||
]>
|
||||
|
||||
<style-sheet>
|
||||
<style-specification use="html">
|
||||
<style-specification-body>
|
||||
|
||||
; Includes a summary at the beginning of an item.
|
||||
(define %generate-article-toc% #t)
|
||||
|
||||
</style-specification-body>
|
||||
</style-specification>
|
||||
<style-specification use="print">
|
||||
<style-specification-body>
|
||||
|
||||
; Includes a summary at the beginning of an item.
|
||||
(define %generate-article-toc% #t)
|
||||
|
||||
</style-specification-body>
|
||||
</style-specification>
|
||||
<external-specification id="html" document="html-docbook">
|
||||
<external-specification id="print" document="print-docbook">
|
||||
</style-sheet>
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
<article class="whitepaper" id="using -docbook" lang="pt-br"><?dbhtml filename="using-docbook.html">
|
||||
|
||||
<artheader>
|
||||
<title>Como-Fazer DocBook</title>
|
||||
<author>
|
||||
<firstname>Jorge</firstname>
|
||||
<othername>Luiz</othername>
|
||||
<surname>Godoy</surname>
|
||||
<othername>Filho</othername>
|
||||
<affiliation>
|
||||
<orgname><ulink url="http://www.conectiva.com">Conectiva S.A.</ulink></orgname>
|
||||
<orgdiv>Publishing Departmentt;/orgdiv>
|
||||
<address><email>godoy@conectiva.com</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.0</revnumber>
|
||||
<date>27 de janeiro de 2000</date>
|
||||
<authorinitials>godoy</authorinitials>
|
||||
<revremark>Versão inicial.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<legalnotice>
|
||||
<para>This document can be freely translated and distributed. It's released
|
||||
under the LDP License.</para>
|
||||
</legalnotice>
|
||||
|
||||
<keywordset>
|
||||
<keyword>SGML</keyword>
|
||||
<keyword>DocBook</keyword>
|
||||
<keyword>DTD</keyword>
|
||||
<keyword>XML</keyword>
|
||||
<keyword>catalogs</keyword>
|
||||
<keyword>documents</keyword>
|
||||
<keyword>Publishingdlt;/keyword>
|
||||
<keyword>Conectiva</keyword>
|
||||
<keyword>configuration</keyword>
|
||||
<keyword>use</keyword>
|
||||
<keyword>tools</keyword>
|
||||
<keyword>HOWTO</keyword>
|
||||
</keywordset>
|
||||
|
||||
</artheader>
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
<book id="network-systems-administration><?dbhtml filename="html/networkadm.html">
|
||||
<bookinfo>
|
||||
<author>
|
||||
<firstname>Jorge</firstname>
|
||||
<surname>Godoy</surname>
|
||||
<affiliation>
|
||||
<orgname>&conectivasa;</orgname>
|
||||
<orgdiv>Publishing Departmentlt;/orgdiv>
|
||||
<address role="email">godoy@conectiva.com.br</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<editor>
|
||||
<firstname>Jorge</firstname>
|
||||
<surname>Godoy</surname>
|
||||
</editor>
|
||||
<copyright>
|
||||
<year>2000</year>
|
||||
<holder>&conectiva;</holder>
|
||||
</copyright>
|
||||
<title>Network and Systems Administration Using Linux</title>
|
||||
<legalnotice>
|
||||
<para>The contents of this book can be freely used and distributed
|
||||
as far as the source is mentioned as a reference that is, its bibliograph.</para>
|
||||
</legalnotice>
|
||||
<edition>INTERNAL Edition for comments</edition>
|
||||
<publisher>
|
||||
<publishername>Conectiva S/A</publishername>
|
||||
<address><city>Curitiba</city><country>Brasil</country></address>
|
||||
</publisher>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>1.0</revnumber>
|
||||
<date>Maio de 2000</date>
|
||||
<revremark>First Edition</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
<isbn>ISBN#</isbn>
|
||||
<pubdate>$Data: 1999/12/30 $</pubdate>
|
||||
</bookinfo>
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
<table frame="all">
|
||||
<title>Sample Table</title>
|
||||
<tgroup cols="5">
|
||||
<colspec colname="column1">
|
||||
<colspec colname="column2">
|
||||
<colspec colname="column3">
|
||||
<colspec colnum="5" colname="column5">
|
||||
<spanspec namest="column1" nameend="column2" spanname="span-horiz" align="center">
|
||||
<spanspec namest="column2" nameend="column3" spanname="span-horiz-vert" align="center">
|
||||
<thead>
|
||||
<row>
|
||||
<entry spanname="span-horiz">
|
||||
<foreignphrase>Span</foreignphrase> horizontal
|
||||
</entry>
|
||||
<entry>Heading 2</entry>
|
||||
<entry>Heading 3</entry>
|
||||
<entry>Heading 4</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tfoot>
|
||||
<row>
|
||||
<entry>Footing 1</entry>
|
||||
<entry>Footing 2</entry>
|
||||
<entry>Footing 3</entry>
|
||||
<entry>Footing 4</entry>
|
||||
<entry>Footing 5</entry>
|
||||
</row>
|
||||
</tfoot>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>Data11</entry>
|
||||
<entry>Data12</entry>
|
||||
<entry>Data13</entry>
|
||||
<entry>Data14</entry>
|
||||
<entry>Data15</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Data21</entry>
|
||||
<entry>Data22</entry>
|
||||
<entry>Data23</entry>
|
||||
<entry>Data24</entry>
|
||||
<entry morerows="1" valign="middle">
|
||||
<foreignphrase>Span</foreignphrase> vertical
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Data31</entry>
|
||||
<entry spanname="span-horiz-vert" morerows="1" valign="bottom">
|
||||
<foreignphrase>Span</foreignphrase> duplo
|
||||
</entry>
|
||||
<entry>Data34</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Data41</entry>
|
||||
<entry>Data44</entry>
|
||||
<entry>Data45</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
|
@ -0,0 +1,155 @@
|
|||
<!-- <!doctype glossary PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> -->
|
||||
|
||||
<glossary id="glossary"><?dbhtml filename="glossary.html">
|
||||
<title>Glossary</title>
|
||||
<glossentry>
|
||||
<glossterm>attribute</glossterm>
|
||||
<glossdef>
|
||||
<para>One attributte makes available extra information regarding the
|
||||
element on which it appears. The attributes always appear as a
|
||||
name-value pair on the initialization pointers. Example of an
|
||||
attribute is <parameter
|
||||
class="option">id="identification"</parameter>, which gives to the
|
||||
attribute <parameter class="option">id</parameter> the value
|
||||
<parameter class="option">identification</parameter>.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>Document Type Definition
|
||||
(<acronym>DTD</acronym>)</glossterm>
|
||||
<glossdef>
|
||||
<para> Group of statements that define element names and their attributes
|
||||
specifying the rules for combinations and sequences. It's the
|
||||
<acronym>DTD</acronym> that define which elements can or cannot
|
||||
be inserted in the context on which the cursor is in.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm><acronym>DSSSL</acronym></glossterm>
|
||||
<glossdef>
|
||||
<para><acronym>DSSSL</acronym> stands for Document Style Semantics and
|
||||
Specification Language. It's an <acronym>ISO</acronym> standard
|
||||
(ISO/IEC 10179:1996). The <acronym>DSSSL</acronym> standard is
|
||||
internationally used as a language for documents stylesheets pages for
|
||||
<acronym>SGML</acronym>.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>element</glossterm>
|
||||
<glossdef>
|
||||
<para>The elements define the hierarchical structure of a document. The
|
||||
majority of elements have opening and closing pointers. Among 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>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>entity</glossterm>
|
||||
<glossdef>
|
||||
<para>Entity is a name designated for some part of data so that it can be
|
||||
referenced by a name. These designations are made by a statement and
|
||||
the stored data might hold from simple characters to chapters or set
|
||||
of statements of a <acronym>DTD</acronym>. There are parameter
|
||||
entities generic, external, internal and of data on
|
||||
the<acronym>SGML</acronym>.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>external entity</glossterm>
|
||||
<glossdef>
|
||||
<para>An external entity points to an external document. External entities
|
||||
are used to include texts on certain locations of a
|
||||
<acronym>SGML</acronym> document. Suggestions for its use includes
|
||||
sample screens, legal notes and chapters.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>generic entities</glossterm>
|
||||
<glossdef>
|
||||
<para>An entity referenced by a name which starts with
|
||||
<quote>&</quote> and ends with semicolon is a generic
|
||||
entity. Most of the time these type of entities are used on the
|
||||
document and not on the <acronym>DTD</acronym>. There are two types
|
||||
of entities: external and internal which refers either to special
|
||||
characters or to text objects such as repeated sentences, names or
|
||||
chapters.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>internal entity</glossterm>
|
||||
<glossdef>
|
||||
<para>An internal entity refers to part of the text and is often used
|
||||
as a schortcut for portions of a text frequently repeated.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>parameter entity</glossterm>
|
||||
<glossdef>
|
||||
<para>An entity often used on the <acronym>DTD</acronym>. The entity's
|
||||
name starts with a percent sign (%) and it ends with a
|
||||
semicolon.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>float</glossterm>
|
||||
<glossdef>
|
||||
<para>Objects such as side bars, pictures, tables and charts are called
|
||||
floats when they don't have a fixed placement on the text. For a
|
||||
printed text, the chart can appear either at the top or at the
|
||||
bottom of the page. It can also be placed on the next page if that's
|
||||
too large.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>processing instruction</glossterm>
|
||||
<glossdef>
|
||||
<para>A processing instruction is a command passed to the document
|
||||
formatting tool. It starts with <quote><?</quote>. A sample
|
||||
of instruction is used on this document for the generated file's
|
||||
choice when the file is converted to
|
||||
<acronym>HTML</acronym>: <sgmltag class="starttag">?dbhtml
|
||||
filename="file.html"</sgmltag></para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm><acronym>SGML</acronym></glossterm>
|
||||
<glossdef>
|
||||
<para><foreignphrase>Standard Generalized Markup
|
||||
Language</foreignphrase>.
|
||||
It's also an international standard (<acronym>ISO</acronym>8879) which
|
||||
specifies rules for the creation of electronic documents in markup
|
||||
systems regardless the work platform used.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm>tag</glossterm>
|
||||
<glossdef>
|
||||
<para>An <acronym>SGML</acronym> element bounded by the marks
|
||||
<quote><</quote> and <quote>></quote>. Tags are used
|
||||
to mark the semantic or the structure of a document. A sample
|
||||
is the tag <emphasis><sgmltag
|
||||
class="starttag">title</sgmltag></emphasis> to mark the beginning
|
||||
of a title.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm><acronym>XML</acronym></glossterm>
|
||||
<glossdef>
|
||||
<para>eXtensible Markup Language. A subproduct of <acronym>SGML</acronym>
|
||||
created specifically for Internet use.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry>
|
||||
<glossterm><acronym>XSL</acronym></glossterm>
|
||||
<glossdef>
|
||||
<para><acronym>XML</acronym> Style
|
||||
Language. XSL is to a <acronym>XML</acronym> document what a
|
||||
<acronym>DSSSL</acronym> style is for a <acronym>SGML</acronym>
|
||||
document. In fact, the style is a document
|
||||
<acronym>XML</acronym>.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
</glossary>
|
||||
|
|
@ -0,0 +1,444 @@
|
|||
|
||||
<chapter id="styleguide">
|
||||
<title>LDP Style Guide</title>
|
||||
|
||||
<sect1 id="sg-subject">
|
||||
<title>Deciding on a Subject</title>
|
||||
|
||||
<para>
|
||||
Before you begin writing a HOWTO, it is essential that
|
||||
you determine what subject area you will cover. It is best if the
|
||||
subject area is:
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title>Not too broad, and not too narrow.</title>
|
||||
<para>
|
||||
Try to cover too much information,
|
||||
and you may sacrifice depth. It is better to cover a
|
||||
small subject area fully than to cover a large subject
|
||||
area poorly.
|
||||
Linux tools are known for doing exactly one
|
||||
thing and doing that one thing <emphasis>well</emphasis>.
|
||||
Similarly, your HOWTO should cover one subject and cover it
|
||||
<emphasis>well</emphasis>.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<para>
|
||||
If your subject matter is very small, it might be better
|
||||
included as part of another HOWTO. This makes it easier
|
||||
for readers to find the HOWTO they need. Search the LDP repository
|
||||
for HOWTOs on related topics, and see if you could place
|
||||
your information in an existing HOWTO.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
How much is too much?
|
||||
How little is too little? That depends on the subject
|
||||
you chose, your mastery of that subject, and many other
|
||||
factors. Just keep this admonition in mind, and use good judgement.
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title>Clearly defined.</title>
|
||||
|
||||
<para>
|
||||
Know before you begin exactly where the boundaries of your
|
||||
subject area lie. You should not cover the same ground as another
|
||||
HOWTO, and you should try not to leave gaps between your HOWTO
|
||||
and related HOWTOs, either.
|
||||
</para>
|
||||
</formalpara>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title>Undocumented</title>
|
||||
|
||||
<para>
|
||||
Before writing on a particular subject, check other HOWTOs at the LDP,
|
||||
and see if the topic is already documented. If it is, refer to the
|
||||
other HOWTO instead of rewriting documentation that already exists.
|
||||
Don't reinvent the wheel.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
<para>
|
||||
If the HOWTO already in place is insufficient, or needs updating,
|
||||
contact the author and offer to help. LDP authors are usually nice folks.
|
||||
After all, they put in their own valuable time to help people they
|
||||
don't even know. And, they appreciate your help. But, please, don't
|
||||
duplicate work. It causes confusion for everyone.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title>Pre-approved by the LDP</title>
|
||||
|
||||
<para>
|
||||
Before you proceed with your HOWTO, post to the ldp-discuss list
|
||||
and get some feedback from other LDP volunteers. Checking with the
|
||||
list <emphasis>before</emphasis> you begin can save you headaches
|
||||
<emphasis>later</emphasis>.
|
||||
The author speaks from experience.
|
||||
</para>
|
||||
|
||||
</formalpara>
|
||||
|
||||
<para>
|
||||
It is a really good idea to join the ldp-discuss list, and follow
|
||||
it regularly, even if you never post. It's a good way to stay current
|
||||
on the activities, needs, and policies of the LDP. Although the LDP
|
||||
volunteers are here to assist you, it is ultimately your
|
||||
responsibility to learn these policies, and to follow them.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sg-outline">
|
||||
<title>Developing an Outline</title>
|
||||
|
||||
<para>
|
||||
Before you actually begin writing, prepare an outline.
|
||||
An outline will help you get a clear picture of the subject matter,
|
||||
and allow you to concentrate on one small part of the HOWTO
|
||||
at a time.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Unless your HOWTO is exceptionally small, your outline will probably
|
||||
be multilevel.
|
||||
When developing a multilevel outline, the top level should contain general
|
||||
subject areas, and sub-headings should be more detailed and specific.
|
||||
Look at each level of your outline independently,
|
||||
and make sure it covers all key areas of the subject matter. Sub-headings
|
||||
should cover all key areas of the heading under which they fall.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Each item in your outline should logically follow the item before it,
|
||||
and lead into the item it precedes. For example, a HOWTO about a particular
|
||||
program shouldn't have a section on <emphasis>configuration</emphasis>
|
||||
before one on <emphasis>installation</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you are comfortable with your outline, look over it once more,
|
||||
with a critical eye. Have you covered every relevant topic in
|
||||
sufficient detail? Have you wandered beyond the scope of the HOWTO?
|
||||
You might want to show it to someone else, and ask for feedback.
|
||||
It's much easier to reorganize your
|
||||
HOWTO at the outline stage than it will be later. Consider submitting
|
||||
the outline to the ldp-discuss list for more feedback.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
You might have noticed a theme developing here.
|
||||
Just like Free software, Free documentation is best when you
|
||||
<quote>release early, release often.</quote> The ldp-discuss list includes
|
||||
many experienced LDP authors, and you would be wise to seek their
|
||||
advice when making decisions about your HOWTO.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Remember Linus' Law:
|
||||
</para>
|
||||
|
||||
<blockquote><attribution>Eric S. Raymond</attribution>
|
||||
<para>
|
||||
<quote>Given enough eyeballs, all [typos] are shallow.</quote>
|
||||
</para>
|
||||
</blockquote>
|
||||
|
||||
<para>
|
||||
(With apologies to Mr. Raymond.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
FIXME: Need a reference to the "standard" HOWTO layout, for
|
||||
topic areas such as Credits, License, Copyright, etc., etc.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sg-writingstyle">
|
||||
<title>Writing the Text</title>
|
||||
|
||||
<para>
|
||||
At this point, your HOWTO has been organized, and bits of raw information
|
||||
have been collected, documented, and inserted into the outline.
|
||||
Good news: You're past the
|
||||
midpoint; it's all downhill from here.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Your next challenge is to
|
||||
massage all of the raw data you've collected into a readable,
|
||||
entertaining, and understandable whole.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It has taken quite a bit of work to get to the point where you can
|
||||
actually start writing, hasn't it? Well, the hard work begins to pay
|
||||
off for you now. At this stage, you can begin to really use your
|
||||
imagination and creativity to communicate this heap of dry,
|
||||
boring information in
|
||||
your own unique way.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is beyond the scope of this document to provide a comprehensive
|
||||
guide to effective writing, so I won't try to go beyond the basics.
|
||||
|
||||
In the <quote><link linkend="sg-references" endterm="sg-references.title"></link></quote>
|
||||
section, you will find a list of resources that cover the subject
|
||||
better than this guide could hope to. Consult them, and follow their
|
||||
advice.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For starters, here is some good advice from
|
||||
<ulink url="http://www.resort.com/~prime8/Orwell/patee.html"><citetitle>Politics and the English Language</citetitle></ulink>:
|
||||
</para>
|
||||
|
||||
<blockquote>
|
||||
<attribution>George Orwell</attribution>
|
||||
|
||||
<para>
|
||||
A scrupulous writer, in every sentence that he writes, will ask himself
|
||||
at least four questions, thus:
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
What am I trying to say?
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
What words will express it?
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
What image or idiom will make it clearer?
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Is this image fresh enough to have an effect?
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
And he will probably ask himself two more:
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Could I put it more shortly?
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Have I said anything that is avoidably ugly?
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
...One can often be in doubt about the effect of a word or phrase,
|
||||
and one needs rules that one can rely on when instinct fails.
|
||||
I think the following rules will cover most cases:
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Never use a long word where a short one will do.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
If it is possible to cut a word out, always cut it out.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Never use the passive where you can use the active.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Never use a foreign phrase, a scientific word,
|
||||
or a jargon word if you can think
|
||||
of an everyday English equivalent.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Break any of these rules sooner than say anything outright barbarous.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<para>
|
||||
And, from a purely stylistic point of view, I believe that
|
||||
the first-person perspective of many HOWTOs adds to their charm,
|
||||
an attribute most documentation in other forms sorely lacks.
|
||||
Don't be afraid to speak for yourself, use the word <quote>I</quote>,
|
||||
or describe personal experiences and opinions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If it hasn't become painfully obvious yet, the underlying principle
|
||||
of all these suggestions is simplicity.
|
||||
Your readers are already struggling with new concepts, so don't
|
||||
make them struggle to understand your language.
|
||||
Remember the <acronym>KISS</acronym> principle: Keep It Simple, Stupid!
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sg-editing">
|
||||
<title>Editing and Proofing the Text</title>
|
||||
|
||||
<para>
|
||||
Once you've written the text of your HOWTO, it is time to polish
|
||||
and refine it. Good editing can make the difference between a good
|
||||
HOWTO and a great one.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
One of the goals of editing is to remove extraneous material that
|
||||
has crept its way into your document.
|
||||
You should go through your HOWTO carefully, and ruthlessly
|
||||
delete anything that doesn't contribute to the reader's understanding
|
||||
of the subject matter. It is natural for writers to go off on tangents
|
||||
while in the process of writing. This is the time to correct that.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When editing and proofing your work, you must check for obvious mistakes,
|
||||
such as spelling errors and typos.
|
||||
However, you should check for deeper, but
|
||||
less obvious errors as well, such as <quote>holes</quote> in the
|
||||
information. Make sure that the contents of every section match
|
||||
the title of that section precisely.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you are completely satisfied with the quality and accuracy of
|
||||
your work, forward it to someone else for third-party proofing.
|
||||
You will be too close to the work to see fundamental flaws.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In a sense, editing is like code review in software development.
|
||||
Having a programmer review their own code doesn't make much sense,
|
||||
does it? Why does having a writer edit their own document make
|
||||
any more sense?
|
||||
So, recruit a friend, or write the
|
||||
ldp-discuss list to find a volunteer to proofread before submitting
|
||||
your HOWTO.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
If you are writing in a language in which you are not fluent,
|
||||
I strongly recommend that you seek an editor who is. Technical
|
||||
documentation, more than any other type of writing, must use
|
||||
extremely precise grammar and vocabulary. Misuse of the language,
|
||||
no matter how understandable and unintended, makes your HOWTO
|
||||
less valuable.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sg-maintaining">
|
||||
<title>Maintaining Your HOWTO</title>
|
||||
|
||||
<para>
|
||||
Just because your HOWTO has now been published doesn't mean your
|
||||
job is done. HOWTOs need regular maintenance, to make sure they
|
||||
are up to date, and to improve them in response to readers' ideas
|
||||
and suggestions. A HOWTO is a living, growing body of knowledge,
|
||||
not just a publish-and-forget-it static document.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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>
|
||||
</sect1>
|
||||
|
||||
<sect1 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</citetitle></ulink>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
<ulink url="http://bartleby.com/141"><citetitle>Elements of Style</citetitle></ulink>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
FIXME: Please send the URL of your favorite resource on technical writing.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue