## 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: this emphasis will not be parsed]]> 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. Use: Non-GUI commands, daemons, etc. Any executable. Also options to commands and partial commands Example: The ls command lists files in a directory Example: The -l options to ls returns a long listing Example: You can list, copy, format, and otherwise manipulate the media, using DOS commands preceded by an m (mcopy, mdir, mdel, etc). Consult the mtools man page for more information. Use: The name of an application, usually a GUI app, as opposed to the command that runs it Example: You can also run Firefox by typing firefox at the command line. Use: Any non-executable filename or the full path to an executable being treated like an ordinary file. can be nested within where appropriate. Example: Try running ls -l on /bin/sh Example: Try running ls -l /bin/sh Use: Used like , but for multi-line output including CLI sessions, command output and file listings. Note that newlines are included as part of the , so the tags should not be proceeded or preceeded by newlines. This decreases legibility but avoids the inclusion extra lines before and after output. is also sensitive to whitespace, so output should not be indented. Example: The /etc/resolv.conf file contains DNS information: search example.com nameserver 192.168.0.254 , and Use: Used within 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 for file listings unless they are presented as the output of cat or similar. For file snippets, just use as in its example. Note: Remember that since counts whitespace you should not use unneccesary tabbing or newlines in your markup. Example: Here is a basic example of the ps command: [student@stationX]$ ps PID TTY TIME CMD 12856 pts/0 00:00:01 bash 22704 pts/0 00:00:00 ps and Use: denotes a keypress and 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 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 Escape key to exit the dialogue. Example: Use Ctrlx to cut the selected text. Example: Use Ctrlx, Ctrls to save. Example: Esc,. recalls the last argument to the previous command in bash. , , and Use: Used to denote a selection from a graphical menu Example: To run Firefox, navigate to ApplicationsInternet Web Browser. 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 instead. Example: You can change to your home directory by typing the cd /home/login_name command. and Use: Used to point out specific parts of a large chunk of text Example: [student@stationX ~]$ ls -l /etc/passwd -rw-r--r-- 1 root root 3872 Aug 4 18:03 /etc/passwd Let's take a closer look at the output of this command: The "mode" of the file represents its permissions and fundamental file type. The user and group associated with this file. Note: The tag with the id "mode" would be labeled (1). The tag using areafs="mode" would also display as a (1). "ugid" would be (2) and so forth. ,
and 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 brads@redhat.com text Users and groups can be managed with system-config-users The system-config-users tool allows you to configure authentication using an easy graphical interface. If you are not in X, system-config-users will use its simpler, text-mode interface:
system-config-users in text mode
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. Use: Used to emphasize a new term when it is introduced Example: Disk drives are divided into partitions. Partitions are formatted with filesystems, allowing users to store data.
Use: Multi-line quotations (single-line quotations should use ordinary text within double-quotes) Example: The chattr man page includes the following warnings:
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. The ‘j’ option is only useful if the filesystem is mounted as ext3. The ‘D’ option is only useful on Linux kernel 2.5.19 and later.
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. Use: Used in conjunction with for passwords Example: Login using the username student and the password student. # vi: se ai sm tw=72 ts=4