From e9636f3c0c68ce37c8689971386abd73e99cf1e2 Mon Sep 17 00:00:00 2001 From: Tammy Fox Date: Fri, 21 Nov 2003 22:40:39 +0000 Subject: change filenames to end with -en.xml --- Makefile | 2 +- docs-converting.xml | 20 - docs-emacs.xml | 697 ------------- docs-getting-files.xml | 61 -- docs-intro.xml | 40 - docs-rh-guidelines.xml | 386 ------- docs-tutorial.xml | 98 -- docs-xml-tags.xml | 2433 -------------------------------------------- documentation-guide-en.xml | 22 +- documentation-guide.xml | 77 -- 10 files changed, 12 insertions(+), 3824 deletions(-) delete mode 100644 docs-converting.xml delete mode 100644 docs-emacs.xml delete mode 100644 docs-getting-files.xml delete mode 100644 docs-intro.xml delete mode 100644 docs-rh-guidelines.xml delete mode 100644 docs-tutorial.xml delete mode 100644 docs-xml-tags.xml delete mode 100644 documentation-guide.xml diff --git a/Makefile b/Makefile index b824144..30c7249 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,7 @@ XSLPDF = ../xsl/main-pdf.xsl XSLHTML = ../xsl/main-html.xsl LANG = en -DOCNAME = documentation-guide +DOCNAME = documentation-guide-$(LANG) XMLFILE = $(DOCNAME).xml ###################################################### diff --git a/docs-converting.xml b/docs-converting.xml deleted file mode 100644 index 809747c..0000000 --- a/docs-converting.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - Converting to HTML and PDF - - - Each directory containing a document also has a Makefile. In the directory, - run the command make html to build the HTML version and - make pdf to build the PDF version. - - - - Warning - - The PDF production is somewhat fragile right now. It may or may not - work. - - - - diff --git a/docs-emacs.xml b/docs-emacs.xml deleted file mode 100644 index 8133bf0..0000000 --- a/docs-emacs.xml +++ /dev/null @@ -1,697 +0,0 @@ - - - - Emacs and PSGML Mode - - - PSGML - - - - Emacs - - - - Emacs - PSGML mode - - - - You can use the PSGML mode available for Emacs to make it easier to write - in XML format. PSGML mode provides syntax-highlighting, tag completion, - and more. - - - - Setting Up Your <filename>.emacs</filename> File - - - Emacs - configuration file - - - - .emacs - - - - For Emacs to parse your DocBook documents correctly, you must have a - .emacs file. Cut and paste the following into your - existing .emacs file or create a new one that - contains the following lines: - - - -;; turn on auto-fill in `text-mode' and derived modes -;;(mail, news, etc) -(add-hook 'text-mode-hook 'turn-on-auto-fill) - -;; -;;MODES -;; - -(setq auto-mode-alist (cons '("\\.sgml$" . sgml-mode) auto-mode-alist)) -(setq auto-mode-alist (cons '("\\.sgm$" . sgml-mode) auto-mode-alist)) - -;; -;;XML!! -;; -;;############################################################# - -;; -;;PSGML mode stuff -;; - -(autoload 'sgml-mode "psgml" "My Most Major Mode" t) - -(setq sgml-mode-hook '(lambda () "Defaults for XML mode." (turn-on-auto-fill) -(setq fill-column 80))) - -(defun My-XML-keymap () - (local-set-key [(alt i)] - '(lambda () - (interactive) - (sgml-indent-line) - (sgml-insert-element 'item) - (sgml-indent-line))) - (local-set-key [(alt l)] - '(lambda () - (interactive) - (sgml-insert-element 'list) - (sgml-insert-element 'item) - (sgml-indent-line))) - (local-set-key [(alt p)] - '(lambda () - (interactive) - (sgml-indent-line) - (sgml-insert-element 'para) - (sgml-indent-line))) - (local-set-key [(alt -)] - '(lambda () - (interactive) - (insert "—")))) - -(add-hook 'sgml-mode-hook 'My-XML-keymap) - -;; -;; Fix up indentation of data... -;; - -(setq-default sgml-indent-data t) - -;; -;; XML markup faces. -;; - -(setq-default sgml-set-face t) - - -(make-face 'sgml-comment-face) -(make-face 'sgml-doctype-face) -(make-face 'sgml-end-tag-face) -(make-face 'sgml-entity-face) -(make-face 'sgml-ignored-face) -(make-face 'sgml-ms-end-face) -(make-face 'sgml-ms-start-face) -(make-face 'sgml-pi-face) -(make-face 'sgml-sgml-face) -(make-face 'sgml-short-ref-face) -(make-face 'sgml-start-tag-face) - -(set-face-foreground 'sgml-comment-face "maroon") -(set-face-foreground 'sgml-doctype-face "dark green") -(set-face-foreground 'sgml-end-tag-face "blue2") -(set-face-foreground 'sgml-entity-face "red2") -(set-face-foreground 'sgml-ignored-face "maroon") -(set-face-background 'sgml-ignored-face "gray90") -(set-face-foreground 'sgml-ms-end-face "maroon") -(set-face-foreground 'sgml-ms-start-face "maroon") -(set-face-foreground 'sgml-pi-face "maroon") -(set-face-foreground 'sgml-sgml-face "maroon") -(set-face-foreground 'sgml-short-ref-face "goldenrod") -(set-face-foreground 'sgml-start-tag-face "blue2") - -(setq-default sgml-markup-faces - '((comment . sgml-comment-face) - (doctype . sgml-doctype-face) - (end-tag . sgml-end-tag-face) - (entity . sgml-entity-face) - (ignored . sgml-ignored-face) - (ms-end . sgml-ms-end-face) - (ms-start . sgml-ms-start-face) - (pi . sgml-pi-face) - (sgml . sgml-sgml-face) - (short-ref . sgml-short-ref-face) - (start-tag . sgml-start-tag-face))) - - -(defun docbook-mode () - (sgml-mode) - ) - - - -;; -;;END XML STUFF -;; -;;################################################################## - -;PO mode stuff - -(setq auto-mode-alist - (cons '("\\.pox?\\'" . po-mode) auto-mode-alist)) -(autoload 'po-mode "po-mode") - - - (global-set-key [(f1)] (lambda () (interactive) (manual- - entry (current-word)))) - - - - - - - - Do you have a cool wheel mouse? If so, you can add the following to your - .emacs file so your wheel will work in - Emacs (must be - Emacs version 21): - - - - -;; Enable wheelmouse support by default for emacs 21 -(cond (window-system -(mwheel-install) -)) - - - - - If you are using the older version 20 of - Emacs, add the following instead: - - - -;; Enable wheelmouse support by default -(require 'mwheel) - - - - - - - - Customizing Emacs - - - Emacs - customizing - - - - .Xresources - - - - Emacs - colors - - - - Emacs - font - - - - Emacs - geometry - - - - The colors, font, and geometry (default size of window) for Emacs in your - ~/.Xresources file. The format for the settings is - emacs.keyword:value - - - - The following is a sample ~/.Xresources file. - - - Note - If you have other settings in your - ~/.Xresources, add the following to the end of - the file. - - - - - -emacs.background: light gray -emacs.foreground: black -emacs.pointerColor: blue -emacs.cursorColor: blue -emacs.bitmapIcon: on -emacs.font: fixed -emacs.geometry: 90x25 - - - - After modifying this file, you must execute the command - - -xrdb -merge ~/.Xresources - - - and restart Emacs for the changes to take - place. - - - - - - Create Recompiled DTD Subset - - - Emacs will perform syntax highlighting and indent correctly on - DocBook XML files if you provide it with the proper Document Type - Declarations (DTD) file. These two features will make your XML file - look pretty and help you spot errors. - - - - To create a loadable Parsed DTD file: - - - Find the parent file for the group of DocBook files. You will - recognize this file by the header <!DOCTYPE article - PUBLIC "-//OASIS//DTD DocBook V4.1//EN". An easy way - to find this parent file is to use the command grep - DocBook *.xml. Once you find the parent file, open it - in Emacs with the command emacs - <parentfile>.xml (where - <parentfile>.xml is the parent - file you found. - - - - - Choose DTD -> Parse DTD from the pulldown - menu. - - - - - You will know the parsing is finished when you see the message - Fontifying...done at the bottom - of your screen. Save the parsed DTD to a file by choosing - DTD -> Save Parsed DTD from the pulldown menu. - - - - - Press Enter to save the file to the default - filename or rename the file keeping the .ced - extension. It can be useful to name it something generic such as - docbook.ced so you can refer to it when - opening all DocBook files. This file can also be copied from - directory to directory to be loaded. - - - - - - - - Tip - - You can also use the Emacs command Meta-x - sgml-parse-prolog to parse the file, and then use the - command Meta-x sgml-save-dtd to save the parsed DTD - to a .ced file. - - - - - - - Load the Parsed DTD - - - Now that you have saved the DTD settings, you can load the - .ced file and see the syntax highlighting for your - .sgml files. - - - - To load a parsed DTD file: - - - Open an XML file in Emacs. - - - - - Choose DTD -> Load DTD from the pulldown menu - and choose the file you saved from the previous step. For - instance, choose docbook.ced. - - - - - You will know it is finished when you see the message - Fontifying...done at the bottom - of your screen. Loading the parsed DTD might take a long time. - You can start editing the file before it finishes. - - - - - - - - - Tip - - You can also use the Emacs command Meta-x - sgml-load-dtd to load the parsed DTD. - - - - - - - Basic Emacs Commands - - - The Meta key is usually the Alt key. - - - - Emacs Commands - - - - - - - Shortcut - Description - - - - - - Metax - sgml-parse-prolog, Enter - Parse DTD - - - Metax - sgml-save-dtd, Enter - Save the Parse DTD - - - Metax - sgml-load-dtd, Enter - Load DTD - - - Ctrl c - , Shift - , Tab - Display list of valid tags - - - Ctrl c - , Shift - , type beginning of tag, - Tab - Complete the tag - - - Ctrl g - - Cancel a command in the minibuffer - - - Ctrl c - , / - Close tag - - - Ctrl a - - Move cursor to beginning of line - - - Ctrle - - Move cursor to the end of the line - - - CtrlHome - - Move cursor to the beginning of the file - - - CtrlEnd - - Move cursor to the end of the file - - - Ctrlk - - Cut line - - - Ctrl y - - Paste line - - - Ctrl s - - Search forward in the file - - - Ctrlr - - Search backwards in the file - - - Meta$ - - Check spelling of current word - - - Metax - ispell-word, Enter - Check spelling of current word - - - Metax - ispell-buffer, Enter - Check spelling of current buffer - - - Ctrlx - , Ctrlf - - Open file - - - Ctrlx - , Ctrls - - Save file - - - Ctrlx - , Ctrlc - - Exit Emacs and prompt to save - files if necessary - - - Meta q - - Fill paragraph - - - Ctrlc - , Ctrla - - Edit attributes for a tag (for example, you can edit the - url attribute of the - ulink tag) - - - Ctrl c - , - Ctrlc - - Exit edit attributes - - - -
- - - - - Examples - - - The table or reference card of Emacs and PSGML commands can be confusing - for beginners. This section provides some examples of how to use them. - - - - Tag Completion - - - Note - This section assumes that you have already loaded the DTD file - (.ced). - - - - - Instead of typing a tag each time you need to use it, use - the key combination Ctrl-c, - followed by <. At the bottom of the - Emacs window, you will see: - - -Tag: < - - - - To view a list of available tags, use either the Tab - or ?. Or, if you know the first few letters of a tag, - you can enter them followed by Tab for a complete - list of available tags beginning with those letters or for a tag - completion. - - - - Try the following: Type Ctrl-c - followed by <. Then enter the letter - k, followed by Tab. You may have to - use the Tab key several times to get a complete list. - - - - The output should look similar to the example below: - - - - -Click mouse-2 on a completion to select it. -In this buffer, type RET to select the completion near point. - -Possible completions are: -<keycap> <keycode> -<keycombo> <keysym> - - - - - - Tag Closure - - - Once you have started the tag of choice, you must close it. The easiest - way to close an open tag is to use the keycombo - Ctrl-c, followed by - /. This will close the closest open tag you have. - - - - - - Other Emacs Tasks - - - Working with one window: Sometimes in - Emacs the window becomes split (with tags - completions or other text in the bottom window). The easiest way to - get it back so that only your XML and text appear on one screen is to - use the keycombo Ctrl-x, followed by - 1. - - - - Saving your work: To save your work, use the - following keycombo, Ctrl-x followed by - Ctrl-s. - - - - The "clear/quit" command: I have found on some - occasions that I have gotten too far into the tag completion process and - need to just exit back out to my text. The easiest way to do this is the - keycombo Ctrl-g. This command quits - what you have been doing within the file, without quitting the file - itself. - - - - Opening a new file: To open a new file, use the - keycombo Ctrl-x followed by - Ctrl-f. At the bottom of the emacs - window, you will be able to enter in the file name (using - Tab completion if needed) of the file you wish to - open. - - - - Closing emacs: The easiest way to close - emacs is to use the keycombo - Ctrl-x followed by - Ctrl-c. If you have not saved your work, - it will prompt you to save the file, otherwise it will just quit the - current emacs session you have been working with. - - - - - - - Additional Resources - - Additional Emacs and PSGML references are available at the - following locations: - - - - - http://wks.uts.ohio-state.edu/unix_course/intro-135.html - — Emacs Quick Reference Guide - - - Emacs reference card that comes with the - emacs package. You can print it out as a - reference. — - /usr/share/emacs/<version>/etc/refcard.ps - - - - Read Editing XML with Emacs and PSGML - in /usr/share/doc/psgml-<version>/psgml.ps. - - - - - - - - - - - - - - diff --git a/docs-getting-files.xml b/docs-getting-files.xml deleted file mode 100644 index 5a4a716..0000000 --- a/docs-getting-files.xml +++ /dev/null @@ -1,61 +0,0 @@ - - - - Getting the Files - - - To start working on the Docs Project, you will need the appropriate - DocBook XML files, stylesheets, and scripts. The following packages are - required: - - - - - xmlto — for producing HTML and PDF outputs - - - docbook-style-xsl — for the default XSLT stylesheets we - build on - - - docbook-dtds — XML versions of the DocBook DTD - - - - - The custom scripts and stylesheets used are all stored in CVS on the - rhlinux.redhat.com CVS server. - - - - You need to check them out along with the DocBook XML files for the - existing docs. - - - - To check out the scripts anonymously: - - - -export CVSROOT=:pserver:anonymous@rhlinux.redhat.com:/usr/local/CVS -cvs -z3 login -cvs -z3 co fedora-docs - - - - Checking the files out anonymously means that you can view them and - retreive the latest versions, but you can not add (commit) any updates or - new files back to the repository. - - - - Except for the &IG;, all docs must be tutorials - written in DocBook XML article format using the template in the - example-tutorial directory. Each tutorial - must be in its own directory. No XML files should be - in the root directory except for files shared by all documents such - legalnotice.xml, which must be included in all docs - so that the FDL is used for all docs. - - - diff --git a/docs-intro.xml b/docs-intro.xml deleted file mode 100644 index 44b1990..0000000 --- a/docs-intro.xml +++ /dev/null @@ -1,40 +0,0 @@ - - - - Introduction - - - The goal of the Docs Project is to create easy-to-follow, task-based - documentation for &DISTRO; users and developers. Other than the - &IG;, each tutorial should be in DocBook XML - article format, with one article per topic. This way, writers can - contribute documentation about a specific topic without having to worry - about how it fits into a manual or how it flows with other topics. - - - - The following tools are used: - - - - - DocBook XML v4.1 - - - Custom XSLT stylesheets for both print and HTML versions - - - Custom scripts to generate PDF and HTML output (use xmlto) - - - Emacs with PSGML mode (optional, but recommended) - - - - - The purpose of this document is to explain the tools used by the Docs - Project as well as to provide writing and tagging guidelines so that the - documentation is consistent and easy-to-follow. - - - diff --git a/docs-rh-guidelines.xml b/docs-rh-guidelines.xml deleted file mode 100644 index 2d39357..0000000 --- a/docs-rh-guidelines.xml +++ /dev/null @@ -1,386 +0,0 @@ - - &RH; Documentation Guidelines - - - 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. - - - - ID Naming Conventions - - - XML tags - 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: - - - - -<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: - - - XML tags - 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) - - - - Some examples are "ch-uniquename" (with 13 - characters) and "s3-install-make-disks" (with 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 - - - 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: - - - - -<!-- $Id: docs-rh-guidelines.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> - - - - - - - Working with Admonitions - - - 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. - - - - 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. - - - - -<warning> -<title>Warning</title> -<para>Body of text goes here.</para> -</warning> - - - - - Warning Body of text goes here. - - - - - - - - - - diff --git a/docs-tutorial.xml b/docs-tutorial.xml deleted file mode 100644 index e453830..0000000 --- a/docs-tutorial.xml +++ /dev/null @@ -1,98 +0,0 @@ - - - - The Layout of a Tutorial - - - In this chapter, you will find an example of a &PROJECT; documentation - parent file. This example is specific to the way the Docs Project uses - DocBook XML. The parent file contains the main structural format of the - book, entities that should be used for this book specifically and more. - - - - The Parent File - - - Below is a sample parent file: - - - - -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - -<!ENTITY RH "Red Hat"> <!--The generic term "Red Hat" --> -<!ENTITY FORMAL-RHI "&RH;, Inc."> <!--The generic term "Red Hat, Inc. --> -<!ENTITY PROJECT "Fedora project"> <!-- Set the project name --> -<!ENTITY NAME-TITLE "Fedora Project"> <!-- Set the project name, use for titles --> -<!ENTITY DISTRO "Fedora Core"> <!-- Set the distro name --> -<!ENTITY BOOKID "example-tutorial-0.1 (2003-07-07)"> <!-- change version of manual and date here --> - -<!ENTITY LEGALNOTICE SYSTEM "../legalnotice.xml"> - - -]> - -<article id="example-tutorial" lang="en"> - <articleinfo> - <title>Example Tutorial</title> - <copyright> - <year>2003</year> - <holder>&FORMAL-RHI;</holder> - <holder>Tammy Fox</holder> - </copyright> - <authorgroup> - <author> - <surname>Fox</surname> - <firstname>Tammy</firstname> - </author> - </authorgroup> - &LEGALNOTICE; - </articleinfo> - - <section id="some-section"> - <title>Some Section</title> - - <para> - This is an example section. You can also use sect1, sect2, etc. - </para> - - <warning> - <title>Warning</title> - <para> - Example of an admonition. - </para> - </warning> - - </section> - -</article> - - - - - - - Including the License Information - - - tutorial layout - license - - - - All &PROJECT; manuals must contain the file - legalnotice.xml. This file makes the license for - the file the GNU Free Documentation License (FDL). - - - - The sample parent file shows how it is included. - - - - - - - diff --git a/docs-xml-tags.xml b/docs-xml-tags.xml deleted file mode 100644 index 6bbce6e..0000000 --- a/docs-xml-tags.xml +++ /dev/null @@ -1,2433 +0,0 @@ - - - - DocBook XML Tags - - - XML - tags - XML tags - - - Please read this chapter carefully. This chapter describes the tags - used by the Docs Project. Some of the rules described are specific to the - project. - - - If these tags are used appropriately, document searches will provide - meaningful results. These tags help search engines identify the - information relevant to the search request. Another benefit is that all - &PROJECT; documents will have a similar look and feel (however, they will have - some differences depending upon the output format). - - - - XML - general tag information - - - All tags in XML must have an opening and closing tag 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. - - Although XML is capable of handling many document types, the format - discussed here is the article format. - - - 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 - - - - - Tags and Entities Caveats - - - xml tags - caveats - - - - It is very important that you remember the caveats in this section. Even - though they are more strict than valid DocBook XML, these rules exist - so that both the HTML and PDF outputs look proper. - - - - - 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 - - Do not 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 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. - - - - - - - - - <command>application</command> - - - XML tags - application - - - An application is the name of a GUI software program. A command is - the name of an executable (text) program or a software command. - - The <application> and - </application> tags allow you to refer to an - application or program. For example, the following XML: - - - - -To view the Web in Linux, you can use -<application>Mozilla</application> or -<application>lynx</application> if you only want a text-based -browser. - - - - - produces the following output: - - - - To view the Web in Linux, you can use Mozilla - or lynx if you only want a text-based browser. - - - - - - <command>chapter</command> - - - XML tags - chapter - - - - A DocBook book can be divided into chapters such as: - - - - -<!--$Id: docs-xml-tags.xml,v 1.2 2003/10/15 18:11:01 tfox Exp $ --> - - <chapter id="ch-sample"> - <title>Sample Chapter</title> - - <para>This is a sample chapter, showing you the XML tags used to create a - chapter, sections, and subsections.</para> - - </chapter> - - - - - The chapter can also be further divided into sections - (sect1, sect2, - sect3, etc.). Refer to for details. - - - - - - - <command>citetitle</command> - - - XML tags - citetitle - - - - - The <citetitle> tag provides formatting for a - specific references (title can be manually typed out or if already - defined within your document set, given as an entityAn - entity is a short hand way of referring to another manual or guide. It - can be defined within the parent document or within a set of files that - your DTD references for your specific documentation set. - - ). - - - For example: - - - -<citetitle>IG;</citetitle>. - - - - The output looks like &IG; because &IG; is an - entity. - - - - - - <command>command</command> - - - XML tags - command - - - An application is the name of a GUI software program. A command is - the name of an executable (text) program or a software command. Any - program that is a command line or text-based only tool is marked with - command tags. - - - If you have text that is a command, use the - <command> and - </command> tags such as: - - - - - - -To change your keyboard after installation, become root -and use the <command>redhat-config-keyboard</command> command, -or you can type <command>setup</command> at the root prompt. - - - - - The output: - - - To change your keyboard after installation, become root and use - the redhat-config-keyboard command, or you can type - setup at the root prompt. - - - Another example would be: - - - -<command>MAILNOVIOLATIONS</command> — If set -to <command>true</command> this option tells Tripwire to -email a report at a regular interval regardless of whether or not -any violations have occured. The default value is -<command>true</command>. - - - - - with the output: - - - - MAILNOVIOLATIONS — If set to - true this variable tells Tripwire to email a report - at a regular interval regardless of whether or not any violations have - occured. The default value is true. - - - - Note In this example, the option value (true) is - defined with a <command> tag set. Because a option is a - configuration file option (command line options which would use the - <option> tag set), and because there is no configuration file - option tag available to use, we are extending the <command> tag - set to define options in a configuration file. - - - - Terms marked with command tags because there aren't - exact tags for them: - - - - Options in configuration files such as Apache directives - - - daemon names - - - - - - - <command>computeroutput</command> - - - XML tags - computeroutput - - - - To show computer output use the following tags: - - - -<computeroutput>Do you want to delete this file? y n</computeroutput> - - - - - The output: - - - Do you really want to delete this file? y n - - - - - <command>emphasis</command> - - - XML tags - emphasis - - - - To emphasis content, use the <emphasis> and - </emphasis> tags. For example: - - - -This installation <emphasis>will remove all</emphasis> existing -Linux partitions on <emphasis>all</emphasis> hard drives in your -system; non-Linux partitions will not be removed. - - - - - The output: - - - - This installation will remove all existing Linux - partitions on all hard drives in your system; - non-Linux partitions will not be removed. - - - - - <command>example</command> - - - XML tags - example - - - The <example> and - </example> tags are used to format text within a - document and is great for adding emphasis to show examples of code, - exercises, and more. - - The <example> tag set should be given an ID - and title: - - - <example id="static-ip"> - <title>Static IP Address using DHCP</title> - -<screen width=60> -<computeroutput> -host apex { - option host-name "apex.example.com"; - hardware ethernet 00:A0:78:8E:9E:AA; - fixed-address 192.168.1.4; -} -<computeroutput> -</screen> - - </example> - - - - The output: - - - - Static IP Address using DHCP - - - -host apex { - option host-name "apex.example.com"; - hardware ethernet 00:A0:78:8E:9E:AA; - fixed-address 192.168.1.4; -} - - - - - - - - - <command>filename</command> - - - XML tags - filename - - - - The <filename> and - </filename> tags define a filename or path to a - file. Since directories are just special files, they are marked with the - filename tags as well. For example: - - -Edit the <filename>/home/smoore/sam.xml</filename> file to make -changes or add comments. - - - The output: - - - Edit the /home/smoore/sam.xml file to make changes - or add comments. - - - - They are also used to markup an RPM package name. For example: - - -To use the <application>Keyboard Configuration Tool</application>, the -<command>redhat-config-keyboard</command> RPM package must be installed. - - - The output: - - - To use the Keyboard Configuration Tool, the - redhat-config-keyboard RPM package must be installed. - - - - Note - - Directory names must end with a forward slash - (/) to distinguish them from file - names. - - - - - - - <command>firstterm</command> - - - XML tags - firstterm - - - - The <firstterm> and - </firstterm> tags helps to define a word that - may be unfamiliar to the user, but that will be seen commonly throughout - the text. For example: - - - -Nearly every modern-day operating system uses <firstterm>disk -partitions</firstterm>, and &DISTRO; is no exception. - - - - - The output: - - - - Nearly every modern-day operating system uses disk - partitions, and &DISTRO; is no exception. - - - - - - <command>footnote</command> - - - XML tags - footnote - - - - If you need to make a footnote, use the following example: - - - -For those of you who need to perform a server-class -<footnote> -<para> -A server-class installation sets up a typical server -environment. Note, no graphical environment is -installed during a server-class installation. -</para> -</footnote> installation, refer to the <citetitle>Installation Guide</citetitle>. - - - - - The output: - - - - For those of you who need to perform a server-class A - server-class installation sets up a typical server environment. Please note, no - graphical environment is installed during a server-class installation. - installation, refer to the - Installation Guide. - - - - - - <command>figure</command> - - - XML tags - figure - - - - Important - - Order matters! The EPS file must be declared - first. - - - - - An example figure declaration: - - - - -<figure id="fig-ksconfig-basic"> - <title>Basic Configuration</title> - <mediaobject> - <imageobject> - <imagedata fileref="./figs/ksconfig/ksconfig-basic.eps" - format="EPS"/> - </imageobject> - <imageobject> - <imagedata fileref="./figs/ksconfig/ksconfig-basic.png" - format="PNG"/> - </imageobject> - <textobject> - <phrase> - Some text description of this image - </phrase> - </textobject> - </mediaobject> -</figure> - - - - - The following describes what needs to be edited: - - - -<figure id="fig-ksconfig-basic"> ==> id="" would be edited - -<title>Basic Configuration</title> ==> title would be edited - -fileref="./figs/ksconfig/ksconfig-basics.eps"> ==> .eps location would be edited - -fileref="./figs/ksconfig/ksconfig-basics.png"> ==> .png location would be edited - -<phrase>Some text description of this image</phrase> ==> "Some text..." would be edited - - - - - GUI Tags - - - XML tags - GUI tags - - - - <command>guilabel</command> - - - XML tags - GUI tags - guilabel - - - - XML tags - guilabel - - - - Use the <guilabel> and - </guilabel> tags as a default for GUI - descriptions, like a screen name or screen title. For example: - - - -The <guilabel>Authentication Configuration</guilabel> screen -shows you how to make your system more secure. - - - - - The output: - - - - The Authentication Configuration screen shows you how to - make your system more secure. - - - - - <command>guibutton</command> - - - XML tags - GUI tags - guibutton - - - - XML tags - guibutton - - - - Use the <guibutton> and - </guibutton> tags to denote a button on a screen or - menu. For example: - - - -Check the <guibutton>Activate on boot</guibutton> button -to have the X Window System start automatically. - - - - - The output: - - - - Check the Activate on boot button to have the X - Window System start automatically. - - - - - <command>guiicon</command> - - - XML tags - GUI tags - guiicon - - - - XML tags - guiicon - - - - The <guiicon> and </guiicon> - tags are used to denote a panel or desktop icon. For example: - - - -Double-click the <guiicon>Start Here</guiicon> icon on the desktop. - - - - - The output: - - - - Double-click the Start Here icon on the desktop. - - - - - - <command>guimenu</command> and - <command>guimenuitem</command> - - - XML tags - GUI tags - guimenu - - - - XML tags - guimenu - - - - XML tags - GUI tags - guimenuitem - - - - XML tags - guimenuitem - - - - To note a menu (like in the installation program or within the control panel), - use the <guimenu> and - </guimenu> tags. - - - - To note submenu items, use the <guimenuitem> and - </guimenuitem> tags. (Please note that there should not - be any breaks between these commands, but for printing purposes breaks have been - inserted). For example: - - - -Select -<guimenu>Main Menu</guimenu> => - <guimenuitem>Programming</guimenuitem> => <guimenuitem>Emacs</guimenuitem> to start the -<application>Emacs</application> text editor. - - - - - The output: - - - - From the control panel, click on Main Menu => - Programming => - Emacs to start the - Emacs text editor. - - - - - - <command>keycap</command> - - - XML tags - keycap - - - - To denote a specific key, you will need to use the - <keycap> and </keycap> - tags. Brackets are automatically added around the keycap, so do not add - them in your XML code. For example: - - - -To make your selection, press the <keycap>Enter</keycap> key. - - - - - The output: - - - - To make your selection, press the Enter key. - - - - <command>menuchoice</command> - - - XML tags - menuchoice - - - - Often using a mouse is tedious for common tasks. Therefore, - programmers often build in keyboard-shortcuts to simplify their - program. These should be described using the shortcut tag as a wrapper - for the keyboard tags. The shortcut tag must be wrapped inside the - menuchoice tag. For example: - - - - -Go to the menu bar and choose: - <menuchoice> - <shortcut> - <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> - </shortcut> - <guimenu><accel>F</accel>ile</guimenu> - <guimenuitem><accel>S</accel>ave</guimenuitem> - </menuchoice>. - - - - - - The output: - - - - Go to the menu bar and choose: - - - Ctrls - - File - Save - . - - - - - - <command>keycombo</command> - - - XML tags - keycombo - - - - To illustrate a key combination, you need to use the - <keycombo> and - </keycombo>, - <keycap> and - </keycap> tags. For example: - - - -To reboot your system, press <keycombo> -<keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> -</keycombo>. - - - - - The output: - - - - To reboot your system, press - CtrlAltDel - . - - - - - - - - Lists - - - lists - creating - - - There are several types of lists you can create using XML. You - can have a itemized (bulleted) list, a ordered (numbered) list, or a - variable list (presents a term and then a separate paragraph). - - There is also a list format for tables and for for creating a - list of glossary terms and their definitions. - - The sections below will discuss the proper uses for the various - list and how to create them. - - - <command>itemizedlist</command> - - - XML tags - itemizedlist - - - - XML tags - lists - itemizedlist - - - - lists - itemizedlist - - - An ItemizedList is best used to present - information that is important for the reader to know, but that does - not need to be in a specific order. It is shorter than a - VariableList and presents the information in a - very simple way. - - To create an ItemizedList (otherwise known as - bulleted list), use the following command sequence: - - - Note Notice below that the text for the list - item is directly surrounded by the para - tags. If you do not do this, you will find extra whitespace in - your lists where the text does not line up correctly. This is most - noticeable when you have a series of list items that consist of - multiple lines of text. This whitespace is not as noticeable in - the HTML output as it is in the PDFs. - - - - -<itemizedlist> - <listitem> - <para>Getting familiar with the installation program's user interface</para> - </listitem> - - <listitem> - <para>Starting the installation program</para> - </listitem> - - <listitem> - <para>Selecting an installation method</para> - </listitem> -</itemizedlist> - - - - The output looks like: - - - - Getting familiar with the installation program's user interface - - - - Starting the installation program - - - - Selecting an installation method - - - - - - - <command>OrderedList</command> - - - XML tags - orderedlist - - - - lists - orderedlist - - - - XML tags - lists - orderedlist - - - An orderedlist is best used to present - information that is important for the reader to know in a specific - order. orderedlists are a good way to convey - step-by-step senarios to the audience you are writing for. - - - To create an orderedlist (numbered list), use the - following XML code sequence: - - - - Note Notice below that the text for the list - item is directly surrounded by the para - tags. If you do not do this, you will find extra whitespace in - your lists where the text does not line up correctly. This is most - noticeable when you have a series of list items that consist of - multiple lines of text. This whitespace is not as noticeable in - the HTML output as it is in the PDFs. - - - - -<orderedlist> - <listitem> - <para>Online &mdash; http://www.redhat.com/support/errata; supplies errata - you can read online, and you can download diskette images - easily.</para> - </listitem> - - <listitem> - <para>Email &mdash; By sending an empty mail message to errata@redhat.com, - you will receive an email containing a text listing of the - complete errata of the installation program and related software - (if errata exist at that time). Also included are URLs to each - updated package and diskette image in the errata. Using these - URLs, you can download any necessary diskette images. Please - note: use binary mode when transferring a diskette image.</para> - </listitem> -</orderedlist> - - - - The output looks like: - - - - Online — http://www.redhat.com/support/errata; supplies errata - you can read online, and you can download diskette images - easily. - - - - - - Email — By sending an empty mail message to - errata@redhat.com, you will receive an email containing a text - listing of the complete errata of the installation program and - related software (if errata exist at that time). Also included - are URLs to each updated package and diskette image in the - errata. Using these URLs, you can download any necessary - diskette images. Please note: use binary mode when transferring - a diskette image. - - - - - - - - <command>Variablelist</command> - - - XML tags - variablelist - - - - XML tags - lists - variablelist - - - - lists - variablelist - - - A variablelist best represents a list of - terms and definitions or descriptions for those terms. - - To create a variablelist, use the following - command sequence: - - - - Note Notice below that the text for the list - item is directly surrounded by the para tags. If - you do not do this, you will find extra whitespace in your lists - where the text does not line up correctly. This is most noticeable - when you have a series of list items that consist of multiple lines - of text. This whitespace is not as noticeable in the HTML output as - it is in the PDFs. - - - - -<variablelist> - <varlistentry> - <term> New Multi-CD Install </term> - <listitem> - <para>As the installation program continues to grow, Red Hat has developed - an installation program capable of installing from - multiple CD-ROMs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XFree 4.0 </term> - <listitem> - <para>Configuration of your X Window System during the installation has - never been more thorough. From choosing your monitor and its correct - settings, to video card probing, to testing your desired X setup, - Xconfigurator will help you set everything just right.</para> - </listitem> - </varlistentry> -</variablelist> - - - - The output looks like: - - - - New Multi-CD Install As the - installation program continues to grow, Red Hat has developed an - installation program capable of installing from - multiple CD-ROMs. - - - - - XFree 4.0 - - Configuration of your X Window System during the - installation has never been more thorough. From choosing your - monitor and its correct settings, to video card probing, to - testing your desired X setup, Xconfigurator will help you set - everything just right. - - - - - - Warning - - Do not specify the - frame attribute to the table. Doing - so breaks PDF production. - - - - - - - Creating a List Within a Table Using <command>Simplelist</command> - - - XML tags - simplelist - - - - XML tags - lists - simplelist - - - - lists - simplelist - - - - tables - creating a list within a table - simplelist - - - A simplelist is an unadorned list of - items. simplelists can be inline or arranged in - columns. - - We use simplelist to add separate paragraphs - of text within a table element. A regular list, such as - itemizedlist, cannot be embedded within a table. - - The XML commands for a table look like: - - - - <table id="tb-hwinfo-hostbus"> - <title>Host Bus Adapter Features and Configuration Requirements</title> - - <tgroup cols="3"> - <colspec colnum="1" colname="HostBus" colwidth="33"/> - <colspec colnum="2" colname="Features" colwidth="34"/> - <colspec colnum="3" colname="Single" colwidth="33"/> - - <thead> - <row> - <entry>Host Bus Adapter</entry> - <entry>Features</entry> - <entry>Single-Initiator Configuration</entry> - </row> - </thead> - - <tbody> - - <row> - <entry>Adaptec 2940U2W</entry> - - <entry><simplelist> - <member>Ultra2, wide, LVD.</member> - <member>HD68 external connector.</member> - <member>One channel, with two bus segments.</member> - <member>Set the onboard termination by using the BIOS - utility.</member> - <member>Onboard termination is disabled when the power is - off.</member> - </simplelist></entry> - - <entry><simplelist> - <member>Set the onboard termination to automatic (the - default).</member> - <member>Use the internal SCSI connector for private - (non-cluster) storage.</member> - </simplelist></entry> - </row> - - <row> - <entry>Qlogic QLA1080</entry> - - <entry><simplelist> - <member>Ultra2, wide, LVD</member> - <member>VHDCI external connector</member> - <member>One channel</member> - <member>Set the onboard termination by using the BIOS - utility.</member> - <member>Onboard termination is disabled when the power is off, - unless jumpers are used to enforce termination.</member> - </simplelist></entry> - - - <entry><simplelist> - <member>Set the onboard termination to - automatic (the default).</member> - <member>Use the internal SCSI connector for private - (non-cluster) storage.</member> - </simplelist></entry> - </row> - - </tbody> - </tgroup> - </table> - - - - The output looks like: - - - Host Bus Adapter Features and Configuration Requirements - - - - - - - - - Host Bus Adapter - Features - Single-Initiator Configuration - - - - - - - Adaptec 2940U2W - - - Ultra2, wide, LVD. - HD68 external connector. - One channel, with two bus segments. - Set the onboard termination by using the BIOS - utility. - Onboard termination is disabled when the power is - off. - - - - Set the onboard termination to automatic (the - default). - Use the internal SCSI connector for private - (non-cluster) storage. - - - - - Qlogic QLA1080 - - - Ultra2, wide, LVD - VHDCI external connector - One channel - Set the onboard termination by using the BIOS - utility. - Onboard termination is disabled when the power is off, - unless jumpers are used to enforce termination. - - - - - Set the onboard termination to - automatic (the default). - Use the internal SCSI connector for private - (non-cluster) storage. - - - - - -
- - - Note - Notice how the SimpleList tags are - used. The <entry> and <simplelist> tags must be aligned - beside one another, otherwise you will receive a parsing error. - - - For each paragraph or list item to be added within a - SimpleList, the <member> tag set must be - added around that particular text item. - - - - <command>glosslist</command> - - - XML tags - glosslist - - - - XML tags - lists - glosslist - - - - lists - glosslist - - - Use the glosslist command set to create a - list of glossary terms and their definitions. - - - In XML, an example looks like the following: - - - - <glosslist> - <glossentry> - <glossterm>applet</glossterm> - <glossdef> - <para>A small application, usually a utility or other - simple program.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>architecture</glossterm> - <glossdef> - <para>The design for organization and integration of - components within a computer or computer system.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>archive</glossterm> - <glossdef> - <para>To transfer files into storage for the purpose of - saving space and/or organization.</para> - </glossdef> - </glossentry> - </glosslist> - - - - - The output looks like: - - - - - applet - - A small application, usually a utility or other simple program. - - - - - architecture - - The design for organization and integration of components - within a computer or computer system. - - - - - archive - - To transfer files into storage for the purpose of saving - space and/or organization. - - - - - - - - - - <command>option</command> - - - XML tags - option - - - If you have a command that offers an option or a flag, use the - <option> and - </option> tags. - - - - Note - The <option> tag set is only meant to be used for command - line options, not options in configuration files. - - - In XML, specifying an option would look like the - following: - - - -For example, with the command <command>ls</command> you can -specify an option such as <option>-la</option>. - - - - - The output: - - - For example, with the command ls you can - specify an option such as . - - - - - Index Entries - - - indexing - - - - - XML tags - indexing - - - The following command sequence shows you the code inserted into - the body of the text to add an index entry to your document: - - - - -<indexterm> <-- indicates a term to be placed in the index -<primary>foo</primary> <-- indicates that "foo" is the first term -<secondary>bar</secondary> <-- "bar" will be listed under "foo" -</indexterm> <-- closes this index entry - - - - - foo - bar - - - - The <seealso> tag allows you to - reference another index entry or refer to another manual. Make sure - the <seealso> reference you are pointing to - has its own entry. For example: - - - - indexing - seealso tag - - - - -<indexterm> -<primary>SWAK</primary> -<seealso>salutations</seealso> -</indexterm> - - -<indexterm> -<primary>salutations</primary> -</indexterm> - - - - - SWAK - Salutations - - - - Salutations - - - - The <see> tag allows you to reference to - another index entry entirely. For example: - - - indexing - see tag - - - - - -<indexterm> -<primary>Guinness</primary> -<see>beer</see> <-- beer will be listed under -the Guinness entry, but you must make sure beer also has its -own entry to refer to. -</indexterm> - -<indexterm> -<primary>beer</primary> -</indexterm> - - - - - Guinness - Beer - - - - Beer - - - To view the HTML output of the index entries shown here, refer - to the generated-index.html file at the end of - this document. - - - - - - <command>para</command> - - - - XML tags - para - - - For any paragraph, the <para> and - </para> tags must open and close that - particular paragraph. - - - - Additional Rules for the <command><para></command> Tag - Set - - - XML tags - para - additional rules - - - - - Proper formatting of <para> tag and - text - - Additionally, the <para> tags - should be justified around the paragraph so that the opening - <para> tag and the first word of that - paragraph are side by side. For example: - - - -<para>This paragraph talk about using the <para> -tag correctly.<para> - - - - - - - - Where not to use <para> tags - - Do not use para tags around anything other than a simple - paragraph. Doing so will create additional white space within - the text itself. - - 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> - - - - - - - - - - - - <command>part</command> - - - parts - - - - - XML tags - part - - - - In the parent file, you can separate the chapters into parts to divide - them into logical groups. For example, in the parent file, the - part tags surround the chapter entities: - - - -<part id="pt-foo"> - <partintro> - <para>Some text for the part intro</para> - &CHAPTER; - - &ANOTHER-CHAPTER; -</part> - - - - - If you create a part, include a part introduction describing the - contents of the part. For example: - - - - - <part id="pt-setup"> - <title>Getting Setup</title> - <partintro> - <para>This section contains information you will need when you first join - the Docs group. You might need to refer to this part again for - information such as installing &DISTRO;.</para> - </partintro> - - - - - In the HTML output, a separate HTML page is generated with the part - number, title, introduction, and TOC. In the PDF output, the same - information about the part is on a separate page. - - - - - - <command>prompt</command> - - - XML tags - prompt - - - - To show a prompt, such as a root or DOS prompt, use the - <prompt> and </prompt> - commands. For example: - - - -At the <prompt>LILO:</prompt> boot prompt, type linux to -boot into your Linux partition. - -At the <prompt>C:\></prompt> prompt, type .... - - - - - The output: - - - - At the LILO: boot prompt, type linux to boot into your - Linux partition. - - - At the C:\> prompt, type .... - - - - Note - - When showing example computer output (usually in - screen tags), do you include the prompt or command - (unless the command or prompt is the actually computer output you want - to show). - - - - - <command>replaceable</command> - - - XML tags - replaceable - - - - To create replaceable text, you use the tags - <replaceable> and - </replaceable> around the text you want to use as a - variable. - - - This example shows the ISBN of our boxed sets with variables: - - - -1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> - - - - - The output: - - - - 1-58569-xx-y - - - - - <command>screen</command> - - XML tags - screen - - - - The <screen> command is used to format text - within a document and is great for adding emphasis to show examples of - code, computer output, and more. In HTML, this appears in a grey - background. To use this command you only need the opening - <screen> and closing - </screen> tags around the text you are - emphasizing. - - - - 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. - - - - - An example of <screen> is the following: - - - -<screen> -<computeroutput> -This is an example of a screen. You do not need <para> tags -within this command. -</computeroutput> -</screen> - - - - - The output: - - - - -This is an example of a screen. You do not need <para> -tags within this command. - - - - - Note To properly use the - <screen> tag set, you also need to properly - tag the content within the screen. If the content in the screen is a - configuration file or the output of a program, it needs the - <computeroutput> tag set. If it is a command, - it needs the <command> tag set. If it is a - command with user input, it may require a construction like the one - below: - -<command>command <userinput>input</userinput></command> - - - - The output looks like: - - - -command input - - - - - - - Sections - - - XML tags - sections - - - - sections - - - Within an article (or chapter if it is a DocBook XML book like the - &IG;), you can have sections and - subsections. <sect1> is always the highest - section and you cannot have two sections of the same level within one - another (a section 2 can be created within a section 1, but section 1 - has to be closed before another section 1 can be created). The general - layout follows: - - - -<sect1 id="s1-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - - <sect2 id="s2-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - <sect3 id="s3-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - </sect3> - - </sect2> - -</sect1> - - - - - If you only need one level of sections in a DocBook article, you can use - the section tag. For example: - - - - -<section id="sn-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> -</section> -<section id="sn-anothername"> - <title>Insert Title Here</title> - <para> - More body text goes here. - </para> -</section> - - - - - - <command>table</command> - - - XML tags - table - - - - The following is an example of creating a table. - - - -<table id="tb-mockup-before-begin"> - This tells XML that you will be creating a table - and the ID name is "tb-mockup-before-begin." - -<title>Available Features of GNOME and KDE</title> - -<tgroup cols="3"> - This tells XML that you are creating a table - with three columns. - -<colspec colnum="1" colname="Features" colwidth="3"/> - colspec says that you are giving information - about the column to XML colnum="1" - says that you are giving specifications for the first column. - - colname="Features" says that the title for this - column will be "Features." - - colwidth="3" specifies the width of the - column. This can be more tricky: such as two columns with - widths of 1 and 2,the 1 is one-half the width of the 2, in - respect to the page size. But, what if you need the 1 to be a - little more than half of the 2, using a larger number ratio, - such as 10 to 20 would accomplish this. You could then change the - 10 to an 11 or a 12 to make it a little more than half of the - second column of 20. In no value is given, a value of 1 is - assumed. - -<colspec colnum="2" colname="GNOME" colwidth="2"/> -<colspec colnum="3" colname="KDE" colwidth="2"/> - -<thead> - Contains one or more table row elements. - -<row> - Contains one or more table cell (entry) elements. - -<entry>Features</entry> - Table cell element, one of several in a row element, defining - columns within the row. - -<entry>GNOME</entry> -<entry>KDE</entry> -</row> -</thead> - -<tbody> - Contains one or more row elements, for the main text - of the table. - -<row> -<entry>highly configurable</entry> -<entry>yes</entry> -<entry>yes</entry> -</row> -<row> -<entry>multiple window managers </entry> -<entry>yes</entry> -<entry>yes</entry> -</row> -<row> -<entry>Internet applications</entry> -<entry>yes </entry> -<entry>yes </entry> -</row> -</tbody> -</tgroup> -</table> - - - - Available Features of GNOME and KDE - - - - - - - - - Features - GNOME - KDE - - - - - - highly configurable - yes - yes - - - multiple window managers - yes - yes - - - Internet applications - yes - yes - - - -
- - - Creating a List Within a Table - - - XML tags - table - list within a table - - - - Creating a list within a table can be a difficult task. It - requires strict formatting and a set of commands that are not - available for command completion in - Emacs. - - The tags you will need to use are - <simplelist> and - <member>. - - The following example will show you the proper formatting for - creating a list within a table. - - - - -<table id="tb-hardware-powerswitch"> - <title>Power Switch Hardware Table</title> - <tgroup cols="4"> - <colspec colnum="1" colname="Hardware" colwidth="2"/> - <colspec colnum="2" colname="Quantity" colwidth="2"/> - <colspec colnum="3" colname="Description" colwidth="6"/> - <colspec colnum="4" colname="Required" colwidth="2"/> - - <thead> - <row> - <entry>Hardware</entry> - <entry>Quantity</entry> - <entry>Description</entry> - <entry>Required</entry> - </row> - </thead> - - <tbody> - - <row> - <entry>Serial power switches</entry> - - <entry>Two</entry> - - <entry><simplelist> <member>Power switches enable each cluster system - to power-cycle the other cluster system. Note that clusters are - configured with either serial or network attached power switches and - not both.</member> - - <member>The following serial attached power switch has been - fully tested:</member> - - <member>RPS-10 (model M/HD in the US, and model M/EC in - Europe) </member> - - <member>Latent support is provided for the following serial - attached power switch. This switch has not yet been fully - tested:</member> - - <member>APC Serial On/Off Switch (partAP9211), <ulink - url="http://www.apc.com/">http://www.apc.com/</ulink></member> - </simplelist></entry> - - <entry>Strongly recommended for data integrity under all failure - conditions</entry> - - </row> - </tbody> - </tgroup> -</table> - - - - Notice how the <simplelist> tag must be - beside the <entry> tag? If you do not format - this properly, it will not parse cleanly. - - The above example will look like the following: - - - Power Switch Hardware Table - - - - - - - - - Hardware - Quantity - Description - Required - - - - - - - Serial power switches - - Two - - Power switches enable each cluster - system to power-cycle the other cluster system. Note - that clusters are configured with either serial or - network attached power switches and not both. - - The following serial attached power switch has been - fully tested: - - RPS-10 (model M/HD in the US, and model M/EC in - Europe) - - Latent support is provided for the following - serial attached power switch. This switch has not yet - been fully tested: - - APC Serial On/Off Switch (partAP9211), http://www.apc.com/ - - - Strongly recommended for data integrity under all failure - conditions - - - - -
- - - - - - - <command>trademark</command> - - - XML tags - trademark - - - - 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> - - - - - - - <command>userinput</command> - - - XML tags - userinput - - - - To show what a user would type, use the userinput - tag. For example: - - - -At the prompt, type: - -<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> - - - - - The output: - - - - At the prompt, type: - - - - dd if=boot.img of=/dev/fd0 bs=1440k - - - - - - - - <command>ulink</command> - - - XML tags - ulink - - - - To create a URL link within your text, use the following example: - - - -Online &mdash; <ulink url="http://www.redhat.com/support/errata/"> -http://www.redhat.com/support/errata/</ulink>; supplies errata -you can read online, and you can download diskette images easily. - - - - - The output: - - - - Online — - http://www.redhat.com/support/errata/; supplies errata - you can read online, and you can download diskette images easily. - - - - Note - - If the URL does not end in a filename, it must end in a slash - (/) to be a properly formed URL. For - example, http://www.redhat.com/. - - - - - - - <command>wordasword</command> - - - XML tags - wordasword - - - The <wordasword> tag set is used to define a word meant - specifically as a word and not representing anything else. - - A lot of technical documentation contains words that have overloaded - meanings. Sometimes it is useful to be able to use a word without invoking - its technical meaning. The <wordasword> element identifies a word or - phrase that might otherwise be interpreted in some specific way, and - asserts that it should be interpreted simply as a word. - - It is unlikely that the presentation of this element will be able to - help readers understand the variation in meaning; good writing will have - to achieve that goal. The real value of <wordasword> lies in the - fact that full-text searching and indexing tools can use it to avoid - false-positives. - - For example: - - -To use <command>grep</command> to search for the word -<wordasword>linux</wordasword>, use the command -<command>grep linux</command>. - - - - The output: - - - To use grep to search for the word - linux, use the command grep - linux. - - In the example, the word "linux" is just a word. It is not - meant to convey anything about Linux as a subject, or to add relevance or - meaning to the content. It can be replaced with any other word without - losing any of the context. - - - - - - <command>xref</command> - - - XML tags - xref - - - - To refer to other sections or chapters within a manual, use the - <xref> tag. - - - - The output of this displays the title of the section or chapter you are - pointing the user to. For example: - - - -For more information about the parent file, refer to -<xref linkend="ch-tutorial"><xref> and <xref linkend="s1-tutorial-parent"></xref> - - - - - The output: - - - - For more information about the parent file, refer to - and . - - - - diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml index 4560d2b..800b481 100644 --- a/documentation-guide-en.xml +++ b/documentation-guide-en.xml @@ -1,4 +1,4 @@ - + - + - + - - - - - - - - + + + + + + + + ]> diff --git a/documentation-guide.xml b/documentation-guide.xml deleted file mode 100644 index 50fc212..0000000 --- a/documentation-guide.xml +++ /dev/null @@ -1,77 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - -]> - - - - &NAME-TITLE; Documentation Guide - - 2003 - &FORMAL-RHI; - Tammy Fox - Johnray Fuller - Sandra Moore - - - - Fox - Tammy - - - Fuller - Johnray - - - Moore - Sandra - - - &LEGALNOTICE; - - - - &INTRODUCTION; - - &GETTINGFILES; - - &GUIDELINES; - - &EMACS; - - &TAGS; - - &TUTORIAL; - - &CONVERTING; - - &CVS; - - &ACKNOWLEDGMENTS; - - -- cgit