From f10317a442d418d07ce934797abfa1e91eb955d8 Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Sun, 18 Feb 2007 22:59:19 +0000 Subject: Some retagging and deconfusification --- en_US/writing-guidelines.xml | 198 +++++++++++++++++++++++++------------------ 1 file changed, 117 insertions(+), 81 deletions(-) diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml index 324aed0..6249a11 100644 --- a/en_US/writing-guidelines.xml +++ b/en_US/writing-guidelines.xml @@ -46,18 +46,9 @@ naming conventions - This section explains the ID naming convention. For - example: - - - -
- -
]]> - - 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: + This section explains the ID naming convention. IDs are + unique identifiers that allow DocBook XML to cross-reference a + section, chapter, or other element. XML tags @@ -68,19 +59,40 @@ naming conventions rules for defining an ID - - Keep it as short and simple as possible. - 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. + The following general rules apply to IDs: + + + + Keep an ID as short and simple as possible. + + + 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. + + + + + demonstrates some example ID + attributes used properly. + + + + Proper ID Usage + + +
+ +
]]> + Two-Character Naming Conventions - - + + Tag @@ -124,17 +136,13 @@
- 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: + Use the title of the item as the ID. Make your titles unique + within a document to prevent conflicts. For example: -How To Fold Laundry]]> - - -Folding Shirts]]> + How To Fold Laundry +
+ Folding Shirts]]> xml tags @@ -254,7 +262,7 @@ committed to CVS) the line is updated automatically to include information about the file. For example: - ]]> + ]]>
@@ -320,17 +328,25 @@ important - 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 + 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 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. + mandate that a warning is + reserved for cases where bodily harm can result.
- Creating Notes, Tips, Cautions, Importants, and - Warnings + 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> XML tags @@ -358,24 +374,27 @@ There are several ways to bring attention to text within a - document. A Note is used to bring + document. A note is used to bring additional information to the users' attention. A - Tip is used to show the user helpful - information or another way to do something. A - Caution is used to show the user they must - be careful when attempting a certain step. An - Important 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 Warning 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. - - 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. + tip is + used to show the user helpful information or another way to do + something. A caution is used to show + the user they must be careful when attempting a certain step. An + important 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 warning 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. + + The following lines of code show the basic setup for each + case mentioned above, along with its appearance in HTML. Note @@ -547,39 +566,56 @@ Text Screenshot 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 screen tags, - what the user types should be in - userinput tags, and what the user is - shown as output should be in - computeroutput tags. For example, the - usage in - should look like - . + Follow these guidelines for textual screenshots: + + + 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. + + + 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. + + + Separate what the user types from sample command + output. + + + When using screen + to demonstrate a procedure, use userinput tags to show what + the user types, and use computeroutput tags to show + the resulting output. + + + + is an example of + textual screenshot usage. - - Incorrect Textual Screenshot - ps ax | grep ssh - 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@philadelphia.net -L 6667:localhost -17223 pts/0 S 0:00 ssh rbalboa@core-router7 -17227 pts/2 S 0:10 ssh rbalboa@smbshare2 -21113 pts/7 S 1:19 ssh rocky@xxx.private - - Correct Textual Screenshot + Correct Textual Screenshot (XML Source and + HTML) + + Correct Textual Screenshot + To find all the currently active ssh sessions, + execute the following command: + ps ax | grep ssh + Output appears similar to the following: + 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@host.example.com + 8032 pts/1 S 0:00 ssh root@backup.example.com +]]> To find all the currently active ssh sessions, execute the following command: - ps ax | grep ssh + ps ax | grep ssh - The output will appear similar to: + Output appears similar to the following: 2564 ? S 0:23 /usr/sbin/sshd 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients -- cgit