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 '&' < 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@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 < 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@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
