diff options
| -rw-r--r-- | Makefile | 20 | ||||
| -rw-r--r-- | docs-converting-en.xml | 20 | ||||
| -rw-r--r-- | docs-converting.xml | 20 | ||||
| -rw-r--r-- | docs-emacs-en.xml | 697 | ||||
| -rw-r--r-- | docs-emacs.xml | 697 | ||||
| -rw-r--r-- | docs-getting-files-en.xml | 61 | ||||
| -rw-r--r-- | docs-getting-files.xml | 61 | ||||
| -rw-r--r-- | docs-intro-en.xml | 40 | ||||
| -rw-r--r-- | docs-intro.xml | 40 | ||||
| -rw-r--r-- | docs-rh-guidelines-en.xml | 386 | ||||
| -rw-r--r-- | docs-rh-guidelines.xml | 386 | ||||
| -rw-r--r-- | docs-tutorial-en.xml | 98 | ||||
| -rw-r--r-- | docs-tutorial.xml | 98 | ||||
| -rw-r--r-- | docs-xml-tags-en.xml | 2433 | ||||
| -rw-r--r-- | docs-xml-tags.xml | 2433 | ||||
| -rw-r--r-- | documentation-guide-en.xml | 74 | ||||
| -rw-r--r-- | documentation-guide.xml | 74 |
17 files changed, 7638 insertions, 0 deletions
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 <tfox@redhat.com> +# Last edited by: Tammy Fox <tfox@redhat.com> +# 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 @@ +<!-- $Id: docs-converting-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + +<chapter id="ch-converting"> + <title>Converting to HTML and PDF</title> + + <para> + Each directory containing a document also has a Makefile. In the directory, + run the command <command>make html</command> to build the HTML version and + <command>make pdf</command> to build the PDF version. + </para> + + <warning> + <title>Warning</title> + <para> + The PDF production is somewhat fragile right now. It may or may not + work. + </para> + </warning> + +</chapter> 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 @@ +<!-- $Id: docs-converting.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + +<chapter id="ch-converting"> + <title>Converting to HTML and PDF</title> + + <para> + Each directory containing a document also has a Makefile. In the directory, + run the command <command>make html</command> to build the HTML version and + <command>make pdf</command> to build the PDF version. + </para> + + <warning> + <title>Warning</title> + <para> + The PDF production is somewhat fragile right now. It may or may not + work. + </para> + </warning> + +</chapter> 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 @@ +<!-- $Id: docs-emacs-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-emacs"> + <title>Emacs and PSGML Mode</title> + + <indexterm> + <primary>PSGML</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>PSGML mode</secondary> + </indexterm> + + <para> + 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. + </para> + + <sect1 id="s1-emacs-file"> + <title>Setting Up Your <filename>.emacs</filename> File</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>configuration file</secondary> + </indexterm> + + <indexterm> + <primary><filename>.emacs</filename></primary> + </indexterm> + + <para> + For Emacs to parse your DocBook documents correctly, you must have a + <filename>.emacs</filename> file. Cut and paste the following into your + existing <filename>.emacs</filename> file or create a new one that + contains the following lines: + +<screen> +<computeroutput> +;; 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)))) + +</computeroutput> +</screen> + + </para> + + <para> + Do you have a cool wheel mouse? If so, you can add the following to your + <filename>.emacs</filename> file so your wheel will work in + <application>Emacs</application> (must be + <application>Emacs</application> version 21): + </para> + +<screen> +<computeroutput> +;; Enable wheelmouse support by default for emacs 21 +(cond (window-system +(mwheel-install) +)) +</computeroutput> +</screen> + + <para> + If you are using the older version 20 of + <application>Emacs</application>, add the following instead: + </para> +<screen> +<computeroutput> +;; Enable wheelmouse support by default +(require 'mwheel) +</computeroutput> +</screen> + + </sect1> + + + <sect1 id="s1-emacs-colors"> + <title>Customizing Emacs</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>customizing</secondary> + </indexterm> + + <indexterm> + <primary><filename>.Xresources</filename></primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>colors</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>font</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>geometry</secondary> + </indexterm> + + <para> + The colors, font, and geometry (default size of window) for Emacs in your + <filename>~/.Xresources</filename> file. The format for the settings is + <computeroutput>emacs.keyword:value</computeroutput> + </para> + + <para> + The following is a sample <filename>~/.Xresources</filename> file. + </para> + <note> + <title>Note</title> + <para>If you have other settings in your + <filename>~/.Xresources</filename>, add the following to the end of + the file. + </para> + </note> + +<screen> +<userinput> +emacs.background: light gray +emacs.foreground: black +emacs.pointerColor: blue +emacs.cursorColor: blue +emacs.bitmapIcon: on +emacs.font: fixed +emacs.geometry: 90x25 +</userinput> +</screen> + <para> + After modifying this file, you must execute the command + </para> +<screen> +<command>xrdb -merge ~/.Xresources</command> +</screen> + <para> + and restart <application>Emacs</application> for the changes to take + place. + </para> + + </sect1> + + <sect1 id="s1-emacs-cedfile"> + <title>Create Recompiled DTD Subset</title> + + <para> + 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. + </para> + + <para> + To create a loadable Parsed DTD file: + <orderedlist> + <listitem> + <para>Find the parent file for the group of DocBook files. You will + recognize this file by the header <filename><!DOCTYPE article + PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</filename>. An easy way + to find this parent file is to use the command <command>grep + DocBook *.xml</command>. Once you find the parent file, open it + in Emacs with the command <command>emacs + <replaceable><parentfile></replaceable>.xml</command> (where + <replaceable><parentfile></replaceable>.xml is the parent + file you found. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Parse DTD</command> from the pulldown + menu. + </para> + </listitem> + + <listitem> + <para>You will know the parsing is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Save the parsed DTD to a file by choosing + <command>DTD -> Save Parsed DTD</command> from the pulldown menu. + </para> + </listitem> + + <listitem> + <para>Press <keycap>Enter</keycap> to save the file to the default + filename or rename the file keeping the <filename>.ced</filename> + extension. It can be useful to name it something generic such as + <filename>docbook.ced</filename> so you can refer to it when + opening all DocBook files. This file can also be copied from + directory to directory to be loaded. + </para> + </listitem> + + </orderedlist> + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-parse-prolog</command> to parse the file, and then use the + command <command>Meta-x sgml-save-dtd</command> to save the parsed DTD + to a <filename>.ced</filename> file. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-loadced"> + <title>Load the Parsed DTD</title> + + <para> + Now that you have saved the DTD settings, you can load the + <filename>.ced</filename> file and see the syntax highlighting for your + <filename>.sgml</filename> files. + </para> + + <para> + To load a parsed DTD file: + <orderedlist> + <listitem> + <para>Open an XML file in Emacs. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Load DTD</command> from the pulldown menu + and choose the file you saved from the previous step. For + instance, choose <filename>docbook.ced</filename>. + </para> + </listitem> + + <listitem> + <para>You will know it is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Loading the parsed DTD might take a long time. + You can start editing the file before it finishes. + </para> + </listitem> + + </orderedlist> + + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-load-dtd</command> to load the parsed DTD. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-basic-commands"> + <title>Basic Emacs Commands</title> + + <para> + The <keycap>Meta</keycap> key is usually the <keycap>Alt</keycap> key. + </para> + + <table frame="all" rowsep="1" colsep="1" id="tb-emacs-commands"> + <title>Emacs Commands</title> + <tgroup rowsep="1" colsep="1" cols="2"> + <colspec colnum="1" colname="shortcut" colwidth="170"/> + <colspec colnum="2" colname="description" colwidth="300"/> + + <thead> + <row> + <entry rowsep="1" colsep="1">Shortcut</entry> + <entry rowsep="1" colsep="1">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry rowsep="1" colsep="1"><keycombo> + <keycap>Meta</keycap><keycap>x</keycap></keycombo> + sgml-parse-prolog, <keycap>Enter</keycap></entry> + <entry>Parse DTD</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-save-dtd, <keycap>Enter</keycap></entry> + <entry>Save the Parse DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-load-dtd, <keycap>Enter</keycap></entry> + <entry>Load DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap></keycombo>, <keycap>Tab</keycap></entry> + <entry>Display list of valid tags</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap> </keycombo>, type beginning of tag, + <keycap>Tab</keycap></entry> + <entry>Complete the tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>g</keycap> + </keycombo></entry> + <entry>Cancel a command in the minibuffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycap>/</keycap></entry> + <entry>Close tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>a</keycap> + </keycombo></entry> + <entry>Move cursor to beginning of line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>e</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>Home</keycap> + </keycombo></entry> + <entry>Move cursor to the beginning of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>End</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>k</keycap> + </keycombo></entry> + <entry>Cut line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>y</keycap> + </keycombo></entry> + <entry>Paste line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>s</keycap> + </keycombo></entry> + <entry>Search forward in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>r</keycap> + </keycombo></entry> + <entry>Search backwards in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>$</keycap> + </keycombo></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-word, <keycap>Enter</keycap></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-buffer, <keycap>Enter</keycap></entry> + <entry>Check spelling of current buffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap> + </keycombo></entry> + <entry>Open file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>s</keycap> + </keycombo></entry> + <entry>Save file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit <application>Emacs</application> and prompt to save + files if necessary</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap> <keycap>q</keycap> + </keycombo></entry> + <entry>Fill paragraph</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>a</keycap> + </keycombo></entry> + <entry>Edit attributes for a tag (for example, you can edit the + <computeroutput>url</computeroutput> attribute of the + <computeroutput>ulink</computeroutput> tag)</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, + <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit edit attributes</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-emacs-examples"> + <title>Examples</title> + + <para> + 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. + </para> + + <sect2 id="s2-emacs-tag-completion"> + <title>Tag Completion</title> + + <note> + <title>Note</title> + <para>This section assumes that you have already loaded the DTD file + (<filename>.ced</filename>). + </para> + </note> + + <para> + Instead of typing a tag each time you need to use it, use + the key combination <keycap>Ctrl</keycap>-<keycap>c</keycap>, + followed by <keycap><</keycap>. At the bottom of the + <application>Emacs</application> window, you will see: + </para> +<screen> +<computeroutput>Tag: <</computeroutput> +</screen> + + <para> + To view a list of available tags, use either the <keycap>Tab</keycap> + or <keycap>?</keycap>. Or, if you know the first few letters of a tag, + you can enter them followed by <keycap>Tab</keycap> for a complete + list of available tags beginning with those letters or for a tag + completion. + </para> + + <para> + Try the following: Type <keycap>Ctrl</keycap>-<keycap>c</keycap> + followed by <keycap><</keycap>. Then enter the letter + <keycap>k</keycap>, followed by <keycap>Tab</keycap>. You may have to + use the <keycap>Tab</keycap> key several times to get a complete list. + </para> + + <para> + The output should look similar to the example below: + </para> + +<screen> +<computeroutput> +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> +</computeroutput> +</screen> + + </sect2> + <sect2 id="s2-emacs-tag-closing"> + <title>Tag Closure</title> + + <para> + 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 + <keycap>Ctrl</keycap>-<keycap>c</keycap>, followed by + <keycap>/</keycap>. This will close the closest open tag you have. + </para> + + </sect2> + + <sect2 id="s2-emacs-other"> + <title>Other Emacs Tasks</title> + + <para> + <guilabel>Working with one window</guilabel>: Sometimes in + <application>Emacs</application> 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 <keycap>Ctrl</keycap>-<keycap>x</keycap>, followed by + <keycap>1</keycap>. + </para> + + <para> + <guilabel>Saving your work</guilabel>: To save your work, use the + following keycombo, <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>s</keycap>. + </para> + + <para> + <guilabel>The "clear/quit" command</guilabel>: 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 <keycap>Ctrl</keycap>-<keycap>g</keycap>. This command quits + what you have been doing within the file, without quitting the file + itself. + </para> + + <para> + <guilabel>Opening a new file</guilabel>: To open a new file, use the + keycombo <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>f</keycap>. At the bottom of the emacs + window, you will be able to enter in the file name (using + <keycap>Tab</keycap> completion if needed) of the file you wish to + open. + </para> + + <para> + <guilabel>Closing emacs</guilabel>: The easiest way to close + <application>emacs</application> is to use the keycombo + <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>c</keycap>. 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. + </para> + </sect2> + + </sect1> + + <sect1 id="s1-emacs-additional-resources"> + <title>Additional Resources</title> + + <para> Additional Emacs and PSGML references are available at the + following locations: + </para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://wks.uts.ohio-state.edu/unix_course/intro-135.html">http://wks.uts.ohio-state.edu/unix_course/intro-135.html</ulink> + — <citetitle>Emacs Quick Reference Guide</citetitle> + </para> + </listitem> + <listitem> <para>Emacs reference card that comes with the + <filename>emacs</filename> package. You can print it out as a + reference. — + <filename>/usr/share/emacs/<replaceable><version></replaceable>/etc/refcard.ps</filename> + </para> + </listitem> + <listitem> + <para>Read <citetitle>Editing XML with Emacs and PSGML</citetitle> + in <filename>/usr/share/doc/psgml-<replaceable><version></replaceable>/psgml.ps</filename>. </para> + </listitem> + </itemizedlist> + + </sect1> + </chapter> + + + + + + + + + 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 @@ +<!-- $Id: docs-emacs.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-emacs"> + <title>Emacs and PSGML Mode</title> + + <indexterm> + <primary>PSGML</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>PSGML mode</secondary> + </indexterm> + + <para> + 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. + </para> + + <sect1 id="s1-emacs-file"> + <title>Setting Up Your <filename>.emacs</filename> File</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>configuration file</secondary> + </indexterm> + + <indexterm> + <primary><filename>.emacs</filename></primary> + </indexterm> + + <para> + For Emacs to parse your DocBook documents correctly, you must have a + <filename>.emacs</filename> file. Cut and paste the following into your + existing <filename>.emacs</filename> file or create a new one that + contains the following lines: + +<screen> +<computeroutput> +;; 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)))) + +</computeroutput> +</screen> + + </para> + + <para> + Do you have a cool wheel mouse? If so, you can add the following to your + <filename>.emacs</filename> file so your wheel will work in + <application>Emacs</application> (must be + <application>Emacs</application> version 21): + </para> + +<screen> +<computeroutput> +;; Enable wheelmouse support by default for emacs 21 +(cond (window-system +(mwheel-install) +)) +</computeroutput> +</screen> + + <para> + If you are using the older version 20 of + <application>Emacs</application>, add the following instead: + </para> +<screen> +<computeroutput> +;; Enable wheelmouse support by default +(require 'mwheel) +</computeroutput> +</screen> + + </sect1> + + + <sect1 id="s1-emacs-colors"> + <title>Customizing Emacs</title> + + <indexterm> + <primary>Emacs</primary> + <secondary>customizing</secondary> + </indexterm> + + <indexterm> + <primary><filename>.Xresources</filename></primary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>colors</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>font</secondary> + </indexterm> + + <indexterm> + <primary>Emacs</primary> + <secondary>geometry</secondary> + </indexterm> + + <para> + The colors, font, and geometry (default size of window) for Emacs in your + <filename>~/.Xresources</filename> file. The format for the settings is + <computeroutput>emacs.keyword:value</computeroutput> + </para> + + <para> + The following is a sample <filename>~/.Xresources</filename> file. + </para> + <note> + <title>Note</title> + <para>If you have other settings in your + <filename>~/.Xresources</filename>, add the following to the end of + the file. + </para> + </note> + +<screen> +<userinput> +emacs.background: light gray +emacs.foreground: black +emacs.pointerColor: blue +emacs.cursorColor: blue +emacs.bitmapIcon: on +emacs.font: fixed +emacs.geometry: 90x25 +</userinput> +</screen> + <para> + After modifying this file, you must execute the command + </para> +<screen> +<command>xrdb -merge ~/.Xresources</command> +</screen> + <para> + and restart <application>Emacs</application> for the changes to take + place. + </para> + + </sect1> + + <sect1 id="s1-emacs-cedfile"> + <title>Create Recompiled DTD Subset</title> + + <para> + 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. + </para> + + <para> + To create a loadable Parsed DTD file: + <orderedlist> + <listitem> + <para>Find the parent file for the group of DocBook files. You will + recognize this file by the header <filename><!DOCTYPE article + PUBLIC "-//OASIS//DTD DocBook V4.1//EN"</filename>. An easy way + to find this parent file is to use the command <command>grep + DocBook *.xml</command>. Once you find the parent file, open it + in Emacs with the command <command>emacs + <replaceable><parentfile></replaceable>.xml</command> (where + <replaceable><parentfile></replaceable>.xml is the parent + file you found. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Parse DTD</command> from the pulldown + menu. + </para> + </listitem> + + <listitem> + <para>You will know the parsing is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Save the parsed DTD to a file by choosing + <command>DTD -> Save Parsed DTD</command> from the pulldown menu. + </para> + </listitem> + + <listitem> + <para>Press <keycap>Enter</keycap> to save the file to the default + filename or rename the file keeping the <filename>.ced</filename> + extension. It can be useful to name it something generic such as + <filename>docbook.ced</filename> so you can refer to it when + opening all DocBook files. This file can also be copied from + directory to directory to be loaded. + </para> + </listitem> + + </orderedlist> + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-parse-prolog</command> to parse the file, and then use the + command <command>Meta-x sgml-save-dtd</command> to save the parsed DTD + to a <filename>.ced</filename> file. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-loadced"> + <title>Load the Parsed DTD</title> + + <para> + Now that you have saved the DTD settings, you can load the + <filename>.ced</filename> file and see the syntax highlighting for your + <filename>.sgml</filename> files. + </para> + + <para> + To load a parsed DTD file: + <orderedlist> + <listitem> + <para>Open an XML file in Emacs. + </para> + </listitem> + + <listitem> + <para>Choose <command>DTD -> Load DTD</command> from the pulldown menu + and choose the file you saved from the previous step. For + instance, choose <filename>docbook.ced</filename>. + </para> + </listitem> + + <listitem> + <para>You will know it is finished when you see the message + <computeroutput>Fontifying...done</computeroutput> at the bottom + of your screen. Loading the parsed DTD might take a long time. + You can start editing the file before it finishes. + </para> + </listitem> + + </orderedlist> + + </para> + + <tip> + <title>Tip</title> + <para> + You can also use the Emacs command <command>Meta-x + sgml-load-dtd</command> to load the parsed DTD. + </para> + </tip> + + </sect1> + + <sect1 id="s1-emacs-basic-commands"> + <title>Basic Emacs Commands</title> + + <para> + The <keycap>Meta</keycap> key is usually the <keycap>Alt</keycap> key. + </para> + + <table frame="all" rowsep="1" colsep="1" id="tb-emacs-commands"> + <title>Emacs Commands</title> + <tgroup rowsep="1" colsep="1" cols="2"> + <colspec colnum="1" colname="shortcut" colwidth="170"/> + <colspec colnum="2" colname="description" colwidth="300"/> + + <thead> + <row> + <entry rowsep="1" colsep="1">Shortcut</entry> + <entry rowsep="1" colsep="1">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry rowsep="1" colsep="1"><keycombo> + <keycap>Meta</keycap><keycap>x</keycap></keycombo> + sgml-parse-prolog, <keycap>Enter</keycap></entry> + <entry>Parse DTD</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-save-dtd, <keycap>Enter</keycap></entry> + <entry>Save the Parse DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Meta</keycap><keycap>x</keycap> + </keycombo>sgml-load-dtd, <keycap>Enter</keycap></entry> + <entry>Load DTD</entry> + </row> + <row> + <entry><keycombo> <keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap></keycombo>, <keycap>Tab</keycap></entry> + <entry>Display list of valid tags</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycombo> <keycap>Shift</keycap> + <keycap></keycap> </keycombo>, type beginning of tag, + <keycap>Tab</keycap></entry> + <entry>Complete the tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>g</keycap> + </keycombo></entry> + <entry>Cancel a command in the minibuffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, <keycap>/</keycap></entry> + <entry>Close tag</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>a</keycap> + </keycombo></entry> + <entry>Move cursor to beginning of line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>e</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>Home</keycap> + </keycombo></entry> + <entry>Move cursor to the beginning of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>End</keycap> + </keycombo></entry> + <entry>Move cursor to the end of the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>k</keycap> + </keycombo></entry> + <entry>Cut line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>y</keycap> + </keycombo></entry> + <entry>Paste line</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>s</keycap> + </keycombo></entry> + <entry>Search forward in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>r</keycap> + </keycombo></entry> + <entry>Search backwards in the file</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>$</keycap> + </keycombo></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-word, <keycap>Enter</keycap></entry> + <entry>Check spelling of current word</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap><keycap>x</keycap> + </keycombo> ispell-buffer, <keycap>Enter</keycap></entry> + <entry>Check spelling of current buffer</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>f</keycap> + </keycombo></entry> + <entry>Open file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>s</keycap> + </keycombo></entry> + <entry>Save file</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>x</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit <application>Emacs</application> and prompt to save + files if necessary</entry> + </row> + <row> + <entry><keycombo><keycap>Meta</keycap> <keycap>q</keycap> + </keycombo></entry> + <entry>Fill paragraph</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo>, <keycombo><keycap>Ctrl</keycap><keycap>a</keycap> + </keycombo></entry> + <entry>Edit attributes for a tag (for example, you can edit the + <computeroutput>url</computeroutput> attribute of the + <computeroutput>ulink</computeroutput> tag)</entry> + </row> + <row> + <entry><keycombo><keycap>Ctrl</keycap> <keycap>c</keycap> + </keycombo>, + <keycombo><keycap>Ctrl</keycap><keycap>c</keycap> + </keycombo></entry> + <entry>Exit edit attributes</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-emacs-examples"> + <title>Examples</title> + + <para> + 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. + </para> + + <sect2 id="s2-emacs-tag-completion"> + <title>Tag Completion</title> + + <note> + <title>Note</title> + <para>This section assumes that you have already loaded the DTD file + (<filename>.ced</filename>). + </para> + </note> + + <para> + Instead of typing a tag each time you need to use it, use + the key combination <keycap>Ctrl</keycap>-<keycap>c</keycap>, + followed by <keycap><</keycap>. At the bottom of the + <application>Emacs</application> window, you will see: + </para> +<screen> +<computeroutput>Tag: <</computeroutput> +</screen> + + <para> + To view a list of available tags, use either the <keycap>Tab</keycap> + or <keycap>?</keycap>. Or, if you know the first few letters of a tag, + you can enter them followed by <keycap>Tab</keycap> for a complete + list of available tags beginning with those letters or for a tag + completion. + </para> + + <para> + Try the following: Type <keycap>Ctrl</keycap>-<keycap>c</keycap> + followed by <keycap><</keycap>. Then enter the letter + <keycap>k</keycap>, followed by <keycap>Tab</keycap>. You may have to + use the <keycap>Tab</keycap> key several times to get a complete list. + </para> + + <para> + The output should look similar to the example below: + </para> + +<screen> +<computeroutput> +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> +</computeroutput> +</screen> + + </sect2> + <sect2 id="s2-emacs-tag-closing"> + <title>Tag Closure</title> + + <para> + 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 + <keycap>Ctrl</keycap>-<keycap>c</keycap>, followed by + <keycap>/</keycap>. This will close the closest open tag you have. + </para> + + </sect2> + + <sect2 id="s2-emacs-other"> + <title>Other Emacs Tasks</title> + + <para> + <guilabel>Working with one window</guilabel>: Sometimes in + <application>Emacs</application> 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 <keycap>Ctrl</keycap>-<keycap>x</keycap>, followed by + <keycap>1</keycap>. + </para> + + <para> + <guilabel>Saving your work</guilabel>: To save your work, use the + following keycombo, <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>s</keycap>. + </para> + + <para> + <guilabel>The "clear/quit" command</guilabel>: 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 <keycap>Ctrl</keycap>-<keycap>g</keycap>. This command quits + what you have been doing within the file, without quitting the file + itself. + </para> + + <para> + <guilabel>Opening a new file</guilabel>: To open a new file, use the + keycombo <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>f</keycap>. At the bottom of the emacs + window, you will be able to enter in the file name (using + <keycap>Tab</keycap> completion if needed) of the file you wish to + open. + </para> + + <para> + <guilabel>Closing emacs</guilabel>: The easiest way to close + <application>emacs</application> is to use the keycombo + <keycap>Ctrl</keycap>-<keycap>x</keycap> followed by + <keycap>Ctrl</keycap>-<keycap>c</keycap>. 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. + </para> + </sect2> + + </sect1> + + <sect1 id="s1-emacs-additional-resources"> + <title>Additional Resources</title> + + <para> Additional Emacs and PSGML references are available at the + following locations: + </para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://wks.uts.ohio-state.edu/unix_course/intro-135.html">http://wks.uts.ohio-state.edu/unix_course/intro-135.html</ulink> + — <citetitle>Emacs Quick Reference Guide</citetitle> + </para> + </listitem> + <listitem> <para>Emacs reference card that comes with the + <filename>emacs</filename> package. You can print it out as a + reference. — + <filename>/usr/share/emacs/<replaceable><version></replaceable>/etc/refcard.ps</filename> + </para> + </listitem> + <listitem> + <para>Read <citetitle>Editing XML with Emacs and PSGML</citetitle> + in <filename>/usr/share/doc/psgml-<replaceable><version></replaceable>/psgml.ps</filename>. </para> + </listitem> + </itemizedlist> + + </sect1> + </chapter> + + + + + + + + + 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 @@ +<!-- $Id: docs-getting-files-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-getting-files"> + <title>Getting the Files</title> + + <para> + To start working on the Docs Project, you will need the appropriate + DocBook XML files, stylesheets, and scripts. The following packages are + required: + </para> + + <itemizedlist> + <listitem> + <para><filename>xmlto</filename> — for producing HTML and PDF outputs</para> + </listitem> + <listitem> + <para><filename>docbook-style-xsl</filename> — for the default XSLT stylesheets we + build on</para> + </listitem> + <listitem> + <para><filename>docbook-dtds</filename> — XML versions of the DocBook DTD</para> + </listitem> + </itemizedlist> + + <para> + The custom scripts and stylesheets used are all stored in CVS on the + <computeroutput>rhlinux.redhat.com</computeroutput> CVS server. + </para> + + <para> + You need to check them out along with the DocBook XML files for the + existing docs. + </para> + + <para> + To check out the scripts anonymously: + </para> + +<screen> +<command>export CVSROOT=:pserver:anonymous@rhlinux.redhat.com:/usr/local/CVS</command> +<command>cvs -z3 login</command> +<command>cvs -z3 co fedora-docs</command> +</screen> + + <para> + 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. + </para> + + <para> + Except for the <citetitle>&IG;</citetitle>, all docs must be tutorials + written in DocBook XML article format using the template in the + <filename>example-tutorial</filename> directory. Each tutorial + <emphasis>must</emphasis> be in its own directory. No XML files should be + in the root directory except for files shared by all documents such + <filename>legalnotice.xml</filename>, which must be included in all docs + so that the FDL is used for all docs. + </para> + + </chapter> 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 @@ +<!-- $Id: docs-getting-files.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-getting-files"> + <title>Getting the Files</title> + + <para> + To start working on the Docs Project, you will need the appropriate + DocBook XML files, stylesheets, and scripts. The following packages are + required: + </para> + + <itemizedlist> + <listitem> + <para><filename>xmlto</filename> — for producing HTML and PDF outputs</para> + </listitem> + <listitem> + <para><filename>docbook-style-xsl</filename> — for the default XSLT stylesheets we + build on</para> + </listitem> + <listitem> + <para><filename>docbook-dtds</filename> — XML versions of the DocBook DTD</para> + </listitem> + </itemizedlist> + + <para> + The custom scripts and stylesheets used are all stored in CVS on the + <computeroutput>rhlinux.redhat.com</computeroutput> CVS server. + </para> + + <para> + You need to check them out along with the DocBook XML files for the + existing docs. + </para> + + <para> + To check out the scripts anonymously: + </para> + +<screen> +<command>export CVSROOT=:pserver:anonymous@rhlinux.redhat.com:/usr/local/CVS</command> +<command>cvs -z3 login</command> +<command>cvs -z3 co fedora-docs</command> +</screen> + + <para> + 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. + </para> + + <para> + Except for the <citetitle>&IG;</citetitle>, all docs must be tutorials + written in DocBook XML article format using the template in the + <filename>example-tutorial</filename> directory. Each tutorial + <emphasis>must</emphasis> be in its own directory. No XML files should be + in the root directory except for files shared by all documents such + <filename>legalnotice.xml</filename>, which must be included in all docs + so that the FDL is used for all docs. + </para> + + </chapter> 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 @@ +<!-- $Id: docs-intro-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <preface id="ch-intro"> + <title>Introduction</title> + + <para> + The goal of the Docs Project is to create easy-to-follow, task-based + documentation for &DISTRO; users and developers. Other than the + <citetitle>&IG;</citetitle>, 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. + </para> + + <para> + The following tools are used: + </para> + + <itemizedlist> + <listitem> + <para>DocBook XML v4.1</para> + </listitem> + <listitem> + <para>Custom XSLT stylesheets for both print and HTML versions</para> + </listitem> + <listitem> + <para>Custom scripts to generate PDF and HTML output (use <command>xmlto</command>)</para> + </listitem> + <listitem> + <para>Emacs with PSGML mode (optional, but recommended)</para> + </listitem> + </itemizedlist> + + <para> + 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. + </para> + + </preface> 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 @@ +<!-- $Id: docs-intro.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <preface id="ch-intro"> + <title>Introduction</title> + + <para> + The goal of the Docs Project is to create easy-to-follow, task-based + documentation for &DISTRO; users and developers. Other than the + <citetitle>&IG;</citetitle>, 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. + </para> + + <para> + The following tools are used: + </para> + + <itemizedlist> + <listitem> + <para>DocBook XML v4.1</para> + </listitem> + <listitem> + <para>Custom XSLT stylesheets for both print and HTML versions</para> + </listitem> + <listitem> + <para>Custom scripts to generate PDF and HTML output (use <command>xmlto</command>)</para> + </listitem> + <listitem> + <para>Emacs with PSGML mode (optional, but recommended)</para> + </listitem> + </itemizedlist> + + <para> + 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. + </para> + + </preface> 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 @@ + <chapter id="ch-rh-guidelines"> + <title>&RH; Documentation Guidelines</title> + + <indexterm> + <primary>recursion</primary> + <see>recursion</see> + </indexterm> + + <indexterm> + <primary>RTFM</primary> + <secondary>read the f*'ing manual</secondary> + <seealso>humor</seealso> + </indexterm> + + <indexterm> + <primary>humor</primary> + <secondary>RTFM</secondary> + </indexterm> + + <para>Please read this chapter carefully. This chapter describes the + guidelines that must be followed such as naming conventions. + </para> + + <sect1 id="s1-xml-guidelines-naming"> + <title>ID Naming Conventions</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>naming conventions</secondary> + </indexterm> + + <indexterm> + <primary>naming conventions</primary> + </indexterm> + + <para>You will see certain ID names referred to below and this will + help to explain how we come up with those names. For example: + </para> + +<screen> +<computeroutput> +<chapter id="ch-uniquename"> + +<sect3="s3-install-make-disks"> + +<figure id="fig-redhat-config-kickstart-basic"> +</computeroutput> +</screen> + + <para>IDs are unique identifiers, allowing DocBook XML to know where to + cross-reference a section or chapter or the like. + </para> + + <para>The general rules for defining an ID are:</para> + + <indexterm> + <primary>XML tags</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> + + <indexterm> + <primary>naming conventions</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> + + <itemizedlist> + <listitem> + <para>Keep it 32 characters or under (this is counted as + everything between the quotation marks)</para> + </listitem> + <listitem> + <para>Keep it as short and simple as possible</para> + </listitem> + <listitem> + <para>Make sure the name is relevant to the information (make it + recognizable)</para> + </listitem> + </itemizedlist> + + <para>Some examples are <command>"ch-uniquename"</command> (with 13 + characters) and <command>"s3-install-make-disks"</command> (with 21 + characters). + </para> + + <para>A section within a particular chapter always uses the chapter + name (minus the <command>"ch-"</command>) in its ID. For example, you + are working with the <command>"ch-intro"</command> chapter and need to + create your first section on disk partitions. That section ID would look + similar to <command>"s1-intro-partition"</command> which contains the + section number, the main chapter ID, and a unique ID for that section. + </para> + + <table id="tb-xml-namingconventions"> + <title>Naming Conventions</title> + + <tgroup cols="2"> + <colspec colnum="1" colname="tag" colwidth="100"/> + <colspec colnum="2" colname="prefix" colwidth="100"/> + <thead> + <row> + <entry>Tag</entry> + <entry>Prefix</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preface</command></entry> + <entry><computeroutput>pr-</computeroutput></entry> + </row> + <row> + <entry><command>chapter</command></entry> + <entry><computeroutput>ch-</computeroutput></entry> + </row> + <row> + <entry><command>section</command></entry> + <entry><computeroutput>sn-</computeroutput></entry> + </row> + <row> + <entry><command>sect1</command></entry> + <entry><computeroutput>s1-</computeroutput></entry> + </row> + <row> + <entry><command>sect2</command></entry> + <entry><computeroutput>s2-</computeroutput></entry> + </row> + <row> + <entry><command>sect3</command></entry> + <entry><computeroutput>s3-</computeroutput></entry> + </row> + <row> + <entry><command>sect4</command></entry> + <entry><computeroutput>s4-</computeroutput></entry> + </row> + <row> + <entry><command>figure</command></entry> + <entry><computeroutput>fig-</computeroutput></entry> + </row> + <row> + <entry><command>table</command></entry> + <entry><computeroutput>tb-</computeroutput></entry> + </row> + <row> + <entry><command>appendix</command></entry> + <entry><computeroutput>ap-</computeroutput></entry> + </row> + <row> + <entry><command>part</command></entry> + <entry><computeroutput>pt-</computeroutput></entry> + </row> + <row> + <entry><command>example</command></entry> + <entry><computeroutput>ex-</computeroutput></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-xml-guidelines-header"> + <title>File Header</title> + + <para> + All the files must contain the CVS Id header. + </para> + + <para> + If you create a new file, the first line must be: + </para> +<screen> +<computeroutput> +<!-- $Id: --> +</computeroutput> +</screen> + + <para> + 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: + </para> + +<screen> +<computeroutput> +<!-- $Id: docs-rh-guidelines-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-xml-admon"> + <title>Working with Admonitions</title> + + <indexterm> + <primary>admonitions</primary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>warning</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>tip</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>note</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>caution</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>important</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>warning</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>tip</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>note</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>caution</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>important</tertiary> + </indexterm> + + <para>There are five types of admonitions in DocBook: Caution, Important, + Note, Tip, and Warning.</para> + + <para>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.</para> + + + <sect2 id="s2-xml-notesetc"> + <title>Creating Notes, Tips, Cautions, Importants, and Warnings</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>note</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>tip</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>caution</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>important</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>warning</secondary> + </indexterm> + + <para>There are several ways to bring attention to text within a + document. A <emphasis>Note</emphasis> is used to bring additional + information to the users' attention. A <emphasis>Tip</emphasis> is + used to show the user helpful information or another way to do + something. A <emphasis>Caution</emphasis> is used to show the user + they must be careful when attempting a certain step. An + <emphasis>Important</emphasis> 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 + <emphasis>Warning</emphasis> 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.</para> + + <para>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.</para> + + +<screen> +<computeroutput> +<note> +<title>Note</title> +<para>Body of text goes here.</para> +</note> +</computeroutput> +</screen> + + <note> + <title>Note</title> <para>Body of text goes here.</para> + </note> + + +<screen> +<computeroutput> +<tip> +<title>Tip</title> +<para>Body of text goes here.</para> +</tip> +</computeroutput> +</screen> + + <tip> + <title>Tip</title> + <para>Body of text goes here</para> + </tip> + +<screen> +<computeroutput> +<caution> +<title>Caution</title> +<para>Body of text goes here.</para> +</caution> +</computeroutput> +</screen> + + <caution> + <title>Caution</title> <para>Body of text goes here.</para> + </caution> + + +<screen> +<computeroutput> +<important> +<title>Important</title> +<para>Body of text goes here.</para> +</important> +</computeroutput> +</screen> + + <important> + <title>Important</title> + <para>Body of text goes here.</para> + </important> + +<screen> +<computeroutput> +<warning> +<title>Warning</title> +<para>Body of text goes here.</para> +</warning> +</computeroutput> +</screen> + + <warning> + <title>Warning</title> <para>Body of text goes here.</para> + </warning> + </sect2> + + </sect1> + + </chapter> + + + + 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 @@ + <chapter id="ch-rh-guidelines"> + <title>&RH; Documentation Guidelines</title> + + <indexterm> + <primary>recursion</primary> + <see>recursion</see> + </indexterm> + + <indexterm> + <primary>RTFM</primary> + <secondary>read the f*'ing manual</secondary> + <seealso>humor</seealso> + </indexterm> + + <indexterm> + <primary>humor</primary> + <secondary>RTFM</secondary> + </indexterm> + + <para>Please read this chapter carefully. This chapter describes the + guidelines that must be followed such as naming conventions. + </para> + + <sect1 id="s1-xml-guidelines-naming"> + <title>ID Naming Conventions</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>naming conventions</secondary> + </indexterm> + + <indexterm> + <primary>naming conventions</primary> + </indexterm> + + <para>You will see certain ID names referred to below and this will + help to explain how we come up with those names. For example: + </para> + +<screen> +<computeroutput> +<chapter id="ch-uniquename"> + +<sect3="s3-install-make-disks"> + +<figure id="fig-redhat-config-kickstart-basic"> +</computeroutput> +</screen> + + <para>IDs are unique identifiers, allowing DocBook XML to know where to + cross-reference a section or chapter or the like. + </para> + + <para>The general rules for defining an ID are:</para> + + <indexterm> + <primary>XML tags</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> + + <indexterm> + <primary>naming conventions</primary> + <secondary>rules for defining an ID</secondary> + </indexterm> + + <itemizedlist> + <listitem> + <para>Keep it 32 characters or under (this is counted as + everything between the quotation marks)</para> + </listitem> + <listitem> + <para>Keep it as short and simple as possible</para> + </listitem> + <listitem> + <para>Make sure the name is relevant to the information (make it + recognizable)</para> + </listitem> + </itemizedlist> + + <para>Some examples are <command>"ch-uniquename"</command> (with 13 + characters) and <command>"s3-install-make-disks"</command> (with 21 + characters). + </para> + + <para>A section within a particular chapter always uses the chapter + name (minus the <command>"ch-"</command>) in its ID. For example, you + are working with the <command>"ch-intro"</command> chapter and need to + create your first section on disk partitions. That section ID would look + similar to <command>"s1-intro-partition"</command> which contains the + section number, the main chapter ID, and a unique ID for that section. + </para> + + <table id="tb-xml-namingconventions"> + <title>Naming Conventions</title> + + <tgroup cols="2"> + <colspec colnum="1" colname="tag" colwidth="100"/> + <colspec colnum="2" colname="prefix" colwidth="100"/> + <thead> + <row> + <entry>Tag</entry> + <entry>Prefix</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preface</command></entry> + <entry><computeroutput>pr-</computeroutput></entry> + </row> + <row> + <entry><command>chapter</command></entry> + <entry><computeroutput>ch-</computeroutput></entry> + </row> + <row> + <entry><command>section</command></entry> + <entry><computeroutput>sn-</computeroutput></entry> + </row> + <row> + <entry><command>sect1</command></entry> + <entry><computeroutput>s1-</computeroutput></entry> + </row> + <row> + <entry><command>sect2</command></entry> + <entry><computeroutput>s2-</computeroutput></entry> + </row> + <row> + <entry><command>sect3</command></entry> + <entry><computeroutput>s3-</computeroutput></entry> + </row> + <row> + <entry><command>sect4</command></entry> + <entry><computeroutput>s4-</computeroutput></entry> + </row> + <row> + <entry><command>figure</command></entry> + <entry><computeroutput>fig-</computeroutput></entry> + </row> + <row> + <entry><command>table</command></entry> + <entry><computeroutput>tb-</computeroutput></entry> + </row> + <row> + <entry><command>appendix</command></entry> + <entry><computeroutput>ap-</computeroutput></entry> + </row> + <row> + <entry><command>part</command></entry> + <entry><computeroutput>pt-</computeroutput></entry> + </row> + <row> + <entry><command>example</command></entry> + <entry><computeroutput>ex-</computeroutput></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="s1-xml-guidelines-header"> + <title>File Header</title> + + <para> + All the files must contain the CVS Id header. + </para> + + <para> + If you create a new file, the first line must be: + </para> +<screen> +<computeroutput> +<!-- $Id: --> +</computeroutput> +</screen> + + <para> + 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: + </para> + +<screen> +<computeroutput> +<!-- $Id: docs-rh-guidelines.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-xml-admon"> + <title>Working with Admonitions</title> + + <indexterm> + <primary>admonitions</primary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>warning</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>tip</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>note</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>caution</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>important</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>warning</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>tip</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>note</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>caution</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>admonitions</secondary> + <tertiary>important</tertiary> + </indexterm> + + <para>There are five types of admonitions in DocBook: Caution, Important, + Note, Tip, and Warning.</para> + + <para>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.</para> + + + <sect2 id="s2-xml-notesetc"> + <title>Creating Notes, Tips, Cautions, Importants, and Warnings</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>note</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>tip</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>caution</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>important</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>warning</secondary> + </indexterm> + + <para>There are several ways to bring attention to text within a + document. A <emphasis>Note</emphasis> is used to bring additional + information to the users' attention. A <emphasis>Tip</emphasis> is + used to show the user helpful information or another way to do + something. A <emphasis>Caution</emphasis> is used to show the user + they must be careful when attempting a certain step. An + <emphasis>Important</emphasis> 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 + <emphasis>Warning</emphasis> 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.</para> + + <para>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.</para> + + +<screen> +<computeroutput> +<note> +<title>Note</title> +<para>Body of text goes here.</para> +</note> +</computeroutput> +</screen> + + <note> + <title>Note</title> <para>Body of text goes here.</para> + </note> + + +<screen> +<computeroutput> +<tip> +<title>Tip</title> +<para>Body of text goes here.</para> +</tip> +</computeroutput> +</screen> + + <tip> + <title>Tip</title> + <para>Body of text goes here</para> + </tip> + +<screen> +<computeroutput> +<caution> +<title>Caution</title> +<para>Body of text goes here.</para> +</caution> +</computeroutput> +</screen> + + <caution> + <title>Caution</title> <para>Body of text goes here.</para> + </caution> + + +<screen> +<computeroutput> +<important> +<title>Important</title> +<para>Body of text goes here.</para> +</important> +</computeroutput> +</screen> + + <important> + <title>Important</title> + <para>Body of text goes here.</para> + </important> + +<screen> +<computeroutput> +<warning> +<title>Warning</title> +<para>Body of text goes here.</para> +</warning> +</computeroutput> +</screen> + + <warning> + <title>Warning</title> <para>Body of text goes here.</para> + </warning> + </sect2> + + </sect1> + + </chapter> + + + + 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 @@ +<!-- $Id: docs-tutorial-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-tutorial"> + <title>The Layout of a Tutorial</title> + + <para> + 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. + </para> + + <sect1 id="s1-tutorial-parent"> + <title>The Parent File</title> + + <para> + Below is a sample parent file: + </para> + +<screen> +<computeroutput> +<!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> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-tutorial-license"> + <title>Including the License Information</title> + + <indexterm> + <primary>tutorial layout</primary> + <secondary>license</secondary> + </indexterm> + + <para> + All &PROJECT; manuals <emphasis>must</emphasis> contain the file + <filename>legalnotice.xml</filename>. This file makes the license for + the file the GNU Free Documentation License (FDL). + </para> + + <para> + The sample parent file shows how it is included. + </para> + + </sect1> + + </chapter> + + 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 @@ +<!-- $Id: docs-tutorial.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-tutorial"> + <title>The Layout of a Tutorial</title> + + <para> + 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. + </para> + + <sect1 id="s1-tutorial-parent"> + <title>The Parent File</title> + + <para> + Below is a sample parent file: + </para> + +<screen> +<computeroutput> +<!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> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-tutorial-license"> + <title>Including the License Information</title> + + <indexterm> + <primary>tutorial layout</primary> + <secondary>license</secondary> + </indexterm> + + <para> + All &PROJECT; manuals <emphasis>must</emphasis> contain the file + <filename>legalnotice.xml</filename>. This file makes the license for + the file the GNU Free Documentation License (FDL). + </para> + + <para> + The sample parent file shows how it is included. + </para> + + </sect1> + + </chapter> + + 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 @@ +<!-- $Id: docs-xml-tags-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-xml-tags"> + <title>DocBook XML Tags</title> + + <indexterm> + <primary>XML</primary> + <secondary>tags</secondary> + <see>XML tags</see> + </indexterm> + + <para>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. + </para> + + <para>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). + </para> + + <indexterm> + <primary>XML</primary> + <secondary>general tag information</secondary> + </indexterm> + + <para>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.</para> + + <para>Although XML is capable of handling many document types, the format + discussed here is the article format.</para> + + <para> + This chapter only discusses tags used for documentation for the &PROJECT;, + not all available DocBook XML tags. For the complete list, refer to: + </para> +<screen> +<computeroutput> +<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</ulink> +</computeroutput> +</screen> + + <sect1 id="s1-xml-tags-caveats"> + <title>Tags and Entities Caveats</title> + + <indexterm> + <primary>xml tags</primary> + <secondary>caveats</secondary> + </indexterm> + + <para> + 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. + </para> + + <variablelist> + <varlistentry> + <term>Do Not Use Trademark Entities</term> + <listitem> + <para>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.</para> + <para>Instead, use the <command>trademark</command> tag and its + associates classes as follows: + </para> + <itemizedlist> + <listitem> + <para><trademark>trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="registered">registered trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="copyright">copyright symbol after me</trademark></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags</term> + <listitem> + <para>Do not use <command>para</command> tags around anything other + than a simple paragraph. Doing so will create additional white space + within the text itself in the PDF version. + </para> + <para>Specifically, do not use <command>para</command> tags around + the following (or, to put this another way, do not embed the + following within <command>para</command> tags): + </para> + <itemizedlist> + <listitem> + <para><screen></para> + </listitem> + <listitem> + <para><itemizedlist></para> + </listitem> + <listitem> + <para><orderedlist></para> + </listitem> + <listitem> + <para><variablelist></para> + </listitem> + <listitem> + <para><table></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags within + <command>listitem</command> tags</term> + <listitem> + <para>Content inside <command>para</command> tags within + <command>listitem</command> tags <emphasis>must</emphasis> start + immediately after the beginning <para> tag to avoid extra + white space in the PDF version. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>screen</command> tags</term> + <listitem> + <para>The <command>screen</command> tags (<screen> and + </screen>) <emphasis>must</emphasis> be flush left in the + XML file, and all the content inside the + <command>screen</command> tags must be flush left as well unless + the white space in intentional; otherwise, the extraneous + whitespace will appear in the HTML version. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect1> + + <sect1 id="s1-xml-tags-application"> + <title><command>application</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>application</secondary> + </indexterm> + + <para>An application is the name of a GUI software program. A command is + the name of an executable (text) program or a software command.</para> + + <para>The <command><application></command> and + <command></application></command> tags allow you to refer to an + application or program. For example, the following XML: + </para> + +<screen> +<computeroutput> +To view the Web in Linux, you can use +<application>Mozilla</application> or +<application>lynx</application> if you only want a text-based +browser. +</computeroutput> +</screen> + + <para> + produces the following output: + </para> + + <para> + To view the Web in Linux, you can use <application>Mozilla</application> + or <application>lynx</application> if you only want a text-based browser. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-chapter"> + <title><command>chapter</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>chapter</secondary> + </indexterm> + + <para> + A DocBook book can be divided into chapters such as: + </para> + +<screen> +<computeroutput> +<!--$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> +</computeroutput> +</screen> + + <para> + The chapter can also be further divided into sections + (<command>sect1</command>, <command>sect2</command>, + <command>sect3</command>, etc.). Refer to <xref + linkend="s1-xml-tags-sections"></xref> for details. + </para> + + </sect1> + + + <sect1 id="s1-xml-tags-citetitle"> + <title><command>citetitle</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>citetitle</secondary> + </indexterm> + + + <para> + The <command><citetitle></command> tag provides formatting for a + specific references (title can be manually typed out or if already + defined within your document set, given as an entity<footnote><para>An + 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.</para> + </footnote> + ).</para> + + <para> + For example: + </para> +<screen> +<computeroutput> +<citetitle>IG;</citetitle>. +</computeroutput> +</screen> + <para> + The output looks like <citetitle>&IG;</citetitle> because &IG; is an + entity. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-command"> + <title><command>command</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>command</secondary> + </indexterm> + + <para>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>command</command> tags. </para> + + + <para>If you have text that is a command, use the + <command><command></command> and + <command></command></command> tags such as: + </para> + + + +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + <para> + 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. + </para> + + <para>Another example would be:</para> + +<screen> +<computeroutput> +<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>. +</computeroutput> +</screen> + + <para> + with the output: + </para> + + <para> + <command>MAILNOVIOLATIONS</command> — If set to + <command>true</command> 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 <command>true</command>. + </para> + + <note> + <title>Note</title> <para>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.</para> + </note> + + <para> + Terms marked with <command>command</command> tags because there aren't + exact tags for them: + </para> + <itemizedlist> + <listitem> + <para>Options in configuration files such as Apache directives</para> + </listitem> + <listitem> + <para>daemon names</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="s1-xml-tags-compoutput"> + <title><command>computeroutput</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>computeroutput</secondary> + </indexterm> + + <para> + To show computer output use the following tags: + </para> +<screen> +<computeroutput> +<computeroutput>Do you want to delete this file? y n</computeroutput> +</computeroutput> +</screen> + + <para> + The output: + </para> + <para> + <computeroutput>Do you really want to delete this file? y n</computeroutput> + </para> + </sect1> + + <sect1 id="s1-xml-tags-emphasis"> + <title><command>emphasis</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>emphasis</secondary> + </indexterm> + + <para> + To emphasis content, use the <command><emphasis></command> and + <command></emphasis></command> tags. For example: + </para> +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + 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. + </para> + </sect1> + + <sect1 id="s1-xml-tags-example"> + <title><command>example</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>example</secondary> + </indexterm> + + <para>The <command><example></command> and + <command></example></command> tags are used to format text within a + document and is great for adding emphasis to show examples of code, + exercises, and more. </para> + + <para>The <command><example></command> tag set should be given an ID + and title:</para> + +<screen> + <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> +</screen> + + <para> + The output: + </para> + + <example id="static-ip"> + <title>Static IP Address using DHCP</title> + +<screen> +<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> + + </sect1> + + + <sect1 id="s1-xml-tags-filename"> + <title><command>filename</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>filename</secondary> + </indexterm> + + <para> + The <command><filename></command> and + <command></filename></command> tags define a filename or path to a + file. Since directories are just special files, they are marked with the + <command>filename</command> tags as well. For example: + </para> +<screen> +Edit the <filename>/home/smoore/sam.xml</filename> file to make +changes or add comments. +</screen> + <para> + The output: + </para> + <para> + Edit the <filename>/home/smoore/sam.xml</filename> file to make changes + or add comments. + </para> + + <para> + They are also used to markup an RPM package name. For example: + </para> +<screen> +To use the <application>Keyboard Configuration Tool</application>, the +<command>redhat-config-keyboard</command> RPM package must be installed. +</screen> + <para> + The output: + </para> + <para> + To use the <application>Keyboard Configuration Tool</application>, the + <command>redhat-config-keyboard</command> RPM package must be installed. + </para> + + <note> + <title>Note</title> + <para> + Directory names must end with a forward slash + (<computeroutput>/</computeroutput>) to distinguish them from file + names. + </para> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-firstterm"> + <title><command>firstterm</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>firstterm</secondary> + </indexterm> + + <para> + The <command><firstterm></command> and + <command></firstterm></command> tags helps to define a word that + may be unfamiliar to the user, but that will be seen commonly throughout + the text. For example: + </para> +<screen> +<computeroutput> +Nearly every modern-day operating system uses <firstterm>disk +partitions</firstterm>, and &DISTRO; is no exception. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Nearly every modern-day operating system uses <firstterm>disk + partitions</firstterm>, and &DISTRO; is no exception. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-footnote"> + <title><command>footnote</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>footnote</secondary> + </indexterm> + + <para> + If you need to make a footnote, use the following example: + </para> +<screen> +<computeroutput> +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>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + For those of you who need to perform a server-class <footnote> <para>A + server-class installation sets up a typical server environment. Please note, no + graphical environment is installed during a server-class installation.</para> + </footnote> installation, refer to the + <citetitle>Installation Guide</citetitle>. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-figure"> + <title><command>figure</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>figure</secondary> + </indexterm> + + <important> + <title>Important</title> + <para> + Order matters! The EPS file <emphasis>must</emphasis> be declared + first. + </para> + </important> + + <para> + An example figure declaration: + </para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para> + The following describes what needs to be edited: + </para> + +<screen> +<figure id="fig-ksconfig-basic"> <emphasis>==> id="" would be edited</emphasis> + +<title>Basic Configuration</title> <emphasis>==> title would be edited</emphasis> + +fileref="./figs/ksconfig/ksconfig-basics.eps"> <emphasis>==> .eps location would be edited</emphasis> + +fileref="./figs/ksconfig/ksconfig-basics.png"> <emphasis>==> .png location would be edited</emphasis> + +<para>Some text description of this image</para> <emphasis>==> "Some text..." would be edited</emphasis> +</screen> + </sect1> + + <sect1 id="s1-xml-tags-gui"> + <title>GUI Tags</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + </indexterm> + + <sect2 id="s2-xml-tags-guilabel"> + <title><command>guilabel</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guilabel</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guilabel</secondary> + </indexterm> + + <para> + Use the <command><guilabel></command> and + <command></guilabel></command> tags as a default for GUI + descriptions, like a screen name or screen title. For example: + </para> +<screen> +<computeroutput> +The <guilabel>Authentication Configuration</guilabel> screen +shows you how to make your system more secure. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + The <guilabel>Authentication Configuration</guilabel> screen shows you how to + make your system more secure. + </para> + </sect2> + + <sect2 id="s2-xml-tags-guibutton"> + <title><command>guibutton</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guibutton</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guibutton</secondary> + </indexterm> + + <para> + Use the <command><guibutton></command> and + <command></guibutton></command> tags to denote a button on a screen or + menu. For example: + </para> +<screen> +<computeroutput> +Check the <guibutton>Activate on boot</guibutton> button +to have the X Window System start automatically. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Check the <guibutton>Activate on boot</guibutton> button to have the X + Window System start automatically. + </para> + </sect2> + + <sect2 id="s2-xml-tags-guiicon"> + <title><command>guiicon</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guiicon</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guiicon</secondary> + </indexterm> + + <para> + The <command><guiicon></command> and <command></guiicon></command> + tags are used to denote a panel or desktop icon. For example: + </para> +<screen> +<computeroutput> +Double-click the <guiicon>Start Here</guiicon> icon on the desktop. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Double-click the <guiicon>Start Here</guiicon> icon on the desktop. + </para> + + </sect2> + + <sect2 id="s2-xml-tags-guimenu"> + <title><command>guimenu</command> and + <command>guimenuitem</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guimenu</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guimenu</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guimenuitem</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guimenuitem</secondary> + </indexterm> + + <para> + To note a menu (like in the installation program or within the control panel), + use the <command><guimenu></command> and + <command></guimenu></command> tags. + </para> + + <para> + To note submenu items, use the <command><guimenuitem></command> and + <command></guimenuitem></command> tags. (Please note that there should not + be any breaks between these commands, but for printing purposes breaks have been + inserted). For example: + </para> +<screen> +<computeroutput> +Select +<guimenu>Main Menu</guimenu> => + <guimenuitem>Programming</guimenuitem> => <guimenuitem>Emacs</guimenuitem> to start the +<application>Emacs</application> text editor. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + From the control panel, click on <guimenu>Main Menu</guimenu> => + <guimenuitem>Programming</guimenuitem> => + <guimenuitem>Emacs</guimenuitem> to start the + <application>Emacs</application> text editor. + </para> + </sect2> + </sect1> + + <sect1 id="s1-xml-tags-keycap"> + <title><command>keycap</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>keycap</secondary> + </indexterm> + + <para> + To denote a specific key, you will need to use the + <command><keycap></command> and <command></keycap></command> + tags. Brackets are automatically added around the keycap, so do not add + them in your XML code. For example: + </para> +<screen> +<computeroutput> +To make your selection, press the <keycap>Enter</keycap> key. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + To make your selection, press the <keycap>Enter</keycap> key. + </para> + + <sect2 id="s2-xml-tags-menuchoice"> + <title><command>menuchoice</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>menuchoice</secondary> + </indexterm> + + <para> + 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: + </para> + +<screen> +<computeroutput> +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>. +</computeroutput> +</screen> + + + <para> + The output: + </para> + + <para> + 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>. + </para> + + </sect2> + + <sect2 id="s2-xml-tags-keycombo"> + <title><command>keycombo</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>keycombo</secondary> + </indexterm> + + <para> + To illustrate a key combination, you need to use the + <command><keycombo></command> and + <command></keycombo></command>, + <command><keycap></command> and + <command></keycap></command> tags. For example: + </para> +<screen> +<computeroutput> +To reboot your system, press <keycombo> +<keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> +</keycombo>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + To reboot your system, press + <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> + </keycombo>. + </para> + + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-lists"> + <title>Lists</title> + + <indexterm> + <primary>lists</primary> + <secondary>creating</secondary> + </indexterm> + + <para>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).</para> + + <para>There is also a list format for tables and for for creating a + list of glossary terms and their definitions.</para> + + <para>The sections below will discuss the proper uses for the various + list and how to create them.</para> + + <sect2 id="s2-xml-tags-itemizedlist"> + <title><command>itemizedlist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>itemizedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>itemizedlist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>itemizedlist</command></secondary> + </indexterm> + + <para>An <command>ItemizedList</command> 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 + <command>VariableList</command> and presents the information in a + very simple way.</para> + + <para>To create an <command>ItemizedList</command> (otherwise known as + bulleted list), use the following command sequence:</para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> + 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + </sect2> + + <sect2 id="s2-xml-tags-orderedlist"> + <title><command>OrderedList</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>orderedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>orderedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>orderedlist</tertiary> + </indexterm> + + <para>An <command>orderedlist</command> is best used to present + information that is important for the reader to know in a specific + order. <command>orderedlist</command>s are a good way to convey + step-by-step senarios to the audience you are writing for.</para> + + <para> + To create an <command>orderedlist</command> (numbered list), use the + following XML code sequence: + </para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> + 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <orderedlist> + <listitem> + <para>Online — http://www.redhat.com/support/errata; supplies errata + you can read online, and you can download diskette images + easily. + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + </orderedlist> + + </sect2> + + <sect2 id="s2-xml-tags-varlist"> + <title><command>Variablelist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>variablelist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>variablelist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>variablelist</command></secondary> + </indexterm> + + <para>A <command>variablelist</command> best represents a list of + terms and definitions or descriptions for those terms.</para> + + <para>To create a <command>variablelist</command>, use the following + command sequence: + </para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + <warning> + <title>Warning</title> + <para> + Do <emphasis>not</emphasis> specify the + <computeroutput>frame</computeroutput> attribute to the table. Doing + so breaks PDF production. + </para> + </warning> + + </sect2> + + <sect2 id="s2-xml-tags-simplelist"> + <title>Creating a List Within a Table Using <command>Simplelist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>simplelist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>simplelist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>simplelist</command></secondary> + </indexterm> + + <indexterm> + <primary>tables</primary> + <secondary>creating a list within a table</secondary> + <tertiary><command>simplelist</command></tertiary> + </indexterm> + + <para>A <command>simplelist</command> is an unadorned list of + items. <command>simplelist</command>s can be inline or arranged in + columns.</para> + + <para>We use <command>simplelist</command> to add separate paragraphs + of text within a table element. A regular list, such as + <command>itemizedlist</command>, cannot be embedded within a table.</para> + + <para>The XML commands for a table look like:</para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + <note> + <title>Note</title> + <para>Notice how the <command>SimpleList</command> tags are + used. The <entry> and <simplelist> tags must be aligned + beside one another, otherwise you will receive a parsing error.</para> + </note> + + <para>For each paragraph or list item to be added within a + <command>SimpleList</command>, the <member> tag set must be + added around that particular text item.</para> + </sect2> + + <sect2 id="s2-xml-tags-glossary"> + <title><command>glosslist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>glosslist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>glosslist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>glosslist</command></secondary> + </indexterm> + + <para>Use the <command>glosslist</command> command set to create a + list of glossary terms and their definitions.</para> + + + <para>In XML, an example looks like the following:</para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para> + The output looks like: + </para> + + <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> + + </sect2> + </sect1> + + + <sect1 id="s1-xml-tags-option"> + <title><command>option</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>option</secondary> + </indexterm> + + <para>If you have a command that offers an option or a flag, use the + <command><option></command> and + <command></option></command> tags. + </para> + + <note> + <title>Note</title> + <para>The <option> tag set is only meant to be used for command + line options, not options in configuration files.</para> + </note> + + <para>In XML, specifying an option would look like the + following:</para> + +<screen> +<computeroutput> +For example, with the command <command>ls</command> you can +specify an option such as <option>-la</option>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para>For example, with the command <command>ls</command> you can + specify an option such as <option>-la</option>.</para> + + </sect1> + + <sect1 id="s1-xml-tags-indexing"> + <title>Index Entries</title> + + <indexterm> + <primary>indexing</primary> + </indexterm> + + + <indexterm> + <primary>XML tags</primary> + <secondary>indexing</secondary> + </indexterm> + + <para>The following command sequence shows you the code inserted into + the body of the text to add an index entry to your document: + </para> + +<screen> +<computeroutput> +<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 +</computeroutput> +</screen> + + <indexterm> + <primary>foo</primary> + <secondary>bar</secondary> + </indexterm> + + + <para>The <command><seealso></command> tag allows you to + reference another index entry or refer to another manual. Make sure + the <command><seealso></command> reference you are pointing to + has its own entry. For example: + </para> + + <indexterm> + <primary>indexing</primary> + <secondary>seealso tag</secondary> + </indexterm> + +<screen> +<computeroutput> +<indexterm> +<primary>SWAK</primary> +<seealso>salutations</seealso> +</indexterm> + + +<indexterm> +<primary>salutations</primary> +</indexterm> +</computeroutput> +</screen> + + <indexterm> + <primary>SWAK</primary> + <seealso>Salutations</seealso> + </indexterm> + + <indexterm> + <primary>Salutations</primary> + </indexterm> + + <para> + The <command><see></command> tag allows you to reference to + another index entry entirely. For example: + </para> + <indexterm> + <primary>indexing</primary> + <secondary>see tag</secondary> + </indexterm> + + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <indexterm> + <primary>Guinness</primary> + <see>Beer</see> + </indexterm> + + <indexterm> + <primary>Beer</primary> + </indexterm> + + <para>To view the HTML output of the index entries shown here, refer + to the <filename>generated-index.html</filename> file at the end of + this document.</para> + +<!-- + <tip> + <title>Tip</title> + <para> + To learn more about the rules of indexing, refer to <xref + linkend="ch-indexing"></xref>. + </para> + </tip> +--> + </sect1> + + <sect1 id="s1-xml-tags-para"> + <title><command>para</command></title> + + + <indexterm> + <primary>XML tags</primary> + <secondary>para</secondary> + </indexterm> + + <para>For any paragraph, the <command><para></command> and + <command></para></command> tags must open and close that + particular paragraph. + </para> + + <sect2 id="s2-xml-tags-para"> + <title>Additional Rules for the <command><para></command> Tag + Set</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>para</secondary> + <tertiary>additional rules</tertiary> + </indexterm> + + <variablelist> + <varlistentry> + <term>Proper formatting of <command><para></command> tag and + text</term> + <listitem> + <para>Additionally, the <command><para></command> tags + should be justified around the paragraph so that the opening + <command><para></command> tag and the first word of that + paragraph are side by side. For example:</para> + +<screen> +<computeroutput> +<command><para></command>This paragraph talk about using the <para> +tag correctly.<command><para></command> +</computeroutput> +</screen> + + </listitem> + </varlistentry> + + <varlistentry> + <term>Where not to use <command><para></command> tags</term> + <listitem> + <para>Do not use para tags around anything other than a simple + paragraph. Doing so will create additional white space within + the text itself.</para> + + <para>Do not use <command><para></command> tags around the + following (or, to put this another way, do not embed the + following within <command><para></command> tags):</para> + + <itemizedlist> + <listitem> + <para><command><screen></command></para> + </listitem> + <listitem> + <para><command><itemizedlist></command></para> + </listitem> + <listitem> + <para><command><orderedlist></command></para> + </listitem> + <listitem> + <para><command><variablelist></command></para> + </listitem> + <listitem> + <para><command><table></command></para> + </listitem> + </itemizedlist> + + </listitem> + </varlistentry> + </variablelist> + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-part"> + <title><command>part</command></title> + + <indexterm> + <primary>parts</primary> + </indexterm> + + + <indexterm> + <primary>XML tags</primary> + <secondary>part</secondary> + </indexterm> + + <para> + In the parent file, you can separate the chapters into parts to divide + them into logical groups. For example, in the parent file, the + <command>part</command> tags surround the chapter entities: + </para> +<screen> +<computeroutput> +<part id="pt-foo"> + <partintro> + <para>Some text for the part intro</para> + &CHAPTER; + + &ANOTHER-CHAPTER; +</part> +</computeroutput> +</screen> + + <para> + If you create a part, include a part introduction describing the + contents of the part. For example: + </para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para> + 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. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-prompt"> + <title><command>prompt</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>prompt</secondary> + </indexterm> + + <para> + To show a prompt, such as a root or DOS prompt, use the + <command><prompt></command> and <command></prompt></command> + commands. For example: + </para> +<screen> +<computeroutput> +At the <prompt>LILO:</prompt> boot prompt, type linux to +boot into your Linux partition. + +At the <prompt>C:\></prompt> prompt, type .... +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + At the <prompt>LILO:</prompt> boot prompt, type linux to boot into your + Linux partition. + </para> + <para> + At the <prompt>C:\></prompt> prompt, type .... + </para> + + <note> + <title>Note</title> + <para> + When showing example computer output (usually in + <command>screen</command> tags), do you include the prompt or command + (unless the command or prompt is the actually computer output you want + to show).</para> + </note> + </sect1> + + <sect1 id="s1-xml-tags-replaceable"> + <title><command>replaceable</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>replaceable</secondary> + </indexterm> + + <para> + To create replaceable text, you use the tags + <command><replaceable></command> and + <command></replaceable></command> around the text you want to use as a + variable. + </para> + <para> + This example shows the ISBN of our boxed sets with variables: + </para> +<screen> +<computeroutput> +1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + 1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> + </para> + </sect1> + + <sect1 id="s1-xml-tags-screen"> + <title><command>screen</command></title> + <indexterm> + <primary>XML tags</primary> + <secondary>screen</secondary> + </indexterm> + + <para> + The <command><screen></command> 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 + <command><screen></command> and closing + <command></screen></command> tags around the text you are + emphasizing. + </para> + + <important> + <title>Important</title> <para>When using the + <command><screen></command> tag, you must set everything within + that screen, including the <command><screen></command> 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.</para> + </important> + + + <para> + An example of <command><screen></command> is the following: + </para> +<screen> +<computeroutput> +<screen> +<computeroutput> +This is an example of a screen. You do not need <para> tags +within this command. +</computeroutput> +</screen> +</computeroutput> +</screen> + + <para> + The output: + </para> + +<screen> +<computeroutput> +This is an example of a screen. You do not need <command><para></command> +tags within this command. +</computeroutput> +</screen> + + <note> + <title>Note</title> <para>To properly use the + <command><screen></command> 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 + <command><computeroutput></command> tag set. If it is a command, + it needs the <command><command></command> tag set. If it is a + command with user input, it may require a construction like the one + below:</para> +<screen> +<command><command></command>command <command><userinput></command>input<command></userinput></command><command></command></command> +</screen> + + <para> + The output looks like: + </para> + +<screen> +<command>command <userinput>input</userinput></command> +</screen> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-sections"> + <title>Sections</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>sections</secondary> + </indexterm> + + <indexterm> + <primary>sections</primary> + </indexterm> + + <para>Within an article (or chapter if it is a DocBook XML book like the + <citetitle>&IG;</citetitle>), you can have sections and + subsections. <command><sect1></command> 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:</para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para> + If you only need one level of sections in a DocBook article, you can use + the <command>section</command> tag. For example: + </para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + </sect1> + + <sect1 id="s1-xml-tags-table"> + <title><command>table</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>table</secondary> + </indexterm> + + <para> + The following is an example of creating a table. + </para> + +<screen> +<table id="tb-mockup-before-begin"> + <emphasis>This tells XML that you will be creating a table + and the ID name is <command>"tb-mockup-before-begin."</command></emphasis> + +<title>Available Features of GNOME and KDE</title> + +<tgroup cols="3"> + <emphasis>This tells XML that you are creating a table + with three columns.</emphasis> + +<colspec colnum="1" colname="Features" colwidth="3"/> + <emphasis><command>colspec</command> says that you are giving information + about the column to XML</emphasis> <emphasis><command>colnum="1"</command> + says that you are giving specifications for the first column.</emphasis> + + <emphasis><command>colname="Features"</command> says that the title for this + column will be "Features."</emphasis> + + <emphasis><command>colwidth="3"</command> 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.</emphasis> + +<colspec colnum="2" colname="GNOME" colwidth="2"/> +<colspec colnum="3" colname="KDE" colwidth="2"/> + +<thead> + <emphasis>Contains one or more table row elements.</emphasis> + +<row> + <emphasis>Contains one or more table cell (entry) elements.</emphasis> + +<entry>Features</entry> + <emphasis>Table cell element, one of several in a row element, defining + columns within the row.</emphasis> + +<entry>GNOME</entry> +<entry>KDE</entry> +</row> +</thead> + +<tbody> + <emphasis>Contains one or more row elements, for the main text + of the table.</emphasis> + +<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> +</screen> + + <table id="tb-mockup-before-begin"> + <title>Available Features of GNOME and KDE</title> + + <tgroup cols="3"> + <colspec colnum="1" colname="Features" colwidth="3"/> + <colspec colnum="2" colname="GNOME" colwidth="2"/> + <colspec colnum="3" colname="KDE" colwidth="2"/> + + <thead> + <row> + <entry>Features </entry> + <entry>GNOME</entry> + <entry>KDE</entry> + </row> + </thead> + + <tbody> + <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> + + <sect2 id="s2-xml-tags-listintable"> + <title>Creating a List Within a Table</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>table</secondary> + <tertiary>list within a table</tertiary> + </indexterm> + + + <para>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 + <application>Emacs</application>.</para> + + <para>The tags you will need to use are + <command><simplelist></command> and + <command><member></command>.</para> + + <para>The following example will show you the proper formatting for + creating a list within a table.</para> + + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>Notice how the <command><simplelist></command> tag must be + beside the <command><entry></command> tag? If you do not format + this properly, it will not parse cleanly.</para> + + <para>The above example will look like the following:</para> + + <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> + + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-trademark"> + <title><command>trademark</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>trademark</command></secondary> + </indexterm> + + + <para>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.</para> + + <para>Instead, use the <command>trademark</command> tag and its + associates classes as follows: + </para> + +<screen> +<computeroutput> +<trademark>trademark symbol after me</trademark> +<trademark class="registered">registered trademark symbol after me</trademark> +<trademark class="copyright">copyright symbol after me</trademark> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-xml-tags-userinput"> + <title><command>userinput</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>userinput</command></secondary> + </indexterm> + + <para> + To show what a user would type, use the <command>userinput</command> + tag. For example: + </para> +<screen> +<computeroutput> +At the prompt, type: + +<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + At the prompt, type: + </para> + + <para> + <userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> + </para> + </sect1> + + +<!-- <sect1 id="s1-xml-tags-mouse"> + <title><command>mousebutton</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>mousebutton</secondary> + </indexterm> + <para> +Describe mouse actions with the mousebutton tag. Below is an example of its use. +</para> + +<screen> +<mousebutton>Right click</mousebutton> on the image and a new menu will appear. +</screen> + + <para> +<mousebutton>Right click</mousebutton> on the image and a new menu will appear. + </para> + + </sect1> --> + + <sect1 id="s1-xml-tag-sulink"> + <title><command>ulink</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>ulink</secondary> + </indexterm> + + <para> + To create a URL link within your text, use the following example: + </para> +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Online — <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. + </para> + + <note> + <title>Note</title> + <para> + If the URL does not end in a filename, it must end in a slash + (<computeroutput>/</computeroutput>) to be a properly formed URL. For + example, <ulink + url="http://www.redhat.com/">http://www.redhat.com/</ulink>. + </para> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-wordasword"> + <title><command>wordasword</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>wordasword</secondary> + </indexterm> + + <para>The <wordasword> tag set is used to define a word meant + specifically as a word and not representing anything else.</para> + + <para>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.</para> + + <para>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.</para> + + <para>For example:</para> + +<screen> +<computeroutput>To use <command>grep</command> to search for the word +<wordasword>linux</wordasword>, use the command +<command>grep linux</command>.</computeroutput> +</screen> + + <para> + The output: + </para> + + <para>To use <command>grep</command> to search for the word + <wordasword>linux</wordasword>, use the command <command>grep + linux</command>.</para> + + <para>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.</para> + + </sect1> + + + <sect1 id="s1-xml-tags-xref"> + <title><command>xref</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>xref</secondary> + </indexterm> + + <para> + To refer to other sections or chapters within a manual, use the + <command><xref></command> tag. + </para> + + <para> + The output of this displays the title of the section or chapter you are + pointing the user to. For example: + </para> +<screen> +<computeroutput> +For more information about the parent file, refer to +<xref linkend="ch-tutorial"><xref> and <xref linkend="s1-tutorial-parent"></xref> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + For more information about the parent file, refer to <xref linkend="ch-tutorial"></xref> + and <xref linkend="s1-tutorial-parent"></xref>. + </para> + </sect1> + + </chapter> 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 @@ +<!-- $Id: docs-xml-tags.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + + <chapter id="ch-xml-tags"> + <title>DocBook XML Tags</title> + + <indexterm> + <primary>XML</primary> + <secondary>tags</secondary> + <see>XML tags</see> + </indexterm> + + <para>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. + </para> + + <para>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). + </para> + + <indexterm> + <primary>XML</primary> + <secondary>general tag information</secondary> + </indexterm> + + <para>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.</para> + + <para>Although XML is capable of handling many document types, the format + discussed here is the article format.</para> + + <para> + This chapter only discusses tags used for documentation for the &PROJECT;, + not all available DocBook XML tags. For the complete list, refer to: + </para> +<screen> +<computeroutput> +<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">http://www.docbook.org/tdg/en/html/docbook.html</ulink> +</computeroutput> +</screen> + + <sect1 id="s1-xml-tags-caveats"> + <title>Tags and Entities Caveats</title> + + <indexterm> + <primary>xml tags</primary> + <secondary>caveats</secondary> + </indexterm> + + <para> + 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. + </para> + + <variablelist> + <varlistentry> + <term>Do Not Use Trademark Entities</term> + <listitem> + <para>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.</para> + <para>Instead, use the <command>trademark</command> tag and its + associates classes as follows: + </para> + <itemizedlist> + <listitem> + <para><trademark>trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="registered">registered trademark symbol after me</trademark> + </para> + </listitem> + <listitem> + <para><trademark class="copyright">copyright symbol after me</trademark></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags</term> + <listitem> + <para>Do not use <command>para</command> tags around anything other + than a simple paragraph. Doing so will create additional white space + within the text itself in the PDF version. + </para> + <para>Specifically, do not use <command>para</command> tags around + the following (or, to put this another way, do not embed the + following within <command>para</command> tags): + </para> + <itemizedlist> + <listitem> + <para><screen></para> + </listitem> + <listitem> + <para><itemizedlist></para> + </listitem> + <listitem> + <para><orderedlist></para> + </listitem> + <listitem> + <para><variablelist></para> + </listitem> + <listitem> + <para><table></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>para</command> tags within + <command>listitem</command> tags</term> + <listitem> + <para>Content inside <command>para</command> tags within + <command>listitem</command> tags <emphasis>must</emphasis> start + immediately after the beginning <para> tag to avoid extra + white space in the PDF version. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Content inside <command>screen</command> tags</term> + <listitem> + <para>The <command>screen</command> tags (<screen> and + </screen>) <emphasis>must</emphasis> be flush left in the + XML file, and all the content inside the + <command>screen</command> tags must be flush left as well unless + the white space in intentional; otherwise, the extraneous + whitespace will appear in the HTML version. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect1> + + <sect1 id="s1-xml-tags-application"> + <title><command>application</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>application</secondary> + </indexterm> + + <para>An application is the name of a GUI software program. A command is + the name of an executable (text) program or a software command.</para> + + <para>The <command><application></command> and + <command></application></command> tags allow you to refer to an + application or program. For example, the following XML: + </para> + +<screen> +<computeroutput> +To view the Web in Linux, you can use +<application>Mozilla</application> or +<application>lynx</application> if you only want a text-based +browser. +</computeroutput> +</screen> + + <para> + produces the following output: + </para> + + <para> + To view the Web in Linux, you can use <application>Mozilla</application> + or <application>lynx</application> if you only want a text-based browser. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-chapter"> + <title><command>chapter</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>chapter</secondary> + </indexterm> + + <para> + A DocBook book can be divided into chapters such as: + </para> + +<screen> +<computeroutput> +<!--$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> +</computeroutput> +</screen> + + <para> + The chapter can also be further divided into sections + (<command>sect1</command>, <command>sect2</command>, + <command>sect3</command>, etc.). Refer to <xref + linkend="s1-xml-tags-sections"></xref> for details. + </para> + + </sect1> + + + <sect1 id="s1-xml-tags-citetitle"> + <title><command>citetitle</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>citetitle</secondary> + </indexterm> + + + <para> + The <command><citetitle></command> tag provides formatting for a + specific references (title can be manually typed out or if already + defined within your document set, given as an entity<footnote><para>An + 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.</para> + </footnote> + ).</para> + + <para> + For example: + </para> +<screen> +<computeroutput> +<citetitle>IG;</citetitle>. +</computeroutput> +</screen> + <para> + The output looks like <citetitle>&IG;</citetitle> because &IG; is an + entity. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-command"> + <title><command>command</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>command</secondary> + </indexterm> + + <para>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>command</command> tags. </para> + + + <para>If you have text that is a command, use the + <command><command></command> and + <command></command></command> tags such as: + </para> + + + +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + <para> + 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. + </para> + + <para>Another example would be:</para> + +<screen> +<computeroutput> +<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>. +</computeroutput> +</screen> + + <para> + with the output: + </para> + + <para> + <command>MAILNOVIOLATIONS</command> — If set to + <command>true</command> 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 <command>true</command>. + </para> + + <note> + <title>Note</title> <para>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.</para> + </note> + + <para> + Terms marked with <command>command</command> tags because there aren't + exact tags for them: + </para> + <itemizedlist> + <listitem> + <para>Options in configuration files such as Apache directives</para> + </listitem> + <listitem> + <para>daemon names</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="s1-xml-tags-compoutput"> + <title><command>computeroutput</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>computeroutput</secondary> + </indexterm> + + <para> + To show computer output use the following tags: + </para> +<screen> +<computeroutput> +<computeroutput>Do you want to delete this file? y n</computeroutput> +</computeroutput> +</screen> + + <para> + The output: + </para> + <para> + <computeroutput>Do you really want to delete this file? y n</computeroutput> + </para> + </sect1> + + <sect1 id="s1-xml-tags-emphasis"> + <title><command>emphasis</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>emphasis</secondary> + </indexterm> + + <para> + To emphasis content, use the <command><emphasis></command> and + <command></emphasis></command> tags. For example: + </para> +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + 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. + </para> + </sect1> + + <sect1 id="s1-xml-tags-example"> + <title><command>example</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>example</secondary> + </indexterm> + + <para>The <command><example></command> and + <command></example></command> tags are used to format text within a + document and is great for adding emphasis to show examples of code, + exercises, and more. </para> + + <para>The <command><example></command> tag set should be given an ID + and title:</para> + +<screen> + <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> +</screen> + + <para> + The output: + </para> + + <example id="static-ip"> + <title>Static IP Address using DHCP</title> + +<screen> +<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> + + </sect1> + + + <sect1 id="s1-xml-tags-filename"> + <title><command>filename</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>filename</secondary> + </indexterm> + + <para> + The <command><filename></command> and + <command></filename></command> tags define a filename or path to a + file. Since directories are just special files, they are marked with the + <command>filename</command> tags as well. For example: + </para> +<screen> +Edit the <filename>/home/smoore/sam.xml</filename> file to make +changes or add comments. +</screen> + <para> + The output: + </para> + <para> + Edit the <filename>/home/smoore/sam.xml</filename> file to make changes + or add comments. + </para> + + <para> + They are also used to markup an RPM package name. For example: + </para> +<screen> +To use the <application>Keyboard Configuration Tool</application>, the +<command>redhat-config-keyboard</command> RPM package must be installed. +</screen> + <para> + The output: + </para> + <para> + To use the <application>Keyboard Configuration Tool</application>, the + <command>redhat-config-keyboard</command> RPM package must be installed. + </para> + + <note> + <title>Note</title> + <para> + Directory names must end with a forward slash + (<computeroutput>/</computeroutput>) to distinguish them from file + names. + </para> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-firstterm"> + <title><command>firstterm</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>firstterm</secondary> + </indexterm> + + <para> + The <command><firstterm></command> and + <command></firstterm></command> tags helps to define a word that + may be unfamiliar to the user, but that will be seen commonly throughout + the text. For example: + </para> +<screen> +<computeroutput> +Nearly every modern-day operating system uses <firstterm>disk +partitions</firstterm>, and &DISTRO; is no exception. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Nearly every modern-day operating system uses <firstterm>disk + partitions</firstterm>, and &DISTRO; is no exception. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-footnote"> + <title><command>footnote</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>footnote</secondary> + </indexterm> + + <para> + If you need to make a footnote, use the following example: + </para> +<screen> +<computeroutput> +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>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + For those of you who need to perform a server-class <footnote> <para>A + server-class installation sets up a typical server environment. Please note, no + graphical environment is installed during a server-class installation.</para> + </footnote> installation, refer to the + <citetitle>Installation Guide</citetitle>. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-figure"> + <title><command>figure</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>figure</secondary> + </indexterm> + + <important> + <title>Important</title> + <para> + Order matters! The EPS file <emphasis>must</emphasis> be declared + first. + </para> + </important> + + <para> + An example figure declaration: + </para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para> + The following describes what needs to be edited: + </para> + +<screen> +<figure id="fig-ksconfig-basic"> <emphasis>==> id="" would be edited</emphasis> + +<title>Basic Configuration</title> <emphasis>==> title would be edited</emphasis> + +fileref="./figs/ksconfig/ksconfig-basics.eps"> <emphasis>==> .eps location would be edited</emphasis> + +fileref="./figs/ksconfig/ksconfig-basics.png"> <emphasis>==> .png location would be edited</emphasis> + +<para>Some text description of this image</para> <emphasis>==> "Some text..." would be edited</emphasis> +</screen> + </sect1> + + <sect1 id="s1-xml-tags-gui"> + <title>GUI Tags</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + </indexterm> + + <sect2 id="s2-xml-tags-guilabel"> + <title><command>guilabel</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guilabel</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guilabel</secondary> + </indexterm> + + <para> + Use the <command><guilabel></command> and + <command></guilabel></command> tags as a default for GUI + descriptions, like a screen name or screen title. For example: + </para> +<screen> +<computeroutput> +The <guilabel>Authentication Configuration</guilabel> screen +shows you how to make your system more secure. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + The <guilabel>Authentication Configuration</guilabel> screen shows you how to + make your system more secure. + </para> + </sect2> + + <sect2 id="s2-xml-tags-guibutton"> + <title><command>guibutton</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guibutton</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guibutton</secondary> + </indexterm> + + <para> + Use the <command><guibutton></command> and + <command></guibutton></command> tags to denote a button on a screen or + menu. For example: + </para> +<screen> +<computeroutput> +Check the <guibutton>Activate on boot</guibutton> button +to have the X Window System start automatically. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Check the <guibutton>Activate on boot</guibutton> button to have the X + Window System start automatically. + </para> + </sect2> + + <sect2 id="s2-xml-tags-guiicon"> + <title><command>guiicon</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guiicon</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guiicon</secondary> + </indexterm> + + <para> + The <command><guiicon></command> and <command></guiicon></command> + tags are used to denote a panel or desktop icon. For example: + </para> +<screen> +<computeroutput> +Double-click the <guiicon>Start Here</guiicon> icon on the desktop. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Double-click the <guiicon>Start Here</guiicon> icon on the desktop. + </para> + + </sect2> + + <sect2 id="s2-xml-tags-guimenu"> + <title><command>guimenu</command> and + <command>guimenuitem</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guimenu</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guimenu</secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>GUI tags</secondary> + <tertiary>guimenuitem</tertiary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>guimenuitem</secondary> + </indexterm> + + <para> + To note a menu (like in the installation program or within the control panel), + use the <command><guimenu></command> and + <command></guimenu></command> tags. + </para> + + <para> + To note submenu items, use the <command><guimenuitem></command> and + <command></guimenuitem></command> tags. (Please note that there should not + be any breaks between these commands, but for printing purposes breaks have been + inserted). For example: + </para> +<screen> +<computeroutput> +Select +<guimenu>Main Menu</guimenu> => + <guimenuitem>Programming</guimenuitem> => <guimenuitem>Emacs</guimenuitem> to start the +<application>Emacs</application> text editor. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + From the control panel, click on <guimenu>Main Menu</guimenu> => + <guimenuitem>Programming</guimenuitem> => + <guimenuitem>Emacs</guimenuitem> to start the + <application>Emacs</application> text editor. + </para> + </sect2> + </sect1> + + <sect1 id="s1-xml-tags-keycap"> + <title><command>keycap</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>keycap</secondary> + </indexterm> + + <para> + To denote a specific key, you will need to use the + <command><keycap></command> and <command></keycap></command> + tags. Brackets are automatically added around the keycap, so do not add + them in your XML code. For example: + </para> +<screen> +<computeroutput> +To make your selection, press the <keycap>Enter</keycap> key. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + To make your selection, press the <keycap>Enter</keycap> key. + </para> + + <sect2 id="s2-xml-tags-menuchoice"> + <title><command>menuchoice</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>menuchoice</secondary> + </indexterm> + + <para> + 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: + </para> + +<screen> +<computeroutput> +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>. +</computeroutput> +</screen> + + + <para> + The output: + </para> + + <para> + 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>. + </para> + + </sect2> + + <sect2 id="s2-xml-tags-keycombo"> + <title><command>keycombo</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>keycombo</secondary> + </indexterm> + + <para> + To illustrate a key combination, you need to use the + <command><keycombo></command> and + <command></keycombo></command>, + <command><keycap></command> and + <command></keycap></command> tags. For example: + </para> +<screen> +<computeroutput> +To reboot your system, press <keycombo> +<keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> +</keycombo>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + To reboot your system, press + <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> + </keycombo>. + </para> + + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-lists"> + <title>Lists</title> + + <indexterm> + <primary>lists</primary> + <secondary>creating</secondary> + </indexterm> + + <para>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).</para> + + <para>There is also a list format for tables and for for creating a + list of glossary terms and their definitions.</para> + + <para>The sections below will discuss the proper uses for the various + list and how to create them.</para> + + <sect2 id="s2-xml-tags-itemizedlist"> + <title><command>itemizedlist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>itemizedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>itemizedlist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>itemizedlist</command></secondary> + </indexterm> + + <para>An <command>ItemizedList</command> 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 + <command>VariableList</command> and presents the information in a + very simple way.</para> + + <para>To create an <command>ItemizedList</command> (otherwise known as + bulleted list), use the following command sequence:</para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> + 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + </sect2> + + <sect2 id="s2-xml-tags-orderedlist"> + <title><command>OrderedList</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>orderedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>orderedlist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>orderedlist</tertiary> + </indexterm> + + <para>An <command>orderedlist</command> is best used to present + information that is important for the reader to know in a specific + order. <command>orderedlist</command>s are a good way to convey + step-by-step senarios to the audience you are writing for.</para> + + <para> + To create an <command>orderedlist</command> (numbered list), use the + following XML code sequence: + </para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> + 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <orderedlist> + <listitem> + <para>Online — http://www.redhat.com/support/errata; supplies errata + you can read online, and you can download diskette images + easily. + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + </orderedlist> + + </sect2> + + <sect2 id="s2-xml-tags-varlist"> + <title><command>Variablelist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>variablelist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>variablelist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>variablelist</command></secondary> + </indexterm> + + <para>A <command>variablelist</command> best represents a list of + terms and definitions or descriptions for those terms.</para> + + <para>To create a <command>variablelist</command>, use the following + command sequence: + </para> + + <note> + <title>Note</title> <para>Notice below that the text for the list + item is directly surrounded by the <command>para</command> 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.</para> + </note> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + <warning> + <title>Warning</title> + <para> + Do <emphasis>not</emphasis> specify the + <computeroutput>frame</computeroutput> attribute to the table. Doing + so breaks PDF production. + </para> + </warning> + + </sect2> + + <sect2 id="s2-xml-tags-simplelist"> + <title>Creating a List Within a Table Using <command>Simplelist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>simplelist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>simplelist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>simplelist</command></secondary> + </indexterm> + + <indexterm> + <primary>tables</primary> + <secondary>creating a list within a table</secondary> + <tertiary><command>simplelist</command></tertiary> + </indexterm> + + <para>A <command>simplelist</command> is an unadorned list of + items. <command>simplelist</command>s can be inline or arranged in + columns.</para> + + <para>We use <command>simplelist</command> to add separate paragraphs + of text within a table element. A regular list, such as + <command>itemizedlist</command>, cannot be embedded within a table.</para> + + <para>The XML commands for a table look like:</para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para>The output looks like:</para> + + <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> + + <note> + <title>Note</title> + <para>Notice how the <command>SimpleList</command> tags are + used. The <entry> and <simplelist> tags must be aligned + beside one another, otherwise you will receive a parsing error.</para> + </note> + + <para>For each paragraph or list item to be added within a + <command>SimpleList</command>, the <member> tag set must be + added around that particular text item.</para> + </sect2> + + <sect2 id="s2-xml-tags-glossary"> + <title><command>glosslist</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>glosslist</command></secondary> + </indexterm> + + <indexterm> + <primary>XML tags</primary> + <secondary>lists</secondary> + <tertiary>glosslist</tertiary> + </indexterm> + + <indexterm> + <primary>lists</primary> + <secondary><command>glosslist</command></secondary> + </indexterm> + + <para>Use the <command>glosslist</command> command set to create a + list of glossary terms and their definitions.</para> + + + <para>In XML, an example looks like the following:</para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para> + The output looks like: + </para> + + <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> + + </sect2> + </sect1> + + + <sect1 id="s1-xml-tags-option"> + <title><command>option</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>option</secondary> + </indexterm> + + <para>If you have a command that offers an option or a flag, use the + <command><option></command> and + <command></option></command> tags. + </para> + + <note> + <title>Note</title> + <para>The <option> tag set is only meant to be used for command + line options, not options in configuration files.</para> + </note> + + <para>In XML, specifying an option would look like the + following:</para> + +<screen> +<computeroutput> +For example, with the command <command>ls</command> you can +specify an option such as <option>-la</option>. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para>For example, with the command <command>ls</command> you can + specify an option such as <option>-la</option>.</para> + + </sect1> + + <sect1 id="s1-xml-tags-indexing"> + <title>Index Entries</title> + + <indexterm> + <primary>indexing</primary> + </indexterm> + + + <indexterm> + <primary>XML tags</primary> + <secondary>indexing</secondary> + </indexterm> + + <para>The following command sequence shows you the code inserted into + the body of the text to add an index entry to your document: + </para> + +<screen> +<computeroutput> +<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 +</computeroutput> +</screen> + + <indexterm> + <primary>foo</primary> + <secondary>bar</secondary> + </indexterm> + + + <para>The <command><seealso></command> tag allows you to + reference another index entry or refer to another manual. Make sure + the <command><seealso></command> reference you are pointing to + has its own entry. For example: + </para> + + <indexterm> + <primary>indexing</primary> + <secondary>seealso tag</secondary> + </indexterm> + +<screen> +<computeroutput> +<indexterm> +<primary>SWAK</primary> +<seealso>salutations</seealso> +</indexterm> + + +<indexterm> +<primary>salutations</primary> +</indexterm> +</computeroutput> +</screen> + + <indexterm> + <primary>SWAK</primary> + <seealso>Salutations</seealso> + </indexterm> + + <indexterm> + <primary>Salutations</primary> + </indexterm> + + <para> + The <command><see></command> tag allows you to reference to + another index entry entirely. For example: + </para> + <indexterm> + <primary>indexing</primary> + <secondary>see tag</secondary> + </indexterm> + + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <indexterm> + <primary>Guinness</primary> + <see>Beer</see> + </indexterm> + + <indexterm> + <primary>Beer</primary> + </indexterm> + + <para>To view the HTML output of the index entries shown here, refer + to the <filename>generated-index.html</filename> file at the end of + this document.</para> + +<!-- + <tip> + <title>Tip</title> + <para> + To learn more about the rules of indexing, refer to <xref + linkend="ch-indexing"></xref>. + </para> + </tip> +--> + </sect1> + + <sect1 id="s1-xml-tags-para"> + <title><command>para</command></title> + + + <indexterm> + <primary>XML tags</primary> + <secondary>para</secondary> + </indexterm> + + <para>For any paragraph, the <command><para></command> and + <command></para></command> tags must open and close that + particular paragraph. + </para> + + <sect2 id="s2-xml-tags-para"> + <title>Additional Rules for the <command><para></command> Tag + Set</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>para</secondary> + <tertiary>additional rules</tertiary> + </indexterm> + + <variablelist> + <varlistentry> + <term>Proper formatting of <command><para></command> tag and + text</term> + <listitem> + <para>Additionally, the <command><para></command> tags + should be justified around the paragraph so that the opening + <command><para></command> tag and the first word of that + paragraph are side by side. For example:</para> + +<screen> +<computeroutput> +<command><para></command>This paragraph talk about using the <para> +tag correctly.<command><para></command> +</computeroutput> +</screen> + + </listitem> + </varlistentry> + + <varlistentry> + <term>Where not to use <command><para></command> tags</term> + <listitem> + <para>Do not use para tags around anything other than a simple + paragraph. Doing so will create additional white space within + the text itself.</para> + + <para>Do not use <command><para></command> tags around the + following (or, to put this another way, do not embed the + following within <command><para></command> tags):</para> + + <itemizedlist> + <listitem> + <para><command><screen></command></para> + </listitem> + <listitem> + <para><command><itemizedlist></command></para> + </listitem> + <listitem> + <para><command><orderedlist></command></para> + </listitem> + <listitem> + <para><command><variablelist></command></para> + </listitem> + <listitem> + <para><command><table></command></para> + </listitem> + </itemizedlist> + + </listitem> + </varlistentry> + </variablelist> + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-part"> + <title><command>part</command></title> + + <indexterm> + <primary>parts</primary> + </indexterm> + + + <indexterm> + <primary>XML tags</primary> + <secondary>part</secondary> + </indexterm> + + <para> + In the parent file, you can separate the chapters into parts to divide + them into logical groups. For example, in the parent file, the + <command>part</command> tags surround the chapter entities: + </para> +<screen> +<computeroutput> +<part id="pt-foo"> + <partintro> + <para>Some text for the part intro</para> + &CHAPTER; + + &ANOTHER-CHAPTER; +</part> +</computeroutput> +</screen> + + <para> + If you create a part, include a part introduction describing the + contents of the part. For example: + </para> + +<screen> +<computeroutput> + <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> +</computeroutput> +</screen> + + <para> + 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. + </para> + + </sect1> + + <sect1 id="s1-xml-tags-prompt"> + <title><command>prompt</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>prompt</secondary> + </indexterm> + + <para> + To show a prompt, such as a root or DOS prompt, use the + <command><prompt></command> and <command></prompt></command> + commands. For example: + </para> +<screen> +<computeroutput> +At the <prompt>LILO:</prompt> boot prompt, type linux to +boot into your Linux partition. + +At the <prompt>C:\></prompt> prompt, type .... +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + At the <prompt>LILO:</prompt> boot prompt, type linux to boot into your + Linux partition. + </para> + <para> + At the <prompt>C:\></prompt> prompt, type .... + </para> + + <note> + <title>Note</title> + <para> + When showing example computer output (usually in + <command>screen</command> tags), do you include the prompt or command + (unless the command or prompt is the actually computer output you want + to show).</para> + </note> + </sect1> + + <sect1 id="s1-xml-tags-replaceable"> + <title><command>replaceable</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>replaceable</secondary> + </indexterm> + + <para> + To create replaceable text, you use the tags + <command><replaceable></command> and + <command></replaceable></command> around the text you want to use as a + variable. + </para> + <para> + This example shows the ISBN of our boxed sets with variables: + </para> +<screen> +<computeroutput> +1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + 1-58569-<replaceable>xx</replaceable>-<replaceable>y</replaceable> + </para> + </sect1> + + <sect1 id="s1-xml-tags-screen"> + <title><command>screen</command></title> + <indexterm> + <primary>XML tags</primary> + <secondary>screen</secondary> + </indexterm> + + <para> + The <command><screen></command> 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 + <command><screen></command> and closing + <command></screen></command> tags around the text you are + emphasizing. + </para> + + <important> + <title>Important</title> <para>When using the + <command><screen></command> tag, you must set everything within + that screen, including the <command><screen></command> 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.</para> + </important> + + + <para> + An example of <command><screen></command> is the following: + </para> +<screen> +<computeroutput> +<screen> +<computeroutput> +This is an example of a screen. You do not need <para> tags +within this command. +</computeroutput> +</screen> +</computeroutput> +</screen> + + <para> + The output: + </para> + +<screen> +<computeroutput> +This is an example of a screen. You do not need <command><para></command> +tags within this command. +</computeroutput> +</screen> + + <note> + <title>Note</title> <para>To properly use the + <command><screen></command> 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 + <command><computeroutput></command> tag set. If it is a command, + it needs the <command><command></command> tag set. If it is a + command with user input, it may require a construction like the one + below:</para> +<screen> +<command><command></command>command <command><userinput></command>input<command></userinput></command><command></command></command> +</screen> + + <para> + The output looks like: + </para> + +<screen> +<command>command <userinput>input</userinput></command> +</screen> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-sections"> + <title>Sections</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>sections</secondary> + </indexterm> + + <indexterm> + <primary>sections</primary> + </indexterm> + + <para>Within an article (or chapter if it is a DocBook XML book like the + <citetitle>&IG;</citetitle>), you can have sections and + subsections. <command><sect1></command> 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:</para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para> + If you only need one level of sections in a DocBook article, you can use + the <command>section</command> tag. For example: + </para> + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + </sect1> + + <sect1 id="s1-xml-tags-table"> + <title><command>table</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>table</secondary> + </indexterm> + + <para> + The following is an example of creating a table. + </para> + +<screen> +<table id="tb-mockup-before-begin"> + <emphasis>This tells XML that you will be creating a table + and the ID name is <command>"tb-mockup-before-begin."</command></emphasis> + +<title>Available Features of GNOME and KDE</title> + +<tgroup cols="3"> + <emphasis>This tells XML that you are creating a table + with three columns.</emphasis> + +<colspec colnum="1" colname="Features" colwidth="3"/> + <emphasis><command>colspec</command> says that you are giving information + about the column to XML</emphasis> <emphasis><command>colnum="1"</command> + says that you are giving specifications for the first column.</emphasis> + + <emphasis><command>colname="Features"</command> says that the title for this + column will be "Features."</emphasis> + + <emphasis><command>colwidth="3"</command> 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.</emphasis> + +<colspec colnum="2" colname="GNOME" colwidth="2"/> +<colspec colnum="3" colname="KDE" colwidth="2"/> + +<thead> + <emphasis>Contains one or more table row elements.</emphasis> + +<row> + <emphasis>Contains one or more table cell (entry) elements.</emphasis> + +<entry>Features</entry> + <emphasis>Table cell element, one of several in a row element, defining + columns within the row.</emphasis> + +<entry>GNOME</entry> +<entry>KDE</entry> +</row> +</thead> + +<tbody> + <emphasis>Contains one or more row elements, for the main text + of the table.</emphasis> + +<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> +</screen> + + <table id="tb-mockup-before-begin"> + <title>Available Features of GNOME and KDE</title> + + <tgroup cols="3"> + <colspec colnum="1" colname="Features" colwidth="3"/> + <colspec colnum="2" colname="GNOME" colwidth="2"/> + <colspec colnum="3" colname="KDE" colwidth="2"/> + + <thead> + <row> + <entry>Features </entry> + <entry>GNOME</entry> + <entry>KDE</entry> + </row> + </thead> + + <tbody> + <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> + + <sect2 id="s2-xml-tags-listintable"> + <title>Creating a List Within a Table</title> + + <indexterm> + <primary>XML tags</primary> + <secondary>table</secondary> + <tertiary>list within a table</tertiary> + </indexterm> + + + <para>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 + <application>Emacs</application>.</para> + + <para>The tags you will need to use are + <command><simplelist></command> and + <command><member></command>.</para> + + <para>The following example will show you the proper formatting for + creating a list within a table.</para> + + +<screen> +<computeroutput> +<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> +</computeroutput> +</screen> + + <para>Notice how the <command><simplelist></command> tag must be + beside the <command><entry></command> tag? If you do not format + this properly, it will not parse cleanly.</para> + + <para>The above example will look like the following:</para> + + <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> + + </sect2> + + </sect1> + + <sect1 id="s1-xml-tags-trademark"> + <title><command>trademark</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>trademark</command></secondary> + </indexterm> + + + <para>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.</para> + + <para>Instead, use the <command>trademark</command> tag and its + associates classes as follows: + </para> + +<screen> +<computeroutput> +<trademark>trademark symbol after me</trademark> +<trademark class="registered">registered trademark symbol after me</trademark> +<trademark class="copyright">copyright symbol after me</trademark> +</computeroutput> +</screen> + + </sect1> + + <sect1 id="s1-xml-tags-userinput"> + <title><command>userinput</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary><command>userinput</command></secondary> + </indexterm> + + <para> + To show what a user would type, use the <command>userinput</command> + tag. For example: + </para> +<screen> +<computeroutput> +At the prompt, type: + +<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + At the prompt, type: + </para> + + <para> + <userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> + </para> + </sect1> + + +<!-- <sect1 id="s1-xml-tags-mouse"> + <title><command>mousebutton</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>mousebutton</secondary> + </indexterm> + <para> +Describe mouse actions with the mousebutton tag. Below is an example of its use. +</para> + +<screen> +<mousebutton>Right click</mousebutton> on the image and a new menu will appear. +</screen> + + <para> +<mousebutton>Right click</mousebutton> on the image and a new menu will appear. + </para> + + </sect1> --> + + <sect1 id="s1-xml-tag-sulink"> + <title><command>ulink</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>ulink</secondary> + </indexterm> + + <para> + To create a URL link within your text, use the following example: + </para> +<screen> +<computeroutput> +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. +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + Online — <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. + </para> + + <note> + <title>Note</title> + <para> + If the URL does not end in a filename, it must end in a slash + (<computeroutput>/</computeroutput>) to be a properly formed URL. For + example, <ulink + url="http://www.redhat.com/">http://www.redhat.com/</ulink>. + </para> + </note> + + </sect1> + + <sect1 id="s1-xml-tags-wordasword"> + <title><command>wordasword</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>wordasword</secondary> + </indexterm> + + <para>The <wordasword> tag set is used to define a word meant + specifically as a word and not representing anything else.</para> + + <para>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.</para> + + <para>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.</para> + + <para>For example:</para> + +<screen> +<computeroutput>To use <command>grep</command> to search for the word +<wordasword>linux</wordasword>, use the command +<command>grep linux</command>.</computeroutput> +</screen> + + <para> + The output: + </para> + + <para>To use <command>grep</command> to search for the word + <wordasword>linux</wordasword>, use the command <command>grep + linux</command>.</para> + + <para>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.</para> + + </sect1> + + + <sect1 id="s1-xml-tags-xref"> + <title><command>xref</command></title> + + <indexterm> + <primary>XML tags</primary> + <secondary>xref</secondary> + </indexterm> + + <para> + To refer to other sections or chapters within a manual, use the + <command><xref></command> tag. + </para> + + <para> + The output of this displays the title of the section or chapter you are + pointing the user to. For example: + </para> +<screen> +<computeroutput> +For more information about the parent file, refer to +<xref linkend="ch-tutorial"><xref> and <xref linkend="s1-tutorial-parent"></xref> +</computeroutput> +</screen> + + <para> + The output: + </para> + + <para> + For more information about the parent file, refer to <xref linkend="ch-tutorial"></xref> + and <xref linkend="s1-tutorial-parent"></xref>. + </para> + </sect1> + + </chapter> 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 @@ +<!-- $Id: documentation-guide-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + +<!DOCTYPE book 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 IG "&DISTRO; Installation Guide"> <!-- Always use for Installation Guide --> + +<!ENTITY BOOKID "documentation-guide-0.1.1 (2003-09-16)"> <!-- change version of manual and date here --> + +<!ENTITY LEGALNOTICE SYSTEM "../legalnotice.xml"> + +<!ENTITY INTRODUCTION SYSTEM "docs-intro.xml"> + +<!ENTITY GETTINGFILES SYSTEM "docs-getting-files.xml"> +<!ENTITY GUIDELINES SYSTEM "docs-rh-guidelines.xml"> +<!ENTITY EMACS SYSTEM "docs-emacs.xml"> +<!ENTITY TAGS SYSTEM "docs-xml-tags.xml"> +<!ENTITY TUTORIAL SYSTEM "docs-tutorial.xml"> +<!ENTITY CONVERTING SYSTEM "docs-converting.xml"> +<!ENTITY CVS SYSTEM "../common/cvs.xml"> + + +]> + +<book id="documentation-guide" lang="en"> + <bookinfo> + <title>&NAME-TITLE; Documentation Guide</title> + <copyright> + <year>2003</year> + <holder>&FORMAL-RHI;</holder> + <holder>Tammy Fox</holder> + <holder>Johnray Fuller</holder> + <holder>Sandra Moore</holder> + </copyright> + <authorgroup> + <author> + <surname>Fox</surname> + <firstname>Tammy</firstname> + </author> + <author> + <surname>Fuller</surname> + <firstname>Johnray</firstname> + </author> + <author> + <surname>Moore</surname> + <firstname>Sandra</firstname> + </author> + </authorgroup> + &LEGALNOTICE; + </bookinfo> + + + &INTRODUCTION; + + &GETTINGFILES; + + &GUIDELINES; + + &EMACS; + + &TAGS; + + &TUTORIAL; + + &CONVERTING; + + &CVS; + +</book> 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 @@ +<!-- $Id: documentation-guide.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --> + +<!DOCTYPE book 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 IG "&DISTRO; Installation Guide"> <!-- Always use for Installation Guide --> + +<!ENTITY BOOKID "documentation-guide-0.1.1 (2003-09-16)"> <!-- change version of manual and date here --> + +<!ENTITY LEGALNOTICE SYSTEM "../legalnotice.xml"> + +<!ENTITY INTRODUCTION SYSTEM "docs-intro.xml"> + +<!ENTITY GETTINGFILES SYSTEM "docs-getting-files.xml"> +<!ENTITY GUIDELINES SYSTEM "docs-rh-guidelines.xml"> +<!ENTITY EMACS SYSTEM "docs-emacs.xml"> +<!ENTITY TAGS SYSTEM "docs-xml-tags.xml"> +<!ENTITY TUTORIAL SYSTEM "docs-tutorial.xml"> +<!ENTITY CONVERTING SYSTEM "docs-converting.xml"> +<!ENTITY CVS SYSTEM "../common/cvs.xml"> + + +]> + +<book id="documentation-guide" lang="en"> + <bookinfo> + <title>&NAME-TITLE; Documentation Guide</title> + <copyright> + <year>2003</year> + <holder>&FORMAL-RHI;</holder> + <holder>Tammy Fox</holder> + <holder>Johnray Fuller</holder> + <holder>Sandra Moore</holder> + </copyright> + <authorgroup> + <author> + <surname>Fox</surname> + <firstname>Tammy</firstname> + </author> + <author> + <surname>Fuller</surname> + <firstname>Johnray</firstname> + </author> + <author> + <surname>Moore</surname> + <firstname>Sandra</firstname> + </author> + </authorgroup> + &LEGALNOTICE; + </bookinfo> + + + &INTRODUCTION; + + &GETTINGFILES; + + &GUIDELINES; + + &EMACS; + + &TAGS; + + &TUTORIAL; + + &CONVERTING; + + &CVS; + +</book> |