From 8e6d5fdfdbfe0310c80fbc5ef4c7697e9b55e214 Mon Sep 17 00:00:00 2001 From: Tammy Fox Date: Mon, 22 Sep 2003 16:34:23 +0000 Subject: add docs guide --- Makefile | 20 + docs-converting-en.xml | 20 + docs-converting.xml | 20 + docs-emacs-en.xml | 697 +++++++++++++ docs-emacs.xml | 697 +++++++++++++ docs-getting-files-en.xml | 61 ++ docs-getting-files.xml | 61 ++ docs-intro-en.xml | 40 + docs-intro.xml | 40 + docs-rh-guidelines-en.xml | 386 +++++++ docs-rh-guidelines.xml | 386 +++++++ docs-tutorial-en.xml | 98 ++ docs-tutorial.xml | 98 ++ docs-xml-tags-en.xml | 2433 ++++++++++++++++++++++++++++++++++++++++++++ docs-xml-tags.xml | 2433 ++++++++++++++++++++++++++++++++++++++++++++ documentation-guide-en.xml | 74 ++ documentation-guide.xml | 74 ++ 17 files changed, 7638 insertions(+) create mode 100644 Makefile create mode 100644 docs-converting-en.xml create mode 100644 docs-converting.xml create mode 100644 docs-emacs-en.xml create mode 100644 docs-emacs.xml create mode 100644 docs-getting-files-en.xml create mode 100644 docs-getting-files.xml create mode 100644 docs-intro-en.xml create mode 100644 docs-intro.xml create mode 100644 docs-rh-guidelines-en.xml create mode 100644 docs-rh-guidelines.xml create mode 100644 docs-tutorial-en.xml create mode 100644 docs-tutorial.xml create mode 100644 docs-xml-tags-en.xml create mode 100644 docs-xml-tags.xml create mode 100644 documentation-guide-en.xml create mode 100644 documentation-guide.xml diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ad86a22 --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +############################################################################### +# Makefile for community charter +# Created by: Tammy Fox +# Last edited by: Tammy Fox +# WARNING: need passivetex 1.24 for pdf generation to work +############################################################################### + +XSLPDF = ../xsl/main-pdf.xsl +XSLHTML = ../xsl/main-html.xsl + +all: html pdf + +html: documentation-guide.xml + @xmlto html -x $(XSLHTML) -o documentation-guide $< + +pdf: documentation-guide.xml + @xmlto pdf -x $(XSLPDF) $< + +clean: + @rm -rfv *.html *.pdf *.tex documentation-guide/ diff --git a/docs-converting-en.xml b/docs-converting-en.xml new file mode 100644 index 0000000..ac0684b --- /dev/null +++ b/docs-converting-en.xml @@ -0,0 +1,20 @@ + + + + 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-converting.xml b/docs-converting.xml new file mode 100644 index 0000000..809747c --- /dev/null +++ b/docs-converting.xml @@ -0,0 +1,20 @@ + + + + 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-en.xml b/docs-emacs-en.xml new file mode 100644 index 0000000..53b8126 --- /dev/null +++ b/docs-emacs-en.xml @@ -0,0 +1,697 @@ + + + + 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-emacs.xml b/docs-emacs.xml new file mode 100644 index 0000000..8133bf0 --- /dev/null +++ b/docs-emacs.xml @@ -0,0 +1,697 @@ + + + + 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-en.xml b/docs-getting-files-en.xml new file mode 100644 index 0000000..db4cdf4 --- /dev/null +++ b/docs-getting-files-en.xml @@ -0,0 +1,61 @@ + + + + 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-getting-files.xml b/docs-getting-files.xml new file mode 100644 index 0000000..5a4a716 --- /dev/null +++ b/docs-getting-files.xml @@ -0,0 +1,61 @@ + + + + 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-en.xml b/docs-intro-en.xml new file mode 100644 index 0000000..905edde --- /dev/null +++ b/docs-intro-en.xml @@ -0,0 +1,40 @@ + + + + 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-intro.xml b/docs-intro.xml new file mode 100644 index 0000000..44b1990 --- /dev/null +++ b/docs-intro.xml @@ -0,0 +1,40 @@ + + + + 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-en.xml b/docs-rh-guidelines-en.xml new file mode 100644 index 0000000..fd4f72c --- /dev/null +++ b/docs-rh-guidelines-en.xml @@ -0,0 +1,386 @@ + + &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-en.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-rh-guidelines.xml b/docs-rh-guidelines.xml new file mode 100644 index 0000000..2d39357 --- /dev/null +++ b/docs-rh-guidelines.xml @@ -0,0 +1,386 @@ + + &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-en.xml b/docs-tutorial-en.xml new file mode 100644 index 0000000..16f6bd9 --- /dev/null +++ b/docs-tutorial-en.xml @@ -0,0 +1,98 @@ + + + + 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-tutorial.xml b/docs-tutorial.xml new file mode 100644 index 0000000..e453830 --- /dev/null +++ b/docs-tutorial.xml @@ -0,0 +1,98 @@ + + + + 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-en.xml b/docs-xml-tags-en.xml new file mode 100644 index 0000000..bc43f8b --- /dev/null +++ b/docs-xml-tags-en.xml @@ -0,0 +1,2433 @@ + + + + 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-en.xml,v 1.1 2003/09/22 16:34:23 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> + <para> + Some text description of this image + </para> + </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 + +<para>Some text description of this image</para> ==> "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/docs-xml-tags.xml b/docs-xml-tags.xml new file mode 100644 index 0000000..f391902 --- /dev/null +++ b/docs-xml-tags.xml @@ -0,0 +1,2433 @@ + + + + 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.1 2003/09/22 16:34:23 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> + <para> + Some text description of this image + </para> + </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 + +<para>Some text description of this image</para> ==> "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 new file mode 100644 index 0000000..fe82600 --- /dev/null +++ b/documentation-guide-en.xml @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + + &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; + + diff --git a/documentation-guide.xml b/documentation-guide.xml new file mode 100644 index 0000000..cb266ab --- /dev/null +++ b/documentation-guide.xml @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + + &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; + + -- cgit