XML style guide
Brad Smith
brads at redhat.com
Fri Sep 16 04:05:28 UTC 2005
For your reference, here is the rough styleguide that we have devised
for forthcoming docbook-based GLS courseware. Much of the feedback I've
gotten from this list has been integrated into it (though there are a
few bits that should probably be revised and it needs to be converted
from text to docbook). If it is of any assistance, please use it. If
not, feel free to comment. Either way, as you say, we should work toward
as standardized a style as possible within Red Hat, Fedora Docs and
related projects.
--Brad
-------------- next part --------------
## GLS Style Guide, $Id: gls-styleguide.txt,v 1.12 2005/09/08 20:21:38 brads Exp $
##
## DO NOT edit this document unless you are or have consulted brads,
## kupferer and/or ralphr!
##
While editing
=============
Set tabstop to four:
set ts=4
Set page width to 72 when editing notes:
set tw=72
Set page width to zero when editing slides:
set tw=0
Terms
==============
Use chrooted, chmodded, chgrped, etc. Not chroot'd chroot'ed, etc.
Substitutions to be aware of
==============
Certain metacharacters will break the xml parser. Be
sure to use the following substitutions:
& instead of '&'
< instead of a literal '<'
> instead of a literal '>'
If you want to print a markup tag without it being interpreted,
use CDATA eg:
<![CDATA[<emphasis>this emphasis will not be parsed</emphasis>]]>
Supported tags
==============
The GLS tagset, is a subset of those currently being used by the
Fedora Documentation Project, which is currently being adapted into the
basis of a Red Hat wide style guide. For more information on any tag
mentioned below, see chapter 6 of the Fedora Documentation Guide:
http://fedora.redhat.com/participate/documentation-guide/
Tags listed there but not in this document may be considered, but email
the people listed at the top of this document first. Modificatin of the
GLS dtd and/or course munger libs may be necessary to add support. Also,
we would like to keep the tagset as small as possible so as to avoid
ambiguity.
Below is a list of currently supported tags and where/how to use them.
<command>
Use:
Non-GUI commands, daemons, etc. Any executable. Also
options to commands and partial commands
Example:
The <command>ls</command> command lists files in a
directory
Example:
The <command>-l</command> options to
<command>ls</command> returns a long listing
Example:
You can list, copy, format, and otherwise manipulate the
media, using DOS commands preceded by an
<command>m</command> (<command>mcopy</command>,
<command>mdir</command>, <command>mdel</command>, etc).
Consult the <command>mtools</command> man page for more
information.
<application>
Use:
The name of an application, usually a GUI app, as
opposed to the command that runs it
Example:
You can also run <application>Firefox</application> by
typing <command>firefox</command> at the command line.
<filename>
Use:
Any non-executable filename or the full path to an
executable being treated like an ordinary file.
<filename> can be nested within <command> where
appropriate.
Example:
Try running <command>ls -l</command> on
<filename>/bin/sh</filname>
Example:
Try running <command>ls -l
<filename>/bin/sh</filename></command>
<screen>
Use: Used like <para>, but for multi-line output including
CLI sessions, command output and file listings. Note
that newlines are included as part of the <screen>, so
the tags should not be proceeded or preceeded by
newlines. This decreases legibility but avoids
the inclusion extra lines before and after output.
<screen> is also sensitive to whitespace, so output
should not be indented.
Example:
<para>
The <filename>/etc/resolv.conf</filename> file contains
DNS information:
</para>
<screen>search example.com
nameserver 192.168.0.254</screen>
</para>
<prompt>, <userinput> and <computeroutput>
Use: Used within <screen> to denote shell prompts, user
commands and command output, respectively, within a CLI
session.
Note: Prompts should always use [student at stationX ~]$ or
[root at stationX ~]# unless another user, host or CWD is
required for the example.
Note: Do not use <computeroutput> for file listings unless
they are presented as the output of cat or similar. For
file snippets, just use <screen> as in its example.
Note: Remember that since <screen> counts whitespace you
should not use unneccesary tabbing or newlines in your
markup.
Example:
<para>
Here is a basic example of the <command>ps</command>
command:
</para>
<screen><prompt>[student at stationX]$</prompt> <userinput>ps</userinput>
<computeroutput>PID TTY TIME CMD
12856 pts/0 00:00:01 bash
22704 pts/0 00:00:00 ps</computeroutput></screen>
<keycombo> and <keycap>
Use: <keycap> denotes a keypress and <keycombo> combines a
number of keypresses
Note: For key combos that involve separate keypresses, as
opposed to holding one key while pressing another (eg
"ESC, period" in bash or "Ctrl+x, Ctrl+s" in emacs)
elements should be separated by a comma and the set of
elements should not be included in a <keycombo>
Note: Non-printing keys (Ctrl, Alt, Esc, etc) should have only
the first letter of each word in the name capitalized eg
PgUp, PrnScn, Tab, Caps Lock, etc. Printing keys
(alphanumerics, symbols, etc) should never be
capitalized. Treat Ctrl+X as Ctrl+Shift+x.
Note: When referenced by themselves, keys should use their
full name, e.g., Return or Escape. When referenced in
key combos, keys should use the following abbreviations:
Escape: Esc
Enter: Enter
Tab: Tab
Caps Lock: CapsLock
Shift: Shift
Control: Ctrl
Alt: Alt
Backspace: BkSpc
Insert: Ins
Home: Home
End: End
Del: Del
Page Up: PgUp
Page Down: PgDn
Num Lock: NumLck
Up Arrow: Up
Down Arrow: Down
Left Arrow: Left
Right Arrow: Right
Example:
Press the <keycap>Escape</keycap> key to exit the
dialogue.
Example:
Use
<keycombo><keycap>Ctrl</keycap><keycap>x</keycap></keycombo>
to cut the selected text.
Example:
Use
<keycombo><keycap>Ctrl</keycap><keycap>x</keycap></keycombo>,
<keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
to save.
Example:
<keycap>Esc</keycap>,<keycap>.</keycap> recalls the last
argument to the previous command in bash.
<menuchoice>, <guimenu>, <guisubmenu> and <guimenuitem>
Use: Used to denote a selection from a graphical menu
Example:
To run <application>Firefox</application>, navigate to
<menuchoice><guimenu>Applications</guimenu><guisubmenu>Internet</guisubmenu><guimenuitem>
Web Browser</guimenuitem></menuchoice>.
<replaceable>
Use: Used in place of <> to denote a variable.
Note: DO NOT use "<" or ">" as they will break docbook
parsing. Also, do not use < or >. Use
<replaceable> instead.
Example:
You can change to your home directory by typing the
<command>cd
/home/<replaceable>login_name</replaceable></command>
command.
<callout> and <co>
Use: Used to point out specific parts of a large chunk of
text
Example:
<screen><prompt>[student at stationX ~]$</prompt> <userinput>ls -l /etc/passwd</userinput>
<co id="mode"/>-rw-r--r-- 1 <co id="ugid"/>root root <co id="size"/>3872 <co id="tstamp"/>Aug 4 18:03 <co id="name"/>/etc/passwd
</screen>
<para>
Let's take a closer look at the output of this command:
<calloutlist>
<callout areafs="mode"><para>
The "mode" of the file represents its
permissions and fundamental file type.
</para></callout>
<callout areafs="ugid"><para>
The user and group associated with this
file.
</para></callout>
</calloutlist>
</para>
Note: The <co> tag with the id "mode" would be labeled (1).
The <callout> tag using areafs="mode" would also display
as a (1). "ugid" would be (2) and so forth.
<graphic>, <figure> and <title>
Use: Used for images. <graphic> defines the actual image
using its "fileref" attribute. <figure> is an optional
wrapper around <graphic> that includes a <title> block
along with the image. Other tags, such as <command> or
<filename> should not be embedded in the <title>
Note: Coursemunger currently auto-translates images into the
appropriate format for a given presentation format
(html, xslfo, etc), so generally a single reference to
an image, ideally png, is adequate.
Note: The next rev of docbook will be moving to <mediaobject>
instead of <graphic>. However, by then cm-xml may have
moved into an intermediary language that xslt will
translate into Red Hat standard docbook, so courseware
authors may never have to address this. In the mean time
we use <graphic> because coursemunger interprets it
specially.
Example:
<page>
<title>Configuring Authentication Graphically</title>
<owner>brads at redhat.com</owner>
<slide_type>text</slide_type>
<slide>
<itemizedlist>
<listitem>Users and groups can be managed with system-config-users</listitem>
</itemizedlist>
<graphic fileref=screenshot-sys-config-users/>
</slide>
<notes>
<para>
The <command>system-config-users</command>
tool allows you to configure authentication
using an easy graphical interface. If you are
not in X,
<command>system-config-users</command> will
use its simpler, text-mode interface:
</para>
<para>
<figure>
<title>
system-config-users in text mode
</title>
<graphic fileref=screenshot_sys-config-users_nox/>
</figure>
</para>
</notes>
</page>
<table> and related tags:
Use: Tabular data (duh). Tables MUST have a width value
specified as a percentage of the screen. For full
documentation see the FDP style guide and/or
http://www.docbook.org/tdg/en/html-ng/table.html
Example:
Just reproducing our ubiquitous "Classroom Network"
slide in docbook seems irritatingly complicated. I'll
figure it out later.
<firstterm>
Use: Used to emphasize a new term when it is introduced
Example:
<para>
Disk drives are divided into
<firstterm>partitions</firstterm>. Partitions are
formatted with <firstterm>filesystems</firstterm>,
allowing users to store data.
</para>
<blockquote>
Use: Multi-line quotations (single-line quotations should use
ordinary text within double-quotes)
Example:
<para>
The <command>chattr</command> man page includes the
following warnings:
</para>
<blockquote>
<para>
The ?c?, ?s?, and ?u? attributes are not honored
by the ext2 and ext3 filesystems as implemented
in the current mainline Linux kernels. These
attributes may be implemented in future versions
ext2 and ext3.
</para>
<para>
The ?j? option is only useful if the filesystem
is mounted as ext3.
</para>
<para>
The ?D? option is only useful on Linux kernel
2.5.19 and later.
</para>
</blockquote>
<code>
Use: Catch-all for any proper noun or other keyword not
defined elsewhere in this document: hostnames, domains,
selinux contexts, icon and menu names, etc.
<emphasis>
Use: Used in conjunction with <code> for passwords
Example:
Login using the username <code>student</code> and the
password <code><emphasis>student</emphasis></code>.
# vi: se ai sm tw=72 ts=4
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050916/885d1685/attachment.bin
More information about the docs
mailing list