Re: XML style guide

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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
##  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 '&'
&lt; 	instead of a literal '<'
&gt; 	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@stationX ~]$ or
		[root@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@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 &lt; or &gt. 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@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@xxxxxxxxxx</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

Attachment: signature.asc
Description: This is a digitally signed message part

-- 

fedora-docs-list@xxxxxxxxxx
To unsubscribe: 
http://www.redhat.com/mailman/listinfo/fedora-docs-list

[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux