documentation-guide/en_US emacs-nxml.xml, NONE, 1.1 emacs.xml, NONE, 1.1 fdp-info.xml, NONE, 1.1 getting-files.xml, NONE, 1.1 intro.xml, NONE, 1.1 module-struct.xml, NONE, 1.1 style.xml, NONE, 1.1 tutorial.xml, NONE, 1.1 vim.xml, NONE, 1.1 writing-guidelines.xml, NONE, 1.1 xml-tags.xml, NONE, 1.1 documentation-guide.xml, 1.4, 1.5 docs-emacs-nxml.xml, 1.1, NONE docs-emacs.xml, 1.2, NONE docs-getting-files.xml, 1.2, NONE docs-intro.xml, 1.2, NONE docs-module-struct.xml, 1.2, NONE docs-rh-guidelines.xml, 1.3, NONE docs-style.xml, 1.2, NONE docs-tutorial.xml, 1.2, NONE docs-vim.xml, 1.2, NONE docs-xml-tags.xml, 1.3, NONE
Karsten Wade (kwade)
fedora-docs-commits at redhat.com
Sat Feb 3 22:22:00 UTC 2007
Author: kwade
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv32086
Modified Files:
documentation-guide.xml
Added Files:
emacs-nxml.xml emacs.xml fdp-info.xml getting-files.xml
intro.xml module-struct.xml style.xml tutorial.xml vim.xml
writing-guidelines.xml xml-tags.xml
Removed Files:
docs-emacs-nxml.xml docs-emacs.xml docs-getting-files.xml
docs-intro.xml docs-module-struct.xml docs-rh-guidelines.xml
docs-style.xml docs-tutorial.xml docs-vim.xml
docs-xml-tags.xml
Log Message:
renaming rh-guidelines to writing-guidelines
--- NEW FILE emacs-nxml.xml ---
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-emacs-nxml">
<title>Emacs and nXML Mode</title>
<indexterm>
<primary>nXML</primary>
</indexterm>
<indexterm>
<primary>Emacs</primary>
</indexterm>
<indexterm>
<primary>Emacs</primary>
<secondary>nXML mode</secondary>
</indexterm>
<para>
You can also use the nXML mode available for
<application>Emacs</application> to make it even easier to write in DocBook
XML format. nXML mode provides context-sensitive editing using completion,
real time validity error checking, syntax highlighting and indentation. All
you need to do is install an RPM!!
</para>
<note>
<title>Early stages</title>
<para>
Please be aware the nxml-mode for <application>Emacs</application> is
quite new, so there are a few things that the advanced user might notice
when using it with other documents types. If you keep an eye on the
mailing-list, you can keep up to date with these, as well as ask
questions. For more details, check out <xref
linkend="s1-emacs-nxml-readme"></xref>.
</para>
</note>
<sect1 id="s1-nxml-rpm">
<title>Getting the nXML RPM</title>
<indexterm>
<primary>nXML</primary>
<secondary>RPM</secondary>
</indexterm>
<indexterm>
<primary>nXML RPM</primary>
</indexterm>
<para>
To use nXML mode with emacs, you will need to install the nXML RPM
available from <ulink
url="http://people.redhat.com/twaugh/ftp/docbook/nxml-mode/">Tim
Waugh's</ulink> website or the source from <ulink
url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink>.
The source requires a lot more work to setup, therefore we will only be
concentrating on the RPM version.
</para>
<para>
Information on where to get the source is available in <xref
linkend="s1-emacs-additional-resources"></xref>.
</para>
</sect1>
<sect1 id="s1-nxml-examples">
<title>Examples</title>
<para>
Compared to PSGML mode there are only couple of commands that you need.
This speeds up writing with <application>Emacs</application> considerably,
which means you can concentrate more on the content of your article.
</para>
<sect2 id="s2-nxml-commands">
<title>Commands</title>
<para>
To create a tag, type <userinput><</userinput> and then type the
keyword. To complete the keyword, press <command>Ctrl-Ret</command>,
then add the last <userinput>></userinput>. To close a tag, type
<userinput></</userinput>.
</para>
<important>
<title>Important</title>
<para>
When you open a document that doesn't have a DOCTYPE declaration at
the top of the file, you will get this message and tag completion
won't work because nXML will not know what format you are writing.
</para>
</important>
<para>
To load the schema, type <command>Ctrl-c</command>, then
<command>Ctrl-s</command> and navigate to
<filename>/usr/share/emacs/site-lisp/nxml-mode/schema/</filename> and
load <filename>docbook.rnc</filename>. <application>Emacs</application>
will then prompt you to save it in the current working directory.
</para>
<tip>
<title>Tip</title>
<para>
The commands already discussed are the only differences between
using <application>Emacs</application> with PSGML mode and
<application>Emacs</application> with nXML mode. You will still need
to use all the same commands as discussed in <xref
linkend="s1-emacs-basic-commands"></xref>.
</para>
</tip>
</sect2>
</sect1>
<sect1 id="s1-emacs-nxml-additional-resources">
<title>Additional Resources</title>
<para> Additional Emacs and nXML references are available at the following
locations:
</para>
<itemizedlist>
<listitem>
<para><ulink
url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink>
— <citetitle>Author's download area</citetitle>
</para>
</listitem>
<listitem>
<para><ulink
url="http://wks.uts.ohio-state.edu/unix_course/intro-135.html">http://wks.uts.ohio-state.edu/unix_course/intro-135.html</ulink>
— <citetitle>Emacs Quick Reference Guide</citetitle>
</para>
</listitem>
<listitem>
<para>Emacs reference card that comes with the
<filename>emacs</filename> package. You can print it out as a
reference. —
<filename>/usr/share/emacs/<replaceable><version></replaceable>/etc/refcard.ps</filename>
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="s1-emacs-nxml-readme">
<title>nXML README File</title>
<note>
<title>Note</title>
<para>
This file can be found in the directory you extracted the source into,
or in
<filename>/usr/share/doc/nxml-mode-<replaceable><version></replaceable>/</filename>
if you installed the RPM.
</para>
</note>
<para>README file:</para>
<para>
This is a new major mode for GNU Emacs for editing XML documents. It
supports editing well-formed XML documents and also provides
schema-sensitive editing of XML documents using RELAX NG Compact Syntax.
</para>
<para>
To use this, you need GNU Emacs version 21.x, preferably 21.3. GNU Emacs
version 20 will not work properly, nor will XEmacs. To get started, do the
following:
</para>
<screen>
<command>M-x load-file RET rng-auto.el RET</command>
</screen>
<para>
This defines the necessary autoloads. Now, visit a file containing an XML
document, and do the following:
</para>
<screen> <command>M-x nxml-mode</command>
</screen>
<para>
Now do
</para>
<screen>
<command>C-h m</command>
</screen>
<para>
For information on how to use nxml-mode. The beginnings of a manual are
in nxml-mode.info. You can read this using:
</para>
<screen>
<command>C-u M-x info RET nxml-mode.info RET</command>
</screen>
<para>
It's also installed as an entry at the end of the top-level info
directory. So you can read it with <command>C-h i</command> as usual.
</para>
<para>
You can use <filename>test.valid.xml</filename> and
<filename>test.invalid.xml</filename> as examples of valid and invalid XML
documents.
</para>
<para>
To get things automatically loaded each time you start Emacs, add:
</para>
<screen>
<computeroutput> (load "~/nxml-mode-200YMMDD/rng-auto.el")
</computeroutput>
</screen>
<para>
to your <filename>.emacs</filename>, where
<computeroutput>~/nxml-mode-200YMMDD</computeroutput> is the directory
containing the <filename>.elc</filename> files. Note that
<filename>rng-auto.el</filename> does not load all of the nxml-mode code;
it merely sets things up so that all the features of nxml-mode will be
autoloaded properly. You should not try to autoload
<filename>rng-auto.el</filename> itself.
</para>
<para>
To use nxml-mode automatically for files with an extension of
<filename>xml</filename>, <filename>xsl</filename>,
<filename>rng</filename> or <filename>xhtml</filename>, add the following
to your <filename>.emacs</filename> file:
</para>
<screen>
<computeroutput> (setq auto-mode-alist (cons
'("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) auto-mode-alist))
</computeroutput>
</screen>
<para>
If you edit XML using iso-8859-N encodings other than iso-8859-1 and you
are running Emacs 21.3 or later, then I recommend enabling
unify-8859-on-decoding-mode, by adding the following to your
<filename>.emacs</filename> file:
</para>
<screen>
<computeroutput>(unify-8859-on-decoding-mode)</computeroutput>
</screen>
<para>
To get validation and schema-sensitive editing, you need a RELAX NG
Compact Syntax (RNC) schema for you document. The schema directory
includes some schemas for popular document types.
</para>
<para>
For more on RELAX NG, refer to <ulink
url="http://relaxng.org/">http://relaxng.org/</ulink>.
</para>
<para>
For a tutorial on RELAX NG Compact Syntax, refer to <ulink
url="http://relaxng.org/compact-tutorial.html">http://relaxng.org/compact-tutorial.html</ulink>
</para>
<para>
For automatically creating RNC schemas, I recommend my Trang program:
<ulink
url="http://www.thaiopensource.com/relaxng/trang.html">http://eee.thaiopensource.com/relaxng/trang.html"</ulink>
</para>
<para>
You can use this to
<itemizedlist>
<listitem>
<para>
Infer an RNC schema from an instance document
</para>
</listitem>
<listitem>
<para>
Convert a DTD to an RNC schema
</para>
</listitem>
<listitem>
<para>
Convert a RELAX NG XML syntax schema to an RNC schema
</para>
</listitem>
</itemizedlist>
</para>
<para>
To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you can
also use the XSLT stylesheet from <ulink
url="http://www.pantor.com/download.html">http://www.pantor.com/download.html"</ulink>.
</para>
<para>
To convert a W3C XML Schema to an RNC schema, you need first to convert it
to RELAX NG XML syntax using Sun's RELAX NG converter tool rngconv (built
on top of MSV). Refer to <ulink
url="https://msv.dev.java.net/">https://www.dev.java.net/</ulink>.
</para>
<para>
The file <filename>NEWS</filename> describes recent changes.
</para>
<para>
Please use the list <ulink
url="http://groups.yahoo.com/group/emacs-nxml-mode/">http://groups.yahoo.com/group/emacs-nxml-mode</ulink>
for bug reports, discussion. I will announce all new versions there.
</para>
<para>
James Clark
</para>
<para>
jjc at thaiopensource.com
</para>
</sect1>
</chapter>
***** Error reading new file: [Errno 2] No such file or directory: 'emacs.xml'
--- NEW FILE fdp-info.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
Warning! Warning! Danger, Will Robinson!
This is a generated file, produced from information in
the "rpm-info.xml" file.
DO NOT EDIT THIS FILE DIRECTLY!
Edit "rpm-info.xml" to change this information.
-->
<bookinfo>
<title>Fedora Documentation Guide</title>
<copyright>
<year>2003</year>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<holder>Red Hat, Inc.</holder>
<holder>Tammy Fox</holder>
<holder>Johnray Fuller</holder>
<holder>Sandra Moore</holder>
<holder>Paul W. Frields</holder>
</copyright>
<authorgroup>
<author>
<surname>Fox</surname>
<firstname>Tammy</firstname>
</author>
<author>
<surname>Fuller</surname>
<firstname>Johnray</firstname>
</author>
<author>
<surname>Moore</surname>
<firstname>Sandra</firstname>
</author>
<author>
<surname>Frields</surname>
<firstname>Paul</firstname>
</author>
</authorgroup>
<revhistory id="rv-revhistory">
<revision>
<revnumber>0.2.6.3</revnumber>
<date>2005-09-18</date>
<authorinitials/>
<revdescription>
<para>
Update to new build requirements
</para>
</revdescription>
</revision>
</revhistory>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="/home/kwade/Documents/projects/fedora/cvs-docs/documentation-guide/../docs-common/common/legalnotice-opl-en_US.xml"/>
</bookinfo>
--- NEW FILE getting-files.xml ---
<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-getting-files">
<title>Prerequisites</title>
<para>
To work on official &FED; documentation you need to install the required
tools. Follow the directions below to configure your system.
</para>
<section id="ch-getting-files-system-packages">
<title>System Packages</title>
<para>
Install the "Authoring and Publishing" package group, which contains
required DocBook XML files, stylesheets and scripts:
</para>
<screen>
<userinput>su -c 'yum groupinstall "Authoring and Publishing"'</userinput>
</screen>
<para>
Next, install the <filename>cvs</filename> package, which is used to
handle revision control on files in the official repository:
</para>
<screen>
<userinput>su -c 'yum install cvs'</userinput>
</screen>
</section>
<section id="ch-getting-files-fdp">
<title>Fedora Documentation Tools</title>
<para>
The &FDP;'s custom scripts and stylesheets are stored in CVS on the
<systemitem class="fqdomainname">cvs.fedoraproject.org</systemitem> CVS
server. Check them out along with the DocBook XML files for the existing
docs.
</para>
<screen>
<userinput>mkdir <replaceable>my-fedora-docs-sandbox</replaceable>
cd <replaceable>my-fedora-docs-sandbox</replaceable>
export CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fedora.redhat.com:/cvs/docs
cvs login
cvs co docs-common</userinput>
</screen>
<para>
At the password prompt, press the <keycap>Enter</keycap> key.
</para>
<note>
<title>Common Files</title>
<para>
You need to perform this "checkout" step only once, although you may
need to update the files later. These files are common to all the
official documentation.
</para>
</note>
<para>
To work on existing documents in CVS, refer to <xref linkend="ch-cvs"/>.
</para>
</section>
<section id="ch-getting-files-filenames">
<title>Filename Conventions</title>
<para>
&FDP; provides the tools, scripts, and stylesheets to transform your
<abbrev>XML</abbrev> documents into other output formats such as
<abbrev>HTML</abbrev>. In addition, these tools can build your document
into a <abbrev>RPM</abbrev> package. To take advantage of these
services, you must follow conventions for naming your files.
</para>
<section id="ch-getting-files-filenames-doc">
<title>Document Filenames</title>
<para>
Each document lives in a peer directory to the
<filename>docs-common</filename> directory you extracted from the &FED;
archive earlier. On the CVS server, these directories are called
<firstterm>modules</firstterm>. Choose a module name that accurately
reflects your document's subject, but avoid any name already taken. Use
the <command>cvs co -c</command> command to view existing module names.
</para>
<important>
<title>Avoid Redundancy</title>
<para>
Do not use the word <wordasword>&FED;</wordasword> in your module
name. Since all documents in the repository are &FED; documentation,
using this term creates unnecessary confusion.
</para>
</important>
</section>
</section>
</chapter>
<!--
Local variables:
mode: xml
fill-column: 72
End:
-->
***** Error reading new file: [Errno 2] No such file or directory: 'intro.xml'
--- NEW FILE module-struct.xml ---
<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-how-modules-work">
<title>How Modules Work</title>
<para>Documentation modules have a specific structure that enables the
preconfigured tools to work correctly. Follow this structure exactly or you
may have problems building your module. The &FDP; build tools locate
resources in the module and use them to build new output such as HTML or RPM
packages.</para>
<section id="sn-module-struct">
<title>Structure of a Module</title>
<para><xref linkend="ex-module-structure"/> shows a directory tree
of an example module, excluding any <filename
class="directory">CVS</filename> folders:</para>
<example id="ex-module-structure">
<title>Example Module Structure</title>
<screen><computeroutput><![CDATA[example-doc/
|
|-- en_US/
| |-- example-doc.xml
| |-- para.xml
| |-- doc-entities.xml
| `-- rpm-info.xml
|
|-- figs/
| |-- fedora-logo-sprite.eps
| `-- fedora-logo-sprite.png
|
|-- po/
| |-- de.po
| |-- example-doc.pot
| `-- pt.po
|
`-- Makefile]]></computeroutput></screen>
</example>
<formalpara>
<title>Primary language directory (required)</title>
<para>This is the only directory absolutely required. It is named for the
original language of the document, such as <filename
class="directory">en_US</filename> (US English). The primary language
does not have to be US English; all languages are supported. This
directory contains all the XML source for the actual document, as well
as XML source for document-specific
<firstterm>entities</firstterm><footnote>
<para>Think of an XML entity as a predefined snippet of information.
It can represent a chunk of XML source, or simply a word or
character. If the information changes, it need be replaced only
once, in the definition, to fix all usage.</para>
</footnote>.
</para>
</formalpara>
<formalpara>
<title>Graphics directory (optional)</title>
<para>The <filename class="directory">figs/</filename> directory is an
optional directory where graphics for the document should be stored. If
graphics are screenshots that are particular to a language, the
<filename class="directory">figs/</filename> directory can and should be
stored in a language directory.</para>
</formalpara>
<formalpara>
<title>Translation (PO) directory (optional)</title>
<para>The <filename class="directory">po/</filename> directory contains
specially formatted files created and used by translators. The &FDP;
build tools use these files to create translated versions of documents.
The translated documents are not stored in CVS; they are created as
needed from these PO files.</para>
</formalpara>
<formalpara>
<title>Makefile (required)</title>
<para>The <filename>Makefile</filename> controls the build process. Its
content is discussed in <xref linkend="ex-makefile"/>.</para>
</formalpara>
<formalpara>
<title><filename>rpm-info.xml</filename> (required)</title>
<para>The <filename>rpm-info.xml</filename> file contains document
specific metadata</para>
</formalpara>
</section>
<section id="ch-getting-files-build-system">
<title>The Document Build System</title>
<para>
The build system can render the document into another format such
as <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev>, using
<command>make(1)</command> and shell scripts. Authors need
<emphasis>no</emphasis> prior experience with either shell scripts
or a <command>make(1)</command>.
</para>
<section id="sn-makefile">
<title>The Document <filename>Makefile</filename></title>
<para>
Each individual document has its own
<filename>Makefile</filename>, which only needs to be a few
lines long. The document <filename>Makefile</filename> content
is designed for cut and paste operations.
</para>
<para>
<xref linkend="ex-makefile"/> below shows the whole
<filename>Makefile</filename> for a simple document with two
files and two translations.
</para>
<example id="ex-makefile">
<title>Sample Document Makefile</title>
<programlisting><![CDATA[DOCBASE = example-doc
PRI_LANG = en_US
OTHERS = de pt
DOC_ENTITIES = doc-entities
define XMLFILES_template
XMLFILES-${1} = ${1}/example-doc.xml \
${1}/para.xml
endef
include ../docs-common/Makefile.common]]></programlisting>
</example>
<para>
Do not be concerned with some of the more complicated syntax
such as the <command>XMLFILES_template</command> stanza. An
explanation for this template appears a few paragraphs
below.</para>
<formalpara>
<title><systemitem class="macro">DOCBASE</systemitem></title>
<para>This variable contains the name for the main (parent) XML
document. Follow convention by naming your document after the
module name.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">PRI_LANG</systemitem></title>
<para>This variable contains the ISO code for the original
version of the document, such as
<systemitem>en_US</systemitem>.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">OTHERS</systemitem></title>
<para>This variable contains a listing of ISO codes for any
other versions into which the document has been translated.
The module must contain a <filename
class="directory">po/</filename> directory and a PO file for
any indicated additional languages.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">DOC_ENTITIES</systemitem></title>
<para>This variable contains a listing of any files containing
entity definitions. The &FDP; uses a special XML format to
record document-specific entities, so they can be translated and
built on the fly like any other XML document. An example is
shown later in this guide. <!-- need xref here --></para>
</formalpara>
<formalpara>
<title><systemitem
class="macro">XMLFILES_template</systemitem></title>
<para>This template allows the build tools to work with the
document in multiple languages once it is translated. The
<systemitem class="macro">${1}</systemitem> marking is a
variable used to substitute the appropriate language. This
template is not terribly complicated. For a new module,
duplicate this section exactly except for the actual
filenames. Prepend the text <systemitem
class="macro">${1}/</systemitem>, in place of the language
code directory name, to each filename in your document.
</para>
</formalpara>
<important>
<title>Files Exempt From Listing</title>
<para>Do not include the document-specific entities XML file or
the <filename>rpm-info.xml</filename> file, which will be
discussed later in this guide.<!-- include xref --></para>
</important>
<para>
The final line, beginning with <literal>include</literal>,
references the main <filename>Makefile</filename> for the build
system. This <filename>Makefile.common</filename> file contains
all the <application>make(1)</application> targets and rules to
actually build the document and the various archives.
</para>
</section>
<section>
<title>The Document <filename>rpm-info.xml</filename></title>
<para>Each document module's primary language directory contains a
file called <filename>rpm-info.xml</filename>. This file
contains document-specific metadata used to generate revision
history, copyright, and contributor information. It follows a
DTD specification included with the rest of the build system
tools.</para>
<para><xref linkend="ex-rpminfo"/> illustrates the content of
this file:</para>
<example id="ex-rpminfo">
<title>Example <filename>rpm-info.xml</filename> File</title>
<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE rpm-info SYSTEM "../../docs-common/packaging/rpm-info.dtd">
<rpm-info>
<colophon>
<worker surname="Smith" firstname="John" othername="Q."
id="JohnSmith" email="jsmith at example.com"
wholename="John Q. Smith" initials="JS"/>
</colophon>
<author worker="JohnSmith"/>
<license>
<rights>OPL</rights>
<version>1.0</version>
</license>
<copyright>
<year>2006</year>
<holder>John Q. Smith</holder>
</copyright>
<title>My Tutorial</title>
<desc>A tutorial about something important</desc>
<changelog order="newest-first">
<revision date="2006-06-01" number="0.1" role="doc">
<author worker="JohnSmith"/>
<details>First draft</details>
</revision>
</changelog>
</rpm-info>]]></programlisting>
</example>
<para>If you are not familiar with XML editing, copy and paste
this file from an existing module and then edit the values for
the various elements as appropriate. Consult &FDP; members and
help channels for more assistance if needed.</para>
</section>
</section>
<section id="ch-getting-files-build-system-targets">
<title>Build System Actions</title>
<para>
To render the <abbrev>XML</abbrev> document into another format,
use one of the following <command>make</command> targets:
</para>
<formalpara>
<title><systemitem class="macro">html</systemitem></title>
<para>This target builds the "chunked" <abbrev>HTML</abbrev>
document for each defined translation. Output is placed in a
separate directory named <filename class="directory"><systemitem
class="macro">${DOCBASE}</systemitem>-<systemitem
class="macro">${LANG}</systemitem>/</filename>. Each
document section is a separate file within that
directory.</para>
</formalpara>
<formalpara>
<title><systemitem
class="macro">html-nochunks</systemitem></title>
<para>This target builds the "non-chunked" <abbrev>HTML</abbrev>
document for each defined translation. Output is placed in a
single file: <filename><systemitem
class="macro">${DOCBASE}</systemitem>-<systemitem
class="macro">${LANG}</systemitem>.html</filename>; no other
files are created.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">pdf</systemitem></title>
<para>This target builds only the <abbrev>PDF</abbrev> document
for all document languages. <abbrev>PDF</abbrev> production is
currently erratic and may not work for your document.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">tarball</systemitem></title>
<para>This target builds only the <command>tar(1)</command>
archive for all document languages.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">all</systemitem></title>
<para>This target builds all targets listed above.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">clean</systemitem></title>
<para>This target deletes any temporary, or generated files, but
does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>,
<abbrev>PDF</abbrev>, or archive files.</para>
</formalpara>
<formalpara>
<title><systemitem class="macro">distclean</systemitem></title>
<para>This target erases all <abbrev>HTML</abbrev>,
<abbrev>PDF</abbrev>, and archive files. This target
automatically invokes the <filename>clean</filename> target as
well.</para>
</formalpara>
<section>
<title>Adding or Changing Targets</title>
<para>
To add a new target and rules, place them at the bottom of the
document <filename>Makefile</filename>, below the
<literal>include</literal> line. Follow your target definitions
with a double colon, not a single colon. The double colon
allows you to specify additional rules for existing targets, or
to write rules for a new target.
</para>
<para>
For more information on using <command>make(1)</command>,
consult the online documentation with the command <command>info
make</command> in a terminal.
</para>
</section>
<section id="ch-getting-files-build-system-images">
<title>Using Document Image Files</title>
<para>
Tutorial documents often make use of images such as <filename
class="extension">.PNG</filename> files. Store image files in
a <filename class="directory">figs/</filename> folder in the
main module directory, as shown in <xref
linkend="ex-module-structure"/>.
</para>
<para>
Depending on the output media, sometimes images may be scaled,
streteched, or squashed. To minimize any distortions, we
recommend that you use only <filename
class="extension">.PNG</filename> images. Avoid <filename
class="extension">.JPG</filename> files. The
<command>convert(1)</command> program, from the <package
role="rpm">ImageMagick</package> <abbrev>RPM</abbrev> package,
provides a convenient way to reformat <filename
class="extension">.JPG</filename> images into <filename
class="extension">.PNG</filename> format. For more information
on formatting images such as screenshots, refer to <xref
linkend="s1-screenshots"/>.
</para>
<para>
Image files may be organized into subdirectories under
<filename>figs/</filename> if necessary. The document building
system recreates the image subdirectory structure in the output
documents.
</para>
<para>
Images often contain labels or other text which may need to be
localized. A screenshot of a program, for example, may require
a version for each translated language. Name language-dependent
image files such as program screenshots by adding the language
code to the filename, such as
<filename>menu-en_US.png</filename>. Language-independent
images, such as <filename>icon.png</filename>, do not need
language codes.
</para>
<para>
Sometimes, a document may require images that do not follow the
naming convention. To use these images with the document
building system, create an ordinary text file containing the
image filenames. This file must be named
<filename>figs/Manifest-</filename><systemitem
class="macro">${LANG}</systemitem> so the build system finds
it when searching for image filenames.
</para>
<para>
<xref linkend="ch-getting-files-build-system-manifest"/>
demonstrates one way to create this
<filename>Manifest</filename> file.
</para>
<example id="ch-getting-files-build-system-manifest">
<title>Building A Manifest</title>
<programlisting><![CDATA[rm -f figs/Manifest-en
find figs -print >/tmp/manifest
mv /tmp/manifest figs/Manifest-en]]></programlisting>
</example>
</section>
<section>
<title>Adding a New DocBook XML File</title>
<para>To add a new DocBook XML file to an existing document,
follow these steps:</para>
<procedure>
<step>
<para>Place the new DocBook XML file in the primary language
directory.</para>
</step>
<step>
<para>Edit the <filename>Makefile</filename> and add the
filename to the <varname>XMLFILES-${1}</varname> listing.
Append a <keycap>\</keycap> to the last existing line, and
on the next line add an entry for the new file. Remember to
add the <literal>${1}/</literal> prefix as a substitute for
the language directory name.</para>
</step>
</procedure>
</section>
<section>
<title>Adding a Translation</title>
<para>Translations are stored as PO (portable object) files, which
the toolchain transforms into translated documents. Each PO
file is based on the POT (PO template) for the document and
translated by the &FED; Translation Project. To add a
translation, follow these steps:</para>
<procedure>
<step>
<para>If the <filename class="directory">po/</filename>
directory does not exist, create it and add it to
CVS:</para>
<screen><![CDATA[mkdir po && cvs add po/]]></screen>
</step>
<step>
<para>If it does not exist, create the POT file:</para>
<screen><![CDATA[make pot]]></screen>
</step>
<step>
<para>Add the new translation language to the
<varname>OTHERS</varname> listing in the
<filename>Makefile</filename>.</para>
</step>
<step>
<para>Although translators often copy the POT manually to
create the new PO file, the following command also
works:</para>
<screen>make po/<replaceable>lang</replaceable>.po</screen>
</step>
</procedure>
</section>
</section>
</chapter>
<!--
Local variables:
mode: xml
fill-column: 72
End:
-->
--- NEW FILE style.xml ---
<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-style">
<title>Style</title>
<para>
Writing good technical documentation is not simply reproducing
command lines and instruction sets. Good documentation is easy to
read, understand, and translate, and presents a concise logical
progression of concepts. Good documentation can also be defined by
what it does <emphasis>not</emphasis> contain. Your tutorial should
avoid:
</para>
<itemizedlist>
<listitem>
<para>
Excessive wordiness
</para>
</listitem>
<listitem>
<para>
Unnecessary or undefined jargon
</para>
</listitem>
<listitem>
<para>
Grammatical or spelling errors
</para>
</listitem>
<listitem>
<para>
References to yourself or your experiences
</para>
</listitem>
<listitem>
<para>
Remarks which might offend or confuse any reader
</para>
</listitem>
</itemizedlist>
<para>
This chapter contains style rules and guidelines for writing &FED;
documentation. Guidelines are not the same as rules. It is
acceptable to violate a guideline when it makes your material easier
to understand. Follow guidelines whenever possible, but follow
rules at all times. Assume any advice is a guideline unless
identified otherwise.
</para>
<section id="sn-intro-to-style">
<title>Why Style Is Important</title>
<para>
Writing well comes naturally to almost no one. It is a skill that
professional writers, even famous ones, must practice constantly.
<firstterm>Style</firstterm>
<indexterm><primary>style</primary></indexterm> is the quality
that separates elegant writing from the merely functional.
</para>
<para>
Elegance comes in many forms. In prose and poetry, elegant
writing may not follow some (or any) common rules of grammar,
syntax, or spelling. A good example is Episode 18, "Penelope," in
James Joyce's novel <citetitle>Ulysses</citetitle><footnote
id='fn-ulysses'>
<para>
For example, refer to. <ulink
url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>.
Please note that this example contains some mature themes and
language, and is not suitable for all readers.
</para>
</footnote>. There, Joyce uses long streams of words without
punctuation to simulate a character's internal consciousness. By
violating basic rules of grammar and syntax, Joyce simulates the
disorganized but loosely connected thought patterns of the
narrator.
</para>
<para>
Technical documentation, however, should always respect these
rules. The more a document departs from standard language usage,
the more difficult the material becomes for the reader. For
example, readers may not be native speakers of the language used,
or they might be reading a translation. If the writer uses slang,
idioms, or jargon, a reader or translator may easily become
confused. The following example compares two different written
executions of the same idea:
</para>
<example>
<title>Incorrect style</title>
<!-- I prefer "incorrect," because I think terms such as
"problematic" are mealy-mouthed. They remind me of the late
1980's English textbook trend toward the politically correct yet
wholly unhelpful "standard/nonstandard." But then, I tend to be
dogmatic; it's probably my Catholic upbringing. [PWF] -->
<para>
So you made the changes I showed you in the last section. What's
the next thing you should do? Just pop your thumb drive onto
your system and read the <filename>messages</filename> log. When
you see "USB device found," then Bob's your uncle.
</para>
</example>
<example>
<title>Correct style</title>
<!-- I prefer "correct." See above. [PWF] -->
<para>
After you complete the configuration changes above, attach the
USB removable media to your system. Use the
<command>dmesg</command> command to examine the kernel message
log. The message <computeroutput>USB device
found</computeroutput> indicates that your device was
installed successfully.
</para>
</example>
<para>
The first example is more conversational English, which is not
appropriate for official written documentation. The second
example is more formal, but as a result it is easier to
comprehend, both for native readers and translators.
</para>
<para>
Following style rules and guidelines also makes readers more
comfortable with a set of documents. Consistent style enhances
the professional appearance of documentation, and its perceived
value. On the other hand, lapses in punctuation or poor grammar
negatively affect a reader's reaction to written material. A
reader can feel that an otherwise correct technical document is
lacking in authority, simply because it is poorly written. Readers
feel at ease when they do not have to struggle to understand an
author's use of language.
</para>
<para>
This chapter cannot possibly cover enough material to make every
reader a good writer. Some manuals devoted entirely to writing
style are themselves hundreds of pages long. This chapter
provides enough guidelines for intermediate writers to understand
style usage in technical documentation.
</para>
<para>
If you are not a practiced writer, whether of technical
documentation or otherwise, you may benefit from other style
resources. The following list is far from comprehensive, but
provides a starting point:
</para>
<itemizedlist>
<listitem>
<para>
<citetitle>The Elements of Style</citetitle>, by William
Strunk. Basic rules and links to online versions can be found
at: <ulink
url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink>
</para>
</listitem>
<!-- placeholder for when it's ready
<para>
<citetitle>The Elements of Style</citetitle>, by William
Strunk. Fedora Docs Project version: <ulink
url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>
</para>
-->
<listitem>
<para>
<citetitle>The Chicago Manual of Style</citetitle>, by the
University of Chicago Press. Online version: <ulink
url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink>
</para>
</listitem>
<listitem>
<para>
<citetitle>Paradigm Online Writing Assistant</citetitle>,
maintained by Chuck Guilford, Ph.D. Online only: <ulink
url="http://www.powa.org/">http://www.powa.org/</ulink>
</para>
</listitem>
</itemizedlist>
<para>
There are many free software documentation projects which have
developed their own style guidelines. This chapter, in fact,
draws heavily on the <citetitle>GNOME Documentation Style
Guidelines</citetitle> (<firstterm>GDSG</firstterm>). You may
read the original <citetitle>GDSG</citetitle> at <ulink
url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>.
</para>
</section>
<section id="sn-tech-docs-fundamentals">
<title>Fundamental Concepts of Technical Documentation</title>
<note>
<title>Bibliographic Information</title>
<para>
This section is drawn primarily from the
<citetitle>GDSG</citetitle>.
</para>
</note>
<!-- This section will reproduce mostly what is in Chapter 1 of
the GDSG. There may be minor changes. FIXME: Make sure the
appropriate front matter of the Documentation Guide includes
attribution as required by the GNU FDL. -->
<para>
This chapter provides a brief introduction to writing technical
documentation.
</para>
<section id="sn-fundamentals-1">
<title>General Style Requirements</title>
<para>
Technical writing for the &FP; imposes special constraints
beyond the basic requirements of good prose. Good &FED;
technical documentation has the following characteristics:
</para>
<variablelist>
<varlistentry>
<term>Comprehensive</term>
<listitem>
<para>
Describe all of the functionality of a product. Do not
omit functionality that you regard as irrelevant for the
user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Conforming</term> <!-- I'm having issues with the
sketchy definition of this non-dictionary word and the
associated text. Not wrong, per se, just wishing for
something better. This note shall remind us! - kwade -->
<!-- Hopefully this change helps. Makes sense according to the
gdict tool in Core, at least. - PWF -->
<listitem>
<para>
Describe what you see. Do not describe what you want to
see. Present your information in the order that users
experience the subject matter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Clear</term>
<listitem>
<para>
Read <citetitle>The Elements of Style</citetitle> (<ulink
url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink>)
to help make your writing clear.
</para>
<!-- placeholder for when this is published:
<para>
Read <citetitle>The Elements of Style</citetitle>
&FED;-version (<ulink
url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>)
to help make your writing clear.
</para>
-->
</listitem>
</varlistentry>
<varlistentry>
<term>Consistent</term>
<listitem>
<para>
Use agreed vocabulary throughout your documentation. Use
the same vocabulary as other writers who are working on
related documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Concise</term>
<listitem>
<para>
Review your work frequently as you write your document.
Ask yourself which words you can take out. Refer to <xref
linkend="sn-fundamentals-2"/> for specific guidelines.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="sn-fundamentals-2">
<title>Golden Rules</title>
<para>
This section contains some basic style guidelines. Subsequent
sections in this chapter expand on these guidelines to give more
detailed guidance.
</para>
<variablelist>
<varlistentry>
<term>Golden Rule 1: Be brief</term>
<listitem>
<itemizedlist>
<listitem>
<para>
Limit each sentence to fewer than 25 words.
</para>
</listitem>
<listitem>
<para>
Limit each procedure step to 23 words.
</para>
</listitem>
</itemizedlist>
<example id="ex-golden-rule-1-wrong">
<title>Incorrect: Too long</title>
<para> Under normal operating conditions, the kernel does
not always immediately write file data to the disks,
storing it in a memory buffer and then periodically
writing to the disks to speed up operations.
</para>
</example>
<example id="ex-golden-rule-1-right">
<title>Correct: Less wordy</title>
<para>
Normally, the kernel stores the data in memory prior to
periodically writing the data to the disk.
</para>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>Golden Rule 2: Be organized</term>
<listitem>
<itemizedlist>
<listitem>
<para>
Limit each paragraph to one topic.
</para>
</listitem>
<listitem>
<para>
Limit each sentence to one idea.
</para>
</listitem>
<listitem>
<para>
Limit each procedure step to one action.
</para>
</listitem>
</itemizedlist>
<example id="ex-golden-rule-2-wrong">
<title>Incorrect: Disorganized topics</title>
<para>
The <application>Workspace Switcher</application> applet
helps you navigate all of the virtual desktops available
on your system. The X Window system, working in hand
with a piece of software called a <emphasis>window
manager</emphasis>, allows you to create more than one
virtual desktop, known as
<emphasis>workspaces</emphasis>, to organize your work,
with different applications running in each workspace.
The <application>Workspace Switcher</application> applet
is a navigational tool to get around the various
workspaces, providing a miniature road map in the GNOME
panel showing all your workspaces and allowing you to
switch easily between them.
</para>
</example>
<example id="ex-golden-rule-2-right">
<title>Correct: Organized topics</title>
<para>
Use the <application>Workspace Switcher</application> to
add new <emphasis>workspaces</emphasis> to the GNOME
Desktop. You can run different applications in each
workspace. The <application>Workspace
Switcher</application> applet provides a miniature map
that shows all of your workspaces. You can use the
<application>Workspace Switcher</application> applet to
switch between workspaces.
</para>
</example>
<tip>
<para>
Plan the order of paragraphs before you start writing.
Decide which topic you want to cover in each paragraph.
</para>
</tip>
</listitem>
</varlistentry>
<varlistentry>
<term>Golden Rule 3: Be demonstrative</term>
<listitem>
<para>
Use explicit examples to demonstrate how an application
works. Provide instructions rather than descriptions.
</para>
<example id="ex-golden-rule-3-wrong">
<title>Incorrect: Describes but does not
demonstrate</title>
<para>
There is a text box that you can use to find out the
definition of a word.
</para>
</example>
<example id="ex-golden-rule-3-right">
<title>Correct: Demonstrates usage</title>
<para>
To request a definition of a word, type the word in the
text box, then select <guilabel>Lookup</guilabel>.
</para>
</example>
<tip>
<para>
Do not apply this guideline too rigidly. Sometimes you
must explain how software works to support your how-to
examples.
</para>
</tip>
</listitem>
</varlistentry>
<varlistentry id="vle-golden-rule-4">
<term>Golden Rule 4: Be objective</term>
<listitem>
<para>
Write in a neutral tone.
</para>
<example id="ex-golden-rule-4-wrong">
<title>Incorrect: Sentence takes sides</title>
<para>
The applet is a handy little screen grabber.
</para>
</example>
<example id="ex-golden-rule-4-right">
<title>Correct: Sentence is objective</title>
<para>
Use the applet to take screenshots.
</para>
</example>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="sn-fundamentals-3">
<title>Tone</title>
<para>
Inappropriate tone hinders reader access to information. A
neutral tone free of opinion or personal flavor improves the
reader's comprehension. Neutral tone helps writers to work in
parallel on a large technical documentation project.
Furthermore, additional writers may join the project at any
time. Use of a neutral tone helps to achieve consistency across
a documentation set, and thereby facilitates user access to
information. The best way to achieve a common, neutral tone is
to apply the following principles:
</para>
<variablelist>
<varlistentry>
<term>Avoid humor</term>
<listitem>
<para>
Humor distracts from the information you are trying to
provide. Humor also makes documentation difficult to
translate. Stay factual.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid personal opinions</term>
<listitem>
<para>
Whether you think a function is useful or woeful is
irrelevant. Report the function to the user, with
instructions about how to use the function. Stay
accurate.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid colloquial language</term>
<listitem>
<para>
Colloquial language is difficult to translate and usually
culture-specific. Stay neutral.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid topical expressions</term>
<listitem>
<para>
An expression that is in common use today might convey
something completely different tomorrow. Stay technical.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid aspirational statements</term>
<listitem>
<para>
Statements about the future developments of a product do
not belong in technical documentation. Write about what
you see right now. Stay real.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="sn-fundamentals-4">
<title>Reaching the Right Audience</title>
<para>
All of the decisions that you make about the structure and
content of a manual follow from an understanding of the
audience. Consider how the audience accesses the documentation,
what sort of information the audience needs, and the experience
level of the audience. Usually, you need to create
documentation that is suitable for different audiences. The
following sections introduce some of the audience-related topics
you need to consider.
</para>
</section>
<section id="sn-fundamentals-6">
<title>User Motivation</title>
<para>
Do not waste the time of the user who looks for information in
your documentation. Users do not read technical documentation
for entertainment. Users usually have specific questions. You
need to give clear answers to those questions.
</para>
</section>
<section id="sn-fundamentals-7">
<title>New Users</title>
<para>
New users to &FC; are likely to consult online tutorials for
guidance about unfamiliar applications or functionality. Each
tutorial should contain enough introductory information to tell
new users how to start using the relevant functions. Each
tutorial should also contain enough usage instructions to tell
users the different actions that they can perform with the
command or function. Keep these instructions task-oriented. Do
not describe GUI screens, dialogs, and dialog elements in a
tutorial, unless there is an unusual feature that affects your
instructions.
</para>
</section>
<section id="sn-fundamentals-8">
<title>Experienced Users</title>
<para>
Experienced users are more likely to use documentation as a
reference. The documentation therefore needs to be complete,
well-organized, and in the case of printed manuals,
well-indexed.
</para>
</section>
<section id="sn-fundamentals-9">
<title>Do Not Offend Your Audience</title>
<para>
To avoid offending your readers, apply the following guidelines
to your documentation:
</para>
<variablelist>
<varlistentry>
<term>Avoid insider language</term>
<listitem>
<para>
Insider language includes both undefined jargon and the
tendency of the computer community to shorten words. For
example, use the term <literal>documentation</literal>
instead of the term <literal>docs</literal>. A term may
be jargon if it fails all the following conditions:
</para>
<itemizedlist>
<listitem>
<para>
The term does not appear in the <citetitle>&FED;
Jargon Buster</citetitle> (<ulink
url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>).
</para>
</listitem>
<listitem>
<para>
The term does not appear in the <citetitle>American
Heritage Dictionary</citetitle> (<ulink
url="http://www.bartleby.com/61/">http://www.bartleby.com/61/
</ulink>).
</para>
</listitem>
<listitem>
<para>
The term does not appear in the glossary of the manual
that you are writing.
</para>
</listitem>
<listitem>
<para>
The term is not defined in the body text of the manual
that you are writing.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid gender-specific language</term>
<listitem>
<para>
Pronoun constructions such as <literal>his/her</literal>
or <literal>s/he</literal> do not exist. There is no need
to identify gender in your instructions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid culture-specific language</term>
<listitem>
<para>
There is little point in giving an example that everyone
in your town knows about, but is a complete mystery to
everyone else in the world.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid talking down to your reader</term>
<listitem>
<para>
There are few experiences more irritating for a user than
documentation that says an action is easy or quick, when
in fact the user cannot complete the action. Do not
qualify or prejudge actions.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Other parts of this guide discuss in more detail tone and
language usage that can cause offense.
</para>
</section>
</section>
<section id="sn-grammar-and-usage">
<title>Grammar and Usage Guidelines</title>
<note>
<title>Bibliographical Information</title>
<para>
This section is drawn partly from the
<citetitle>GDSG</citetitle>, and partly from <citetitle>The
Elements of Style</citetitle>, updated as necessary for the
needs of 21st-century technical documentation writers.
</para>
</note>
<!-- FIXME: Again, check attribution viz. GNU FDL. This will be more work
than the previous section. -->
<para>
This section contains an alphabetical list of grammar and usage
guidelines for use in &FED; documentation. Many of these
guidelines are only applicable to English-language usage, refer to
the <citetitle>American Heritage Dictionary</citetitle> (<ulink
url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>)
and the <citetitle>Chicago Manual of Style</citetitle> (<ulink
url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
</para>
<variablelist>
<varlistentry>
<term>Abbreviations</term>
<listitem>
<para>
A shortened form of a word or phrase that takes the place of
the full word or phrase, such as <literal>Dr.</literal>,
<literal>a.m.</literal>, <literal>p.m.</literal>, and so on.
Apply the following rules when you use abbreviations:
</para>
<itemizedlist>
<listitem>
<para>
Avoid creating new abbreviations. Unfamiliar
abbreviations can confuse rather than clarify a concept.
</para>
</listitem>
<listitem>
<para>
Do not explain or expand familiar abbreviations.
</para>
</listitem>
<listitem>
<para>
Do not include familiar abbreviations in the glossary of
your manual.
</para>
</listitem>
</itemizedlist>
<para>
For abbreviations of phrases, such as
<literal>i.e.</literal> for "in other words" and
<literal>e.g.</literal> for "for example", do not use the
abbreviation. Spell out the entire phrase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Adjectives</term>
<listitem>
<para>
Use adjectives with caution. If an adjective is necessary
to differentiate between items, then use adjectives. In all
cases, test whether the phrase can stand alone without the
adjective.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Acronyms</term>
<listitem>
<para>
A term that represents a multi-word term. Typically,
acronyms are formed in the following ways:
</para>
<itemizedlist>
<listitem>
<para>
From the first letters of each word in a compound term,
for example Table of Contents (TOC).
</para>
</listitem>
<listitem>
<para>
From recognizable parts of a compound term, such as GNU
Object Model Environment (GNOME).
</para>
</listitem>
</itemizedlist>
<para>
Apply the following rules when you use acronyms:
</para>
<itemizedlist>
<listitem>
<para>
On the first occurrence of an acronym, spell out the
full term, with the acronym in parentheses.
</para>
</listitem>
<listitem>
<para>
Do not spell out the full compound for well-known
acronyms, unless you think the information is useful for
readers.
</para>
</listitem>
<listitem>
<para>
Avoid creating new acronyms. Unfamiliar acronyms can
confuse rather than clarify a concept.
</para>
</listitem>
<listitem>
<para>
Write the acronym in uppercase letters, unless there is
a compelling case for lowercase.
</para>
</listitem>
<listitem>
<para>
Include the acronym and the full term in the glossary of
your manual.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Adverbs</term>
<listitem>
<para>
Use adverbs with caution. If an adverb is necessary to
qualify the function of a component, then use an adverb. In
all cases, test whether the phrase can stand alone without
the adverb. Classic superfluous adverbs
<literal>simply</literal>, <literal>easily</literal>,
<literal>quickly</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Anthropomorphism</term>
<listitem>
<itemizedlist>
<listitem>
<para>
Do not apply emotions, desires, or opinions to software
applications.
</para>
</listitem>
<listitem>
<para>
Do not apply a sense of location or dimension to a
software application. A user can not be "in" a text
editor.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Articles</term>
<listitem>
<para>
Do not use the definite article <literal>the</literal> to
begin any of the following items:
</para>
<itemizedlist>
<listitem>
<para>
Manual titles
</para>
</listitem>
<listitem>
<para>
Chapter titles
</para>
</listitem>
<listitem>
<para>
Headings
</para>
</listitem>
<listitem>
<para>
Figure captions
</para>
</listitem>
<listitem>
<para>
Table captions
</para>
</listitem>
<listitem>
<para>
Callouts
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Apostrophe</term>
<listitem>
<para>
Do not use apostrophes except where absolutely required
</para>
<itemizedlist>
<listitem>
<para>
Do not use apostrophes to denote possession.
</para>
</listitem>
<listitem>
<para>
Do not use apostrophes to denote contractions.
</para>
</listitem>
<listitem>
<para>
Do not use apostrophes to denote plurals.
</para>
</listitem>
</itemizedlist>
<example id="ex-apostrophe-wrong">
<title>Incorrect: Apostrophes</title>
<itemizedlist>
<listitem>
<para>
the <guimenu>Main Menu's</guimenu>
<guimenuitem>Help</guimenuitem> option
</para>
</listitem>
<listitem>
<para>
don't use the default option
</para>
</listitem>
<listitem>
<para>
several SCSI disk's
</para>
</listitem>
</itemizedlist>
</example>
<example id="ex-apostrophe-right">
<title>Correct: No apostrophes</title>
<itemizedlist>
<listitem>
<para>
the <guimenuitem>Help</guimenuitem> option on the
<guimenu>Main Menu</guimenu>
</para>
</listitem>
<listitem>
<para>
do not use the default option
</para>
</listitem>
<listitem>
<para>
several SCSI disks
</para>
</listitem>
</itemizedlist>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>Brackets</term>
<listitem>
<itemizedlist>
<listitem>
<para>
Do not use brackets [such as these] as a substitute for
parentheses (such as these).
</para>
</listitem>
<listitem>
<para>
Use brackets for optional command line entries.
</para>
</listitem>
<listitem>
<para>
Do not use angle brackets to indicate variables in text,
instead use the <sgmltag
class="starttag">replaceable</sgmltag> tag. Refer to
<xref linkend="s1-xml-tags-replaceable"/> for
information about using this tag.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Capitalization</term>
<listitem>
<para>
Capitalize in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
All letters in acronyms, unless the acronym is a
well-known exception
</para>
</listitem>
<listitem>
<para>
Initial letter of the first word in a list
</para>
</listitem>
<listitem>
<para>
Initial letter of the first word in a callout
</para>
</listitem>
<listitem>
<para>
Initial letter of a key name, such as the
<keycap>Shift</keycap> key
</para>
</listitem>
<listitem>
<para>
Initial letter of a sentence
</para>
<note>
<title>Command Names</title>
<para>
Avoid starting a sentence with a command name or
application name that has a lowercase initial letter.
</para>
</note>
</listitem>
<listitem>
<para>
Initial letter of a complete sentence after a colon
</para>
</listitem>
</itemizedlist>
<para>
Do not capitalize in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
A compound term that is followed by an abbreviation or
an acronym
</para>
</listitem>
<listitem>
<para>
When you want to emphasize something
</para>
</listitem>
<listitem>
<para>
Variable names
</para>
</listitem>
<listitem>
<para>
The initial letter of an incomplete sentence after a
colon
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Captions</term>
<listitem>
<para>
Use the same rules as for headings, for all captions
accompanying figures and tables. Do not put a period at the
end of a caption.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Colon</term>
<listitem>
<para>
Use a colon in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To introduce a list
</para>
</listitem>
<listitem>
<para>
Before an explanation
</para>
</listitem>
<listitem>
<para>
After an introduction
</para>
</listitem>
</itemizedlist>
<para>
Do not use a colon in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To introduce a figure or a table
</para>
</listitem>
<listitem>
<para>
To introduce headings
</para>
</listitem>
<listitem>
<para>
At the end of an introduction to a procedure
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Column headings</term>
<listitem>
<para>
Use the same rules as for headings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Comma</term>
<listitem>
<para>
Use commas in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To separate items in a series
</para>
</listitem>
<listitem>
<para>
To separate the parts of a sentence
</para>
</listitem>
<listitem>
<para>
To separate nonrestrictive phrases
</para>
</listitem>
<listitem>
<para>
Instead of dashes to set off appositives
</para>
</listitem>
<listitem>
<para>
With <emphasis>for example</emphasis> and similar
expressions
</para>
</listitem>
</itemizedlist>
<para>
Do not use commas in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
In a series of adjectives used as one modifier
</para>
</listitem>
<listitem>
<para>
Between two short independent clauses
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Commands</term>
<listitem>
<para>
Do not use commands as verbs.
</para>
</listitem>
</varlistentry>
<varlistentry id="vle-contractions">
<term>Contractions</term>
<listitem>
<para>
Do not use contractions such as <emphasis>can't</emphasis>,
<emphasis>don't</emphasis>, or <emphasis>isn't</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Dash</term>
<listitem>
<para>
Do not use the em dash or the en dash. Use a paragraph
break or a colon instead, where you want to create an
introductory piece of text. If you have several items that
you want to introduce, then you can use a variable list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Ellipsis</term>
<listitem>
<para>
Use an ellipsis in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To show that you have omitted something from a sentence
</para>
</listitem>
<listitem>
<para>
To indicate a pause when you quote displayed text
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Fractions</term>
<listitem>
<para>
Follow these rules when using fractions:
</para>
<itemizedlist>
<listitem>
<para>
Use numerals for fractions in tables and in units of
measurement, but spell out fractions in prose.
</para>
</listitem>
<listitem>
<para>
Use a space between a numeral and a related fraction, if
there is a possible ambiguity. For example: 1 1/2
instead of 11/2.
</para>
</listitem>
<listitem>
<para>
If a fraction is used in a compound modifier, insert a
hyphen between the fraction and the unit of measurement.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Gender</term>
<listitem>
<para>
Refer to <xref linkend="sn-fundamentals-9"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Grammar</term>
<listitem>
<para>
Use standard American English grammar rules, refer to the
<citetitle>Chicago Manual of Style</citetitle> (<ulink
url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">
http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Headings</term>
<listitem>
<para>
Use the following capitalization rules in headings:
</para>
<itemizedlist>
<listitem>
<para>
Initial uppercase letter of the first word
</para>
</listitem>
<listitem>
<para>
Initial uppercase letter for all nouns, adjectives, and
verbs.
</para>
</listitem>
<listitem>
<para>
All lowercase letters for conjunctions, articles, and
prepositions of fewer than four letters
</para>
</listitem>
<listitem>
<para>
Initial uppercase letter for prepositions of four
letters or longer
</para>
</listitem>
<listitem>
<para>
Initial uppercase letter for conjunctions of four
letters or longer
</para>
</listitem>
</itemizedlist>
<!-- <para> See <xref linkend="infodesign-2"/> for more
information about headings. </para> -->
</listitem>
</varlistentry>
<varlistentry>
<term>Hyphen</term>
<listitem>
<para>
Use hyphens in the following situations:
</para>
<itemizedlist>
<listitem>
<para> With a numeral in a compound modifier
</para>
</listitem>
<listitem>
<para>
To prevent ambiguity
</para>
</listitem>
<listitem>
<para>
With some standard prefixes and suffixes. Use the
<citetitle>American Heritage Dictionary</citetitle>
(<ulink
url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>)
for guidance
</para>
</listitem>
<listitem>
<para>
In spelled-out fractions
</para>
</listitem>
<listitem>
<para>
In variable names of two or more words, such as
<replaceable>directory-name</replaceable>. Note:
<replaceable>filename</replaceable> is an exception.
</para>
</listitem>
</itemizedlist>
<para>
Do not use hyphens in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
For industry-accepted terms
</para>
</listitem>
<listitem>
<para>
To construct verbs
</para>
</listitem>
<listitem>
<para>
With an adverb ending in <emphasis>ly</emphasis>
</para>
</listitem>
<listitem>
<para>
With numerals as single modifiers
</para>
</listitem>
<listitem>
<para>
With a word that is listed as unhyphenated in the
<citetitle>American Heritage Dictionary</citetitle>
(<ulink
url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>),
and that uses a common prefix
</para>
</listitem>
<listitem>
<para>
With trademarked terms
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Latin terms</term>
<listitem>
<para>
Do not use Latin terms. Use an equivalent English term
instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Like</term>
<listitem>
<para>
Do not use the term <emphasis>like</emphasis> to denote
equivalence or similarity.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Lists</term>
<listitem>
<para>
Introduce a list with a complete sentence that ends with a
colon.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Numbers</term>
<listitem>
<para>
Spell out numbers in the following situations:
</para>
<itemizedlist>
<listitem>
<para> Numbers from zero through nine unless the number is
part of a measurement
</para>
</listitem>
<listitem>
<para>
Approximations
</para>
</listitem>
<listitem>
<para>
Extreme values such as <emphasis>million</emphasis>, but
precede the value with a numeral
</para>
</listitem>
<listitem>
<para>
Any number that begins a sentence
</para>
</listitem>
<listitem>
<para>
A number that is immediately followed by a numeral, for
example: <literal>two 10 MB files</literal>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Numerals</term>
<listitem>
<para>
Use numerals in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
The number 10 or greater
</para>
</listitem>
<listitem>
<para> Negative numbers
</para>
</listitem>
<listitem>
<para>
Most fractions
</para>
</listitem>
<listitem>
<para>
Percentages
</para>
</listitem>
<listitem>
<para>
Decimals
</para>
</listitem>
<listitem>
<para>
Measurements
</para>
</listitem>
<listitem>
<para>
Units of time smaller than one second
</para>
</listitem>
<listitem>
<para>
References to bits and bytes
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Parentheses</term>
<listitem>
<para>
Use parentheses in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To contain the abbreviation of a term on the first
occurrence of the full term
</para>
</listitem>
<listitem>
<para>
In man page references, specifically the section number
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Period</term>
<listitem>
<para>
Use a period in the following situations:
</para>
<itemizedlist>
<listitem>
<para>
To end a sentence
</para>
</listitem>
<listitem>
<para>
In file and directory names
</para>
</listitem>
<listitem>
<para>
In abbreviations that can be mistaken for words, such as
a.m. and U.S.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Punctuation</term>
<listitem>
<para>
Use standard American English punctuation rules. In
addition to the specific points of punctuation in this
section, refer also to the <citetitle>Chicago Manual of
Style</citetitle> (<ulink
url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Punctuation in numbers</term>
<listitem>
<para>
Do not use a comma in numerals of four digits. Use a comma
in numerals of more than four digits.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Quotation marks</term>
<listitem>
<para>
Use quotation marks to indicate material that is taken
verbatim from another source. Do not use quotation marks to
excuse terms from legitimacy. If the term is not
legitimate, then use another term. If you must use that
term, declare the term in the glossary and make the term
legitimate.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>See v. Refer to</term>
<listitem>
<para>
When referring a user to another resource, use "refer to"
instead of "see", and "refer also to" instead of "see also".
This differentiates from the <sgmltag
class="starttag">see</sgmltag> and <sgmltag
class="starttag">seealso</sgmltag> tags that are used in
indexing. These tags create special links in the index. To
be consistent throughout the document, we reserve the
special words "see" and "see also" for hyperlinked index
references, and use "refer to" and "refer also to" for
non-hyperlinked and non-indexed references.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Semicolon</term>
<listitem>
<para>
Do not use semicolons.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Slash</term>
<listitem>
<para>
Except where required as part of a filename, do not use
slashes "/" in your writing. The construction
<literal>and/or</literal>, for example, does not exist. Use
one or the other term instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Spelling</term>
<listitem>
<para>
Use standard American English spelling rules, refer to the
<citetitle>American Heritage Dictionary</citetitle> (<ulink
url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>)
for guidelines.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Titles</term>
<listitem>
<para>
For manual titles use the same rules as for headings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Units</term>
<listitem>
<para>
Follow these rules when using units:
</para>
<itemizedlist>
<listitem>
<para>
Use standard abbreviations for units of measurements, do
not invent your own abbreviations.
</para>
</listitem>
<listitem>
<para>
<!-- See <xref linkend="units"/> for a list of units
relevant to the GNOME Desktop. --> For further
guidelines, refer to the <citetitle>IEEE Standard
Dictionary of Electrical and Electronics
Terms</citetitle>.
</para>
</listitem>
<listitem>
<para>
Use periods for abbreviated units that might be mistaken
for a word.
</para>
</listitem>
<listitem>
<para>
Most standard abbreviations of units account for both
singular and plural usage.
</para>
</listitem>
<listitem>
<para>
Insert a space between the numeral and the unit of
measurement.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="sn-composition-tips">
<title>Composition Tips</title>
<!--
This section will collect miscellanea and advice for specific
situations that the FDP editors encounter. I hope they will feel
free to e-mail me sticky situations or particularly interesting
examples of work they've beautified. Hopefully not too much will be
drawn from my own work! - PWF.
-->
<para>
This section contains usage tips based on situations the &FDP;
editors have encountered in the past. You should read and
understand these examples to improve your own documentation. The
&FDP; editors welcome additional examples.
</para>
<section id="sn-misc-active-voice">
<title>Active Voice</title>
<para>
Always use active voice, except when it is awkward to do so. The
tutorial tells the user how to accomplish a task, and should
give instructions clearly and concisely. Avoid using "must,"
"need to," and the like. These words are redundant in a
tutorial, since the reader assumes you are outlining necessary
steps to accomplish a task. Also avoid using "maybe," "might,"
and other words that indicate you are unsure about the subject
matter. Your tutorial should cover a subject authoritatively.
The reader should never be concerned about unknown effects of
following the tutorial.
</para>
<example id="ex-misc-passive-voice">
<title>Incorrect: Passive voice</title>
<para>
The <command>yum update</command> command must be run.
</para>
<para>
You might want to run the <command>yum update</command>
command.
</para>
</example>
<example id="ex-misc-active-voice">
<title>Correct: Active voice</title>
<para>
Run the <command>yum update</command> command.
</para>
</example>
</section>
<section id="sn-present-tense">
<title>Present Tense</title>
<para>
Write in the present tense. A good rule of thumb is that the
words "will" and "shall" are almost never needed in describing
what the user should do or see. They add unnecessary length to
sentences and can confuse translators. They are also often
indicators of passive voice; refer also to <xref
linkend="sn-misc-active-voice"/>.
</para>
<example id="ex-misc-future-tense">
<title>Incorrect: Future tense</title>
<para>
The application will display a list of target files.
</para>
<para>
A list of target files will be displayed by the application.
</para>
</example>
<example id="ex-misc-present-tense">
<title>Correct: Present tense</title>
<para>
The application displays a list of target files.
</para>
</example>
</section>
<section id="sn-narrative-voice">
<title>Narrative Voice</title>
<para>
Do not use the first person "I," "we," or "us" to refer to
yourself the writer (whether including the reader or not), the
&FDP;, the &FED; community, or any other group. Do not refer to
users with a third person pronoun ("he," "she," or "he or she")
or the word "one." It is acceptable to refer to the reader with
the second person pronoun "you."
</para>
<example id="ex-misc-wrong-person">
<title>Incorrect: First or third person</title>
<para>
As described in the last section, I always run
<command>up2date</command> before configuring the Samba
server.
</para>
<para>
If the user needs to back up his or her files, s/he should use
the <command>tar</command> or <command>cpio</command> command.
</para>
</example>
<example id="ex-misc-correct-person">
<title>Correct: Second (or no) person</title>
<para>
Refer to the section on <command>up2date</command> before
configuring the Samba server.
</para>
<para>
If necessary, users can back up files with the
<command>tar</command> or <command>cpio</command> command.
</para>
</example>
</section>
<section id="sn-misc-negative">
<title>Negative Words</title>
<para>
Avoid negative words when possible, since they give
documentation an overly dogmatic tone. The word "avoid" is
useful for this purpose. Note that contractions are often used
for negative words such as <emphasis>don't</emphasis> or
<emphasis>can't</emphasis>. Refer to <xref
linkend="vle-contractions" />.
</para>
</section>
<section id="sn-misc-uncertainty">
<title>Uncertainty</title>
<para>
Avoid overuse of "typically," "usually," "most of," "many," and
the like. While occasional use of these constructions is
acceptable, overuse reduces the authority of your documentation.
The documentation should adequately cover a stock installation
of &FC;. It is impossible for a tutorial-length document to
cover every possible configuration scenario. Address the most
common scenarios and note discrepancies only as required.
</para>
</section>
<section id="sn-misc-offtopic">
<title>Redundant Coverage</title>
<para>
Avoid covering redundant material, such as how to update a &FC;
system. These overarching topics may be covered in other
tutorials. Writers frequently violate this guideline because
they feel their tutorial is not long enough. Keep your tutorial
from wandering off-topic. Instead, refer the reader to a
separate tutorial whenever possible for complete coverage of
that topic.
</para>
</section>
<section id="sn-misc-importance">
<title>Self-referential Value Judgments</title>
<para>
Avoid statements such as "One of the most important things to do
is <replaceable>XYZ</replaceable>." If the procedure is
important, the reader already expects it to be in your tutorial.
The converse is also true: If a procedure appears in your
tutorial, the reader expects it is important. This is
especially true if you use a whole section for the procedure in
question. Merely state, "Do <replaceable>XYZ</replaceable>."
Then elaborate as required. If the whole section concerns how
to do <replaceable>XYZ</replaceable>, leave this sentence out
entirely. Refer also to <xref linkend="vle-golden-rule-4" />.
</para>
</section>
<section id="sn-misc-precision">
<title>Precision of Language</title>
<para>
Use precise words for actions users should take. Do not
instruct users to "go" to a selection, or "find" a menu.
</para>
<example id="ex-precision-wrong">
<title>Incorrect: Imprecise wording</title>
<itemizedlist>
<listitem>
<para>
Go to the <guimenu>Main Menu</guimenu> ->
<guimenuitem>Foobar</guimenuitem>
</para>
</listitem>
<listitem>
<para>
Find the option labeled <guilabel>Search</guilabel>
</para>
</listitem>
</itemizedlist>
</example>
<example id="ex-precision-right">
<title>Correct: Precise wording</title>
<itemizedlist>
<listitem>
<para>
From the <guimenu>Main Menu</guimenu>, select
<guimenuitem>Foobar</guimenuitem>
</para>
</listitem>
<listitem>
<para>
Select the <guilabel>Search</guilabel> option
</para>
</listitem>
</itemizedlist>
</example>
<important>
<title>Do Not Discriminate Against Non-GUI Users</title>
<para>
If you are writing about a GUI-only application, you may use
"click" freely. If you are writing about an application that
has a text-mode interface, use "select" instead as shown
above.
</para>
</important>
</section>
<section id="sn-misc-docbook-tips">
<title>DocBook Tips</title>
<para>
This section contains tips on how to use DocBook tags more
effectively in your documentation.
</para>
<section id="sn-misc-admonitions">
<title>Admonitions</title>
<para>
Avoid overuse of admonitions. Keep admonitions short and
effective by using only the most important material inside the
admonition. Move any background material required to explain
the admonition statements outside the admonition. Use a short
but descriptive title for an admonition. Use title case for
the admonition title.
</para>
<example id="ex-misc-ineffective-admonition">
<title>Incorrect: Lengthy admonition</title>
<para>
<warning>
<title>Use <command>sfdisk</command> to check input</title>
<para>
The <command>sfdisk</command> command accepts a script
file as standard input to set up partitions on a hard
disk. Sometimes <command>sfdisk</command> will simply
reject an erroneous input file. In other cases, it will
use the input verbatim, writing an incorrect partition
table to your disk. Always use the <command>sfdisk
-n</command> command to check your input file before
writing to the disk.
</para>
</warning>
</para>
</example>
<example id="ex-misc-good-admonition">
<title>Correct: Brief admonition</title>
<para>
The <command>sfdisk</command> command accepts a script
file as standard input to set up partitions on a hard disk.
Sometimes <command>sfdisk</command> will simply reject an
erroneous input file. In other cases, it will use the input
verbatim, writing an incorrect partition table to your disk.
<warning>
<title>Check Input</title>
<para>
Always use the <command>sfdisk -n</command> command to
check your input file before writing to the disk.
</para>
</warning>
</para>
</example>
<para>
Avoid punctuation in titles for sections or admonitions,
except for commas only where demanded. Use a title that says
something about the admonition comment, such as "Reboot
Required," instead of simply using the admonition type for a
title ("Note").
</para>
<para>
Follow the capitalization rules for headings in the title of
an admonition.
</para>
</section>
<section id="sn-misc-replaceable">
<title>The <sgmltag class="starttag">replaceable</sgmltag>
Tag</title>
<para>
If your documentation formally states a specific value will be
used as a convention, do not use the <sgmltag
class="starttag">replaceable</sgmltag> tag in your text or
examples.
</para>
</section>
<section id="sn-misc-entities">
<title>XML Entities</title>
<para>
Use the entities provided by the &FDP;. These entities are
found in the <filename>common/</filename> folder in the
<filename>fedora-docs</filename> distribution. (Refer also to
<xref linkend="ch-getting-files"/>.) For instance, do not use
abbreviations such as "FC2." Instead, use the predefined
entities "&FC; &FCVER;," which produces the text "&FC;
&FCVER;."
</para>
</section>
</section>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
fill-column: 72
End:
-->
***** Error reading new file: [Errno 2] No such file or directory: 'tutorial.xml'
***** Error reading new file: [Errno 2] No such file or directory: 'vim.xml'
***** Error reading new file: [Errno 2] No such file or directory: 'writing-guidelines.xml'
***** Error reading new file: [Errno 2] No such file or directory: 'xml-tags.xml'
Index: documentation-guide.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/documentation-guide.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- documentation-guide.xml 17 Dec 2006 00:41:55 -0000 1.4
+++ documentation-guide.xml 3 Feb 2007 22:21:58 -0000 1.5
@@ -17,43 +17,43 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="fdp-info.xml" />
<!-- INTRODUCTION -->
- <xi:include href="docs-intro.xml" xpointer="element(ch-intro)"
+ <xi:include href="intro.xml" xpointer="element(ch-intro)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- GETTINGFILES -->
- <xi:include href="docs-getting-files.xml" xpointer="element(ch-getting-files)"
+ <xi:include href="getting-files.xml" xpointer="element(ch-getting-files)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- HOWMODULESWORK -->
- <xi:include href="docs-module-struct.xml"
+ <xi:include href="module-struct.xml"
xpointer="element(ch-how-modules-work)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- GUIDELINES -->
- <xi:include href="docs-rh-guidelines.xml" xpointer="element(ch-rh-guidelines)"
+ <xi:include href="rh-guidelines.xml" xpointer="element(ch-rh-guidelines)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- EMACS -->
- <xi:include href="docs-emacs.xml" xpointer="element(ch-emacs)"
+ <xi:include href="emacs.xml" xpointer="element(ch-emacs)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- EMACS-NXML -->
<!-- This chapter needs editing, so we're excluding it now. -->
<!--
- <xi:include href="docs-emacs-nxml.xml" xpointer="element(ch-emacs-nxml)"
+ <xi:include href="emacs-nxml.xml" xpointer="element(ch-emacs-nxml)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-->
<!-- VIM -->
- <xi:include href="docs-vim.xml" xpointer="element(ch-vim)"
+ <xi:include href="vim.xml" xpointer="element(ch-vim)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- TAGS -->
- <xi:include href="docs-xml-tags.xml" xpointer="element(ch-xml-tags)"
+ <xi:include href="xml-tags.xml" xpointer="element(ch-xml-tags)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- TUTORIAL -->
- <xi:include href="docs-tutorial.xml" xpointer="element(ch-tutorial)"
+ <xi:include href="tutorial.xml" xpointer="element(ch-tutorial)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- CVS -->
--- docs-emacs-nxml.xml DELETED ---
--- docs-emacs.xml DELETED ---
--- docs-getting-files.xml DELETED ---
--- docs-intro.xml DELETED ---
--- docs-module-struct.xml DELETED ---
--- docs-rh-guidelines.xml DELETED ---
--- docs-style.xml DELETED ---
--- docs-tutorial.xml DELETED ---
--- docs-vim.xml DELETED ---
--- docs-xml-tags.xml DELETED ---
More information about the Fedora-docs-commits
mailing list