From 1bff601616263caee405d229d813790ce18a44fd Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Sat, 23 Dec 2006 23:49:59 +0000 Subject: Minor changes, major reformatting. Sorry about the noise. --- en_US/docs-rh-guidelines.xml | 966 ++++++++++++++++++++----------------------- en_US/docs-xml-tags.xml | 37 +- 2 files changed, 476 insertions(+), 527 deletions(-) diff --git a/en_US/docs-rh-guidelines.xml b/en_US/docs-rh-guidelines.xml index bc8b467..f243058 100644 --- a/en_US/docs-rh-guidelines.xml +++ b/en_US/docs-rh-guidelines.xml @@ -7,589 +7,529 @@ ]> - - &RH; Documentation Guidelines + + &RH; Documentation Guidelines - - recursion - recursion - + + recursion + recursion + - - RTFM - read the f*'ing manual - humor - + + RTFM + read the f*'ing manual + humor + - - humor - RTFM - + + humor + RTFM + - Please read this chapter carefully. This chapter describes the - guidelines that must be followed such as naming conventions. - + Please read this chapter carefully. This chapter describes the + guidelines that must be followed such as naming conventions. - - ID Naming Conventions + + ID Naming Conventions - - XML tags - naming conventions - + + XML tags + naming conventions + - - naming conventions - + + naming conventions + - You will see certain ID names referred to below and this will - help to explain how we come up with those names. For example: - + You will see certain ID names referred to below and this will + help to explain how we come up with those names. For + example: - - -<chapter id="ch-uniquename"> + -<sect3="s3-install-make-disks"> +
-<figure id="fig-redhat-config-kickstart-basic"> - - +
]]> - IDs are unique identifiers, allowing DocBook XML to know where to - cross-reference a section or chapter or the like. - - - The general rules for defining an ID are: + IDs are unique identifiers, allowing DocBook XML to know where + to cross-reference a section or chapter or the like. The + following general rules apply to IDs: - - XML tags - rules for defining an ID - + + XML tags + rules for defining an ID + - - naming conventions - rules for defining an ID - + + naming conventions + rules for defining an ID + - - - Keep it 32 characters or under (this is counted as - everything between the quotation marks) - - - Keep it as short and simple as possible - - - Make sure the name is relevant to the information (make it - recognizable) - - + + + Restrict the ID name, which is everything between the + quotation marks, to 32 characters or fewer + + + Keep it as short and simple as possible + + + Make sure the name is recognizable and relevant to the + information + + - Some examples are "ch-uniquename" (with 13 - characters) and "s3-install-make-disks" (with 21 - characters). - + Some examples are "ch-uniquename" (13 + characters) and "sn-install-make-disks" (21 + characters). + + A section within a particular chapter always uses the chapter + name (minus the "ch-") in its ID. For example, + you are working with the "ch-intro" chapter and + need to create your first section on disk partitions. That section + ID would look similar to "s1-intro-partition" + which contains the section number, the main chapter ID, and a + unique ID for that section. + + + Naming Conventions + + + + + + + Tag + Prefix + + + + + preface + pr- + + + chapter + ch- + + + section + sn- + + + sect1 + s1- + + + sect2 + s2- + + + sect3 + s3- + + + sect4 + s4- + + + figure + fig- + + + table + tb- + + + appendix + ap- + + + part + pt- + + + example + ex- + + + +
+ + + + + File Header - A section within a particular chapter always uses the chapter - name (minus the "ch-") in its ID. For example, you - are working with the "ch-intro" chapter and need to - create your first section on disk partitions. That section ID would look - similar to "s1-intro-partition" which contains the - section number, the main chapter ID, and a unique ID for that section. - + All the files must contain the CVS Id header. If you create a + new file, the first line must be: - - Naming Conventions - - - - - - - Tag - Prefix - - - - - preface - pr- - - - chapter - ch- - - - section - sn- - - - sect1 - s1- - - - sect2 - s2- - - - sect3 - s3- - - - sect4 - s4- - - - figure - fig- - - - table - tb- - - - appendix - ap- - - - part - pt- - - - example - ex- - - - -
- - - - - File Header - - - All the files must contain the CVS Id header. - + ]]> - - If you create a new file, the first line must be: - - - -<!-- $Id: --> - - - - - The first time it is committed to CVS (and every time it is committed to - CVS) the line is updated automatically to include information about the - file. For example: - + The first time it is committed to CVS (and every time it is + committed to CVS) the line is updated automatically to include + information about the file. For example: - - -<!-- $Id: docs-rh-guidelines.xml,v 1.2 2006/12/17 00:41:55 pfrields Exp $ --> - - + ]]> - + - - Admonitions + + Admonitions - - admonitions - + + admonitions + - - XML tags - warning - + + XML tags + warning + - - XML tags - tip - + + XML tags + tip + - - XML tags - note - + + XML tags + note + + + + XML tags + caution + + + + XML tags + important + + + + XML tags + admonitions + warning + - - XML tags - caution - + + XML tags + admonitions + tip + + + + XML tags + admonitions + note + + + + XML tags + admonitions + caution + - - XML tags - important - + + XML tags + admonitions + 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 + 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. + + + Creating Notes, Tips, Cautions, Importants, and + Warnings XML tags - admonitions - warning + note XML tags - admonitions - tip + tip XML tags - admonitions - note + caution XML tags - admonitions - caution + important XML tags - admonitions - important + warning - 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. - - - - Creating Notes, Tips, Cautions, Importants, and Warnings - - - XML tags - note - - - - XML tags - tip - - - - XML tags - caution - - - - XML tags - important - - - - XML tags - warning - - - There are several ways to bring attention to text within a - 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. - - - - -<note> -<title>Note</title> -<para>Body of text goes here.</para> -</note> - - - - - Note Body of text goes here. - - - - - -<tip> -<title>Tip</title> -<para>Body of text goes here.</para> -</tip> - - - - - Tip - Body of text goes here - - - - -<caution> -<title>Caution</title> -<para>Body of text goes here.</para> -</caution> - - - - - Caution Body of text goes here. - - - - - -<important> -<title>Important</title> -<para>Body of text goes here.</para> -</important> - - - - - Important - Body of text goes here. - + There are several ways to bring attention to text within a + 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. + + + Note + Body of text goes here. +]]> + + + Note + Body of text goes here. + + + + Tip + Body of text goes here. +]]> + + + Tip + Body of text goes here + + + + Caution + Body of text goes here. +]]> + + + Caution + Body of text goes here. + + + + Important + Body of text goes here. +]]> + + + Important + Body of text goes here. + - - -<warning> -<title>Warning</title> -<para>Body of text goes here.</para> -</warning> - - + + Warning + Body of text goes here. +]]> - - Warning Body of text goes here. - - + + Warning + Body of text goes here. + + - + - - Screenshots + + Screenshots - - screenshots - how to take - - - screen captures - screenshots - - - screen grabs - screenshots - + + screenshots + how to take + + + screen captures + screenshots + + + screen grabs + screenshots + - - There are two types of screenshots: graphical and textual. The - philosophy on using these two types is rely on text over - graphics. This means, if you can say it in text instead of - showing a graphic, do so. A graphical screenshot of a GUI can create a good - setting of objects to then describe textually, but you don't want to create - a screenshot for each graphical step. - - - The main reason for this preference is that a block of text can usually - convey more meaning than the same physical space of graphics. This is - highly dependent on the graphic; obviously, a photographic image of a - scene can convey more than 1000 words can. A GUI screenshot is usually - full of blank space with a few elements that can just as easily be - described or listed. - - - The steps for taking a graphical screenshot illustrate how using text to - describe a procedure is more concise than a series of screenshots. - - - - Graphical Screenshot - - - - - Set the theme to Bluecurve defaults. This gives a look that - is familiar to most readers, and makes &FDP; documents - consistent. From the panel menu, choose - Preferences, - Theme and select - Bluecurve from the theme list. - - - - - Set fonts to Bluecurve defaults as well. From the panel menu, - choose Preferences, - Fonts. Set the - Application font and the - Desktop font to Sans Regular 10. Set the - Window Title font to Sans Bold 10. Set - the Terminal font to Monospace Regular - 10. - - - - - Before taking the screenshot, try to resize the targeted GUI - element(s) to the smallest possible size they can be. Your - target is an image of 500 pixels or less. If you are doing a - screenshot of more than one GUI element, you may need to - resize the screenshot in a following step. - - - - - To take the screenshot, select the GUI element with your - mouse, bringing it to the forefront, or otherwise arranging - the elements. Press Alt - Print Screen to capture a single - GUI window. For capturing the entire desktop use - Print Screen. If you are taking a shot of - multiple elements and have grouped them closely together, you - can crop the resulting image in The - GIMP. The image will be in the PNG format. - - - - - If you need to, you can resize using The - GIMP. With the image open, right-click on it - and choose Image -> Scale - Image.... With the chain symbol intact, set the - New Width to 500 px, - and click OK. Be sure to - Ctrl s to save - your changes to your PNG before converting to EPS. - + There are two types of screenshots: graphical and textual. + The philosophy on using these two types is rely on text + over graphics. This means, if you can say it in + text instead of showing a graphic, do so. A graphical screenshot + of a GUI can create a good setting of objects to then describe + textually, but you don't want to create a screenshot for each + graphical step. + The main reason for this preference is that a block of text + can usually convey more meaning than the same physical space of + graphics. This is highly dependent on the graphic; obviously, a + photographic image of a scene can convey more than 1000 words can. + A GUI screenshot is usually full of blank space with a few + elements that can just as easily be described or listed. + The steps for taking a graphical screenshot illustrate how + using text to describe a procedure is more concise than a series + of screenshots. + + + Graphical Screenshot + + + + Set the theme to Bluecurve defaults. This gives a look + that is familiar to most readers, and makes &FDP; + documents consistent. From the panel menu, choose + Preferences, + Theme and select + Bluecurve from the theme + list. + + + Set fonts to Bluecurve defaults as well. From the + panel menu, choose Preferences, + Fonts. Set the + Application font and the + Desktop font to Sans Regular 10. + Set the Window Title font to Sans + Bold 10. Set the Terminal font to + Monospace Regular 10. + + + Before taking the screenshot, try to resize the + targeted GUI element(s) to the smallest possible size + they can be. Your target is an image of 500 pixels or + less. If you are doing a screenshot of more than one + GUI element, you may need to resize the screenshot in a + following step. + + + To take the screenshot, select the GUI element with + your mouse, bringing it to the forefront, or otherwise + arranging the elements. Press + Alt + Print Screen to capture a + single GUI window. For capturing the entire desktop use + Print Screen. If you are taking a shot + of multiple elements and have grouped them closely + together, you can crop the resulting image in + The GIMP. The image will be + in the PNG format. - - With the image open in The GIMP, - right-click on the image, selecting File - -> Save As.... Under - Determine File Type:, select - PostScript, then click - OK. Allow flattening of the image by - clicking Export. - - - In the Save as PostScript window, select - Encapsulated PostScript, and click - OK. - - - - - For more information about calling the images from the XML, refer - to . - - - - - 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 If you need to, you can resize using + The GIMP. With the image + open, right-click on it and choose + Image -> Scale + Image.... With the chain symbol intact, + set the New Width to 500 + px, and click OK. + Be sure to + Ctrl s + to save your changes to your PNG before converting to + EPS. + + + + With the image open in The + GIMP, right-click on the image, + selecting File -> + Save As.... Under + Determine File Type:, select + PostScript, then click + OK. Allow flattening of the image + by clicking Export. + In the Save as PostScript + window, select Encapsulated + PostScript, and click + OK. + + + For more information about calling the images from the + XML, refer to . + + + + 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 + . - - - Incorrect Textual Screenshot - -ps ax | grep ssh - - 2564 ? S 0:23 /usr/sbin/sshd + + + 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 - - To find all the currently active ssh sessions, execute the - following command: - - -ps ax | grep ssh - +21113 pts/7 S 1:19 ssh rocky@xxx.private + + + Correct Textual Screenshot + To find all the currently active ssh sessions, execute the + following command: + ps ax | grep ssh - - The output will appear similar to: - + The output will appear similar to: - - - 2564 ? S 0:23 /usr/sbin/sshd + 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 - - - - - For more information about using screen, refer to . - - - - - - - - Diagrams and Images - - - images - - - diagrams - creating - + 8032 pts/1 S 0:00 ssh root@backup.example.com + + For more information about using screen, refer to . + + + + + + - - + - - + diff --git a/en_US/docs-xml-tags.xml b/en_US/docs-xml-tags.xml index 6c31779..31a13d2 100644 --- a/en_US/docs-xml-tags.xml +++ b/en_US/docs-xml-tags.xml @@ -1,4 +1,4 @@ - + general tag information - All tags in XML must have an opening and closing tag Additionally, + Most tags in XML must have an opening and closing tag. A few + tags, such as xref, have no + content and close themselves. Additionally, proper XML conventions say that there must be a unique identifier for sections, chapters, figures, tables, and so on, so that they may be correctly identified, and cross referenced if needed. @@ -137,12 +139,11 @@ Content inside screen tags - The screen tags (<screen> and - </screen>) must be flush left in the - XML file, and all the content inside the - screen tags must be flush left as well unless - the white space in intentional; otherwise, the extraneous - whitespace will appear in the HTML version. + The content inside screen tags + (<screen> and </screen>) + must be flush left in the XML file; + otherwise, the extraneous whitespace will appear in the HTML + version. @@ -200,7 +201,7 @@ browser. -<!--$Id: docs-xml-tags.xml,v 1.2 2006/12/17 00:41:55 pfrields Exp $ --> +<!--$Id: docs-xml-tags.xml,v 1.3 2006/12/23 23:49:59 pfrields Exp $ --> <chapter id="ch-sample"> <title>Sample Chapter</title> @@ -1813,11 +1814,12 @@ foo-version-number.arch.rp Important - When using the <screen> tag, you must set - everything within that screen, including the - <screen> tags themselves, to flush left. This - must be done so that when it is converted to HTML, it will not have - extra blank space in front of it inside the gray background. + When using the <screen> tag, set + everything within that screen to flush left. The contents of + the screen element are + rendered exactly as is, including any indentation. Using flush + left prevents extra blank space in front of the text inside the + gray background when the content is converted to HTML. @@ -2498,3 +2500,10 @@ For more information about the parent file, refer to + + -- cgit