%FEDORA-ENTITIES-EN; ]> recursion recursion RTFM read the f*'ing 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: http://www.docbook.org/tdg/en/html/docbook.html

XML tags naming conventions 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 or chapter or the like. The following general rules apply to IDs: XML tags rules for defining an ID 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 what the XML container type is. 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. 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: ]]> ]]> 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: <trademark>trademark symbol after me</trademark> <trademark class="registered">registered trademark symbol after me</trademark> <trademark class="copyright">copyright symbol after me</trademark> 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 tags): <screen> <itemizedlist> <orderedlist> <variablelist> <table> Content inside para tags within listitem tags Content inside para tags within listitem tags 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 Warnings be 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 will show the basic setup for each case as mentioned above, along with an example of how it would be displayed in the 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. 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 . 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 To find all the currently active ssh sessions, execute the following command: ps ax | grep ssh The output will appear similar to: 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 .