documentation-guide/en_US writing-guidelines.xml,1.5,1.6
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sun Feb 18 22:59:21 UTC 2007
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv26927
Modified Files:
writing-guidelines.xml
Log Message:
Some retagging and deconfusification
Index: writing-guidelines.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/writing-guidelines.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- writing-guidelines.xml 18 Feb 2007 14:24:33 -0000 1.5
+++ writing-guidelines.xml 18 Feb 2007 22:59:19 -0000 1.6
@@ -46,18 +46,9 @@
<primary>naming conventions</primary>
</indexterm>
- <para>This section explains the ID naming convention. For
- example:</para>
-
- <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">
-
-<section id="sn-install-make-disks">
-
-<figure id="fig-redhat-config-kickstart-basic">]]></screen>
-
- <para>IDs are unique identifiers, allowing DocBook XML to know where
- to cross-reference a section, chapter, or other element. The
- following general rules apply to IDs:</para>
+ <para>This section explains the ID naming convention. IDs are
+ unique identifiers that allow DocBook XML to cross-reference a
+ section, chapter, or other element.</para>
<indexterm>
<primary>XML tags</primary>
@@ -68,19 +59,40 @@
<primary>naming conventions</primary>
<secondary>rules for defining an ID</secondary>
</indexterm>
-
- <para>Keep it as short and simple as possible.</para>
- <para>Start the ID with the special short two-character label. This
- makes URLs and other references to this ID human readable, by
- self-identifying the XML container type.</para>
+ <para>The following general rules apply to IDs:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Keep an ID as short and simple as possible.</para>
+ </listitem>
+ <listitem>
+ <para>Start the ID with the special short two-character label.
+ This makes URLs and other references to this ID human
+ readable, by self-identifying the XML container type.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ <xref linkend="ex-id-usage"/> demonstrates some example ID
+ attributes used properly.
+ </para>
+
+ <example id="ex-id-usage">
+ <title>Proper ID Usage</title>
+ <screen><![CDATA[<chapter id="ch-unique-name-of-chapter">
+
+<section id="sn-install-make-disks">
+
+<figure id="fig-redhat-config-kickstart-basic">]]></screen>
+ </example>
<table id="tb-id-two-char-naming-conventions">
<title>Two-Character Naming Conventions</title>
<tgroup cols="2">
- <colspec colnum="1" colname="tag" colwidth="100"/>
- <colspec colnum="2" colname="prefix" colwidth="100"/>
+ <colspec colnum="1" colname="tag"/>
+ <colspec colnum="2" colname="prefix"/>
<thead>
<row>
<entry>Tag</entry>
@@ -124,17 +136,13 @@
</tgroup>
</table>
- <para>Use the title of the item as the ID. If your title is not
- unique, there is either a problem you need to fix (titles should
- be unique within a document), or it is part of a template and
- should reflect the containing chapter/section of the template. For
- example:</para>
+ <para>Use the title of the item as the ID. Make your titles unique
+ within a document to prevent conflicts. For example:</para>
<screen><![CDATA[<chapter id="ch-how-to-fold-laundry">
-<title>How To Fold Laundry</title>]]></screen>
-
- <screen><![CDATA[<section id="sn-folding-shirts">
-<title>Folding Shirts</title>]]></screen>
+ <title>How To Fold Laundry</title>
+ <section id="sn-folding-shirts">
+ <title>Folding Shirts</title>]]></screen>
<indexterm>
<primary>xml tags</primary>
@@ -320,17 +328,25 @@
<tertiary>important</tertiary>
</indexterm>
- <para>There are five types of admonitions in DocBook: Caution,
- Important, Note, Tip, and Warning. All of the admonitions have
- the same structure: an optional Title followed by paragraph-level
+ <para>There are five types of admonitions in DocBook: <sgmltag
+ class="element">caution</sgmltag>, <sgmltag
+ class="element">important</sgmltag>, <sgmltag
+ class="element">note</sgmltag>, <sgmltag
+ class="element">tip</sgmltag>, and <sgmltag
+ class="element">warning</sgmltag>. All of the admonitions have
+ the same structure: an optional <sgmltag
+ class="element">title</sgmltag> followed by paragraph-level
elements. The DocBook DTD does not impose any specific semantics
on the individual admonitions. For example, DocBook does not
- mandate that Warnings be reserved for cases where bodily harm can
- result.</para>
+ mandate that a <sgmltag class="element">warning</sgmltag> is
+ reserved for cases where bodily harm can result.</para>
<section id="sn-xml-notesetc">
- <title>Creating Notes, Tips, Cautions, Importants, and
- Warnings</title>
+ <title>Creating a <sgmltag class="element">note</sgmltag>,
+ <sgmltag class="element">tip</sgmltag>, <sgmltag
+ class="element">caution</sgmltag>, <sgmltag
+ class="element">important</sgmltag>, or <sgmltag
+ class="element">warning</sgmltag></title>
<indexterm>
<primary>XML tags</primary>
@@ -358,24 +374,27 @@
</indexterm>
<para>There are several ways to bring attention to text within a
- document. A <emphasis>Note</emphasis> is used to bring
+ document. A <emphasis><sgmltag
+ class="element">note</sgmltag></emphasis> is used to bring
additional information to the users' attention. A
- <emphasis>Tip</emphasis> is used to show the user helpful
- information or another way to do something. A
- <emphasis>Caution</emphasis> is used to show the user they must
- be careful when attempting a certain step. An
- <emphasis>Important</emphasis> tag set can be used to show the
- user a piece of information that should not be overlooked. While
- this information may not change anything the user is doing, it
- should show the user that this piece of information could be
- vital. A <emphasis>Warning</emphasis> is used to show the reader
- that their current setup will change or be altered, such as
- files being removed, and they should not choose this operation
- unless they are alright with the consequences.</para>
-
- <para>The following lines of code will show the basic setup for
- each case as mentioned above, along with an example of how it
- would be displayed in the HTML.</para>
+ <emphasis><sgmltag class="element">tip</sgmltag></emphasis> is
+ used to show the user helpful information or another way to do
+ something. A <emphasis><sgmltag
+ class="element">caution</sgmltag></emphasis> is used to show
+ the user they must be careful when attempting a certain step. An
+ <emphasis><sgmltag
+ class="element">important</sgmltag></emphasis> tag set can
+ be used to show the user a piece of information that should not
+ be overlooked. While this information may not change anything
+ the user is doing, it should show the user that this piece of
+ information could be vital. A <emphasis><sgmltag
+ class="element">warning</sgmltag></emphasis> is used to show
+ the reader that their current setup will change or be altered,
+ such as files being removed, and they should not choose this
+ operation unless they are alright with the consequences.</para>
+
+ <para>The following lines of code show the basic setup for each
+ case mentioned above, along with its appearance in HTML.</para>
<screen><![CDATA[<note>
<title>Note</title>
@@ -547,39 +566,56 @@
<term>Text Screenshot</term>
<listitem>
<para>Textual screen information is also useful for readers.
- If you use a graphical screenshot to illustrate a function,
- and the textual mode has identical functions, you should not
- include both, unless omitting either would make your
- description unclear. You should make your information
- generic over specific. Omit the username and machine
- information, and separate what the user types from sample
- command output. Also, in <command>screen</command> tags,
- what the user types should be in
- <command>userinput</command> tags, and what the user is
- shown as output should be in
- <command>computeroutput</command> tags. For example, the
- usage in
- <xref linkend="ex-text-screenshot-bad"/> should look like
- <xref
- linkend="ex-text-screenshot-good"/>.
+ Follow these guidelines for textual screenshots:</para>
+ <itemizedlist>
+ <listitem>
+ <para>If you use a graphical screenshot to illustrate a
+ function, and the textual mode has identical functions,
+ do not include both, unless omitting either would make
+ your description unclear.</para>
+ </listitem>
+ <listitem>
+ <para>Make your information generic over specific, and
+ omit any username and machine information if possible.
+ Do not include the shell prompt unless it is vital to
+ the demonstration.</para>
+ </listitem>
+ <listitem>
+ <para>Separate what the user types from sample command
+ output.</para>
+ </listitem>
+ <listitem>
+ <para>When using <sgmltag class="element">screen</sgmltag>
+ to demonstrate a procedure, use <sgmltag
+ class="element">userinput</sgmltag> tags to show what
+ the user types, and use <sgmltag
+ class="element">computeroutput</sgmltag> tags to show
+ the resulting output.</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <xref linkend="ex-text-screenshot-good"/> is an example of
+ textual screenshot usage.
</para>
- <example id="ex-text-screenshot-bad">
- <title>Incorrect Textual Screenshot</title>
- <screen><userinput>ps ax | grep ssh</userinput>
-<computeroutput> 2564 ? S 0:23 /usr/sbin/sshd
- 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
- 8235 ? S 0:00 ssh -Nf rocky at philadelphia.net -L 6667:localhost
-17223 pts/0 S 0:00 ssh rbalboa at core-router7
-17227 pts/2 S 0:10 ssh rbalboa at smbshare2
-21113 pts/7 S 1:19 ssh rocky at xxx.private</computeroutput></screen>
- </example>
<example id="ex-text-screenshot-good">
- <title>Correct Textual Screenshot</title>
+ <title>Correct Textual Screenshot (XML Source and
+ HTML)</title>
+ <screen><![CDATA[<example id="ex-text-screenshot-good">
+ <title>Correct Textual Screenshot</title>
+ <para>To find all the currently active ssh sessions,
+ execute the following command:</para>
+ <screen><userinput>ps ax | grep ssh</userinput></screen>
+ <para>Output appears similar to the following:</para>
+ <screen><computeroutput> 2564 ? S 0:23 /usr/sbin/sshd
+ 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
+ 8032 pts/0 S 0:00 ssh user at host.example.com
+ 8032 pts/1 S 0:00 ssh root at backup.example.com</computeroutput></screen>
+</example>]]></screen>
<para>To find all the currently active ssh sessions, execute the
following command:</para>
- <screen><command>ps ax | grep ssh</command></screen>
+ <screen><userinput>ps ax | grep ssh</userinput></screen>
- <para>The output will appear similar to:</para>
+ <para>Output appears similar to the following:</para>
<screen><computeroutput> 2564 ? S 0:23 /usr/sbin/sshd
3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
More information about the docs-commits
mailing list