%FEDORA-ENTITIES-EN; ]> recursion recursion RTFM read the fine manual humor humor RTFM Please read this chapter carefully. This chapter describes the guidelines that must be followed such as naming conventions. This chapter only discusses tags used for documentation for the &PROJECT;, not all available DocBook XML tags. For the complete list, refer to .

XML tags naming conventions naming conventions 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 rules for defining an ID naming conventions rules for defining an ID 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.

]]> Tag Prefix preface pr- chapter ch- section sn- figure fig- table tb- appendix ap- part pt- example ex- Use the title of the item as the ID. Make your titles unique within a document to prevent conflicts. For example:

]]> xml tags caveats It is very important that you remember the caveats in this section. These are learned suggestions or rules that make your XML experience better. Do Not Use Trademark Entities Do not use the trademark entities trade, copy, or reg because the do not produce HTML output that works for all charsets. The HTML output produces by these entities are declared in the DTD and cannot be changed via the stylesheet. Instead, use the trademark tag and its associates classes as follows: trademarktrademark symbol after metrademark trademark class="registered"registered trademark symbol after metrademark trademark class="copyright"copyright symbol after metrademark Content inside para tags In general, use para tags around anything other than a simple paragraph. Doing so will create additional white space within the text itself in the PDF version. Specifically, do not use para tags around the following (or, to put this another way, do not embed the following within para elements): screen itemizedlist orderedlist variablelist table Content inside para elements within listitem tags Content inside para elements within listitem elements must start immediately after the beginning para tag to avoid extra white space in the PDF version. Content inside screen tags 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.

All the files must contain the CVS Id header. If you create a new file, the first line must be: ]]> 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: ]]>

admonitions XML tags warning XML tags tip XML tags note XML tags caution XML tags important XML tags admonitions warning XML tags admonitions tip XML tags admonitions note XML tags admonitions caution 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 a warning is reserved for cases where bodily harm can result.

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 show the basic setup for each case mentioned above, along with its appearance in HTML. Body of text goes here. ]]> Body of text goes here. Body of text goes here. ]]> Body of text goes here Body of text goes here. ]]> Body of text goes here. Body of text goes here. ]]> Body of text goes here. Body of text goes here. ]]> Body of text goes here.

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. 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. Text Screenshot Textual screen information is also useful for readers. 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. 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 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