%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 .

In accordance with good XML practices, the first line in any DocBook XML source files should identify the file as XML. Use the following line as the first line of any new XML file: ]]>

All the files must contain the CVS Id header. Use the following line as the second line of any new XML file: ]]> Any time the file is committed to CVS, the line is updated automatically to include information about the file. For example: ]]>

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: DocBook XML source Rendered content trademark symbol after me]]> trademark symbol after me registered trademark symbol after me]]> registered trademark symbol after me copyright symbol after me]]> copyright symbol after me 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.

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 Screenshots are illustrations that show the state of a display the user may encounter. Screenshots can be either graphical or textual. However, screenshots use a great deal of space in a text document to convey relatively small amounts of information. The same space in the document can hold a greater amount of more descriptive and helpful information. Therefore, authors should avoid screenshots whenever possible in favor of descriptive text. One of the isolated instances in which screenshots are useful is to demonstrate a physical screen layout that is unfamiliar to a reader. This does not mean that illustrations of dialog boxes are good uses of screenshots. On the contrary, dialogs are simply instances of a user interface element with which a reader is already familiar. An annotated diagram in certain cases, however, explains to the reader where to find functional landmarks on the screen such as menu bars. 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 Create a new user account to make screenshots. The new account uses the distribution default theme, fonts, and element sizes. The resulting screenshot has an appearance familiar to the largest number of readers, and makes &FDP; documents consistent. Before taking the screenshot, if possible, resize the targeted GUI element(s) to the smallest possible size. The target image should be 500 pixels wide or less. If the screenshot includes 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 the mouse to bring it to the forefront, or otherwise arrange the elements. Press Alt Print Screen to capture a single GUI window. For capturing the entire desktop use Print Screen. If the shot includes multiple elements grouped closely together, crop the resulting PNG format image in The GIMP. If necessary, resize the image using The GIMP. Open the image, then right-click on it and choose Image Scale Image... . With the chain symbol intact, set the New Width to 500 px, and click OK. Choose File Save to save changes to the image before converting it. With the image open in The GIMP, right-click the image, and select File Save As... . Under Determine File Type:, select PostScript, then click OK. Allow flattening of the image by clicking Export. A Save as PostScript window appears. Select Encapsulated PostScript, and click OK. Text Screenshot Textual screen information is also useful for readers. Follow these guidelines for textual screenshots: If a graphical screenshot illustrates a function, and the textual mode has identical functions, do not include both, unless omitting either would make your description unclear. Make the 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

The GNOME Help browser, also known as yelp, and the KDE Khelp documentation browser can render DocBook XML information as needed. Use these applications to preview your work if you prefer reading your work in a browser-like environment. Run the following command: Make sure to point the preferred help browser at the top parent file of your XML document. Once the document loads, you can add a bookmark for it for ease of use later. Keeping your documents in the same place for every checkout session makes help browser bookmarks more effective. Once you have a bookmark stored, it will appear in the help browser at every use. You can now hit F1 during any GUI session to launch the help browser. Then choose your bookmark from the menu to preview your document at any time.