diff options
| author | Paul W. Frields <stickster@gmail.com> | 2006-11-23 20:32:31 +0000 |
|---|---|---|
| committer | Paul W. Frields <stickster@gmail.com> | 2006-11-23 20:32:31 +0000 |
| commit | 2978c374a745e38b0c300d15d3bbe2648d3a8c64 (patch) | |
| tree | 4552189b36aed1b886deccab96518457514859e0 | |
| parent | 3a410abf1b43ca69203ba9d7d56cc110269fea41 (diff) | |
| download | documentation-guide-2978c374a745e38b0c300d15d3bbe2648d3a8c64.tar.gz documentation-guide-2978c374a745e38b0c300d15d3bbe2648d3a8c64.tar.xz documentation-guide-2978c374a745e38b0c300d15d3bbe2648d3a8c64.zip | |
Remove old files in en locale
| -rw-r--r-- | acknowledgments-en.xml | 45 | ||||
| -rw-r--r-- | docs-emacs-en.xml | 727 | ||||
| -rw-r--r-- | docs-emacs-nxml-en.xml | 339 | ||||
| -rw-r--r-- | docs-getting-files-en.xml | 402 | ||||
| -rw-r--r-- | docs-intro-en.xml | 43 | ||||
| -rw-r--r-- | docs-rh-guidelines-en.xml | 586 | ||||
| -rw-r--r-- | docs-style-en.xml | 1965 | ||||
| -rw-r--r-- | docs-tutorial-en.xml | 99 | ||||
| -rw-r--r-- | docs-vim-en.xml | 147 | ||||
| -rw-r--r-- | docs-xml-tags-en.xml | 2491 |
10 files changed, 0 insertions, 6844 deletions
diff --git a/acknowledgments-en.xml b/acknowledgments-en.xml deleted file mode 100644 index c7dc535..0000000 --- a/acknowledgments-en.xml +++ /dev/null @@ -1,45 +0,0 @@ - <chapter id="acknowledgments"> - <title>Acknowledgments</title> - - <para> - This document is based on the a document started by Tammy Fox (tfox at - redhat.com) and contributed to by Sandra Moore (smoore at redhat.com) and - Johnray Fuller (jrfuller at redhat.com). - </para> - - <para> - A patch from Roozbeh Pournader (roozbeh at sharif.edu) has been applied to - fix a few typos and explain that anonymous CVS access does not allow - commits. - </para> - - <para> - Patches from Gavin Henry (ghenry at suretecsystems.com) have been applied - to add the trailing slashes to the <command>figure</command> tag example - in <filename>docs-xml-tags.xml</filename> and to add <xref - linkend="ch-emacs-nxml"></xref>. - </para> - - <para> - A patch from Joshua Daniel Franklin (joshuadfranklin at yahoo.com) has been - applied to add <xref linkend="ch-vim"></xref>. - </para> - - <para> - A patch from Karsten Wade (kwade at redhat.com) has been applied to add - <xref linkend="s1-screenshots"></xref>. It was edited by Paul - W. Frields (stickstr5 at hotmail.com). - </para> - - <para> - A patch from Paul W. Frields (stickstr5 at hotmail.com) has been applied - to add more explanation of the <command>screen</command> tag set to <xref - linkend="s1-xml-tags-screen"></xref>. - </para> - - <para> - A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been - applied to more fully explaing the document building system. - </para> - - </chapter> diff --git a/docs-emacs-en.xml b/docs-emacs-en.xml deleted file mode 100644 index f690926..0000000 --- a/docs-emacs-en.xml +++ /dev/null @@ -1,727 +0,0 @@ -<!-- $Id: docs-emacs-en.xml,v 1.2 2004/08/13 15:35:41 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> - -<!-- bug #125757 in NEEDINFO state - <para> - If you have a mouse, you can also add the following. It adds popup menus - when the cursor is either on a start tag or in a region where elements - are allowed. - </para> - -<screen> -<computeroutput> -;; Mouse Bindings: right-click to generate context-aware -;; elements/attributes popup menu. -(define-key sgml-mode-map [mouse-3] 'sgml-tags-menu) -</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> - <listitem> - <para><ulink - url="http://www.snee.com/bob/sgmlfree/psgmqref.html">http://www.snee.com/bob/sgmlfree/psgmqref.html</ulink> - — <citetitle>Emacs/PSGML Quick Reference</citetitle> is a - reference table of Emacs commands for PSGML mode. - </para> - </listitem> - <listitem> - <para><ulink - url="http://www.snee.com/bob/sgmlfree/emcspsgm.html">http://www.snee.com/bob/sgmlfree/emcspsgm.html</ulink> - — <citetitle>PSGML Tricks</citetitle></para> - </listitem> - </itemizedlist> - - </sect1> - </chapter> - - - - - - - - - diff --git a/docs-emacs-nxml-en.xml b/docs-emacs-nxml-en.xml deleted file mode 100644 index 5509dfb..0000000 --- a/docs-emacs-nxml-en.xml +++ /dev/null @@ -1,339 +0,0 @@ - <chapter id="ch-emacs-nxml"> - <title>Emacs and nXML Mode</title> - - <indexterm> - <primary>nXML</primary> - </indexterm> - - <indexterm> - <primary>Emacs</primary> - </indexterm> - - <indexterm> - <primary>Emacs</primary> - <secondary>nXML mode</secondary> - </indexterm> - - <para> - You can also use the nXML mode available for - <application>Emacs</application> to make it even easier to write in - DocBook XML format. nXML mode provides context-sensitive editing using - completion, real time validity error checking, syntax highlighting and - indentation. All you need to do is install an RPM!! - </para> - - <note> - <title>Early stages</title> - <para> - Please be aware the nxml-mode for <application>Emacs</application> is - quite new, so there are a few things that the advanced user might notice - when using it with other documents types. If you keep an eye on the - mailing-list, you can keep up to date with these, as well as ask - questions. For more details, check out <xref - linkend="s1-emacs-nxml-readme"></xref>. - </para> - </note> - - - <sect1 id="s1-nxml-rpm"> - <title>Getting the nXML RPM</title> - - <indexterm> - <primary>nXML</primary> - <secondary>RPM</secondary> - </indexterm> - - <indexterm> - <primary>nXML RPM</primary> - </indexterm> - - <para> - To use nXML mode with emacs, you will need to install the nXML RPM - available from <ulink - url="http://people.redhat.com/twaugh/ftp/docbook/nxml-mode/">Tim - Waugh's</ulink> website or the source from <ulink - url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink>. The - source requires a lot more work to setup, therefore we will only be - concentrating on the RPM version. - </para> - - <para> - Information on where to get the source is available in <xref - linkend="s1-emacs-additional-resources"></xref>. - </para> - - </sect1> - - <sect1 id="s1-nxml-examples"> - <title>Examples</title> - - <para> - Compared to PSGML mode there are only couple of commands that you - need. This speeds up writing with <application>Emacs</application> - considerably, which means you can concentrate more on the content of - your article. - </para> - - <sect2 id="s2-nxml-commands"> - <title>Commands</title> - - <para> - To create a tag, type <userinput><</userinput> and then type the - keyword. To complete the keyword, press <command>Ctrl-Ret</command>, - then add the last <userinput>></userinput>. To close a tag, type - <userinput></</userinput>. - </para> - - <important> - <title>Important</title> - <para> - When you open a document that doesn't have a DOCTYPE declaration at - the top of the file, you will get this message and tag completion - won't work because nXML will not know what format you are writing. - </para> - </important> - - <para> - To load the schema, type <command>Ctrl-c</command>, then - <command>Ctrl-s</command> and navigate to - <filename>/usr/share/emacs/site-lisp/nxml-mode/schema/</filename> and - load - <filename>docbook.rnc</filename>. <application>Emacs</application> - will then prompt you to save it in the current working directory. - </para> - - - <tip> - <title>Tip</title> - <para> - The commands already discussed are the only differences between - using <application>Emacs</application> with PSGML mode and - <application>Emacs</application> with nXML mode. You will still need - to use all the same commands as discussed in <xref - linkend="s1-emacs-basic-commands"></xref>. - </para> - </tip> - </sect2> - </sect1> - - <sect1 id="s1-emacs-nxml-additional-resources"> - <title>Additional Resources</title> - - <para> - Additional Emacs and nXML references are available at the following - locations: - </para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.thaiopensource.com/download/">http://www.thaiopensource.com/download/</ulink> - — <citetitle>Author's download area</citetitle> - </para> - </listitem> - <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> - </itemizedlist> - </sect1> - - <sect1 id="s1-emacs-nxml-readme"> - <title>nXML README File</title> - - <note> - <title>Note</title> - <para> - This file can be found in the directory you extracted the source - into, or in - <filename>/usr/share/doc/nxml-mode-<replaceable><version></replaceable>/</filename> - if you installed the RPM. - </para> - </note> - - <para>README file:</para> - - <para> - This is a new major mode for GNU Emacs for editing XML documents. It - supports editing well-formed XML documents and also provides - schema-sensitive editing of XML documents using RELAX NG Compact - Syntax. - </para> - - <para> - To use this, you need GNU Emacs version 21.x, preferably 21.3. GNU - Emacs version 20 will not work properly, nor will XEmacs. - To get started, do the following: - </para> - -<screen> -<command>M-x load-file RET rng-auto.el RET</command> -</screen> - - <para> - This defines the necessary autoloads. Now, visit a file containing - an XML document, and do the following: - </para> - -<screen> -<command>M-x nxml-mode</command> -</screen> - - <para> - Now do - </para> - -<screen> -<command>C-h m</command> -</screen> - - <para> - For information on how to use nxml-mode. The beginnings of a manual are - in nxml-mode.info. You can read this using: - </para> - -<screen> -<command>C-u M-x info RET nxml-mode.info RET</command> -</screen> - - <para> - It's also installed as an entry at the end of the top-level info - directory. So you can read it with <command>C-h i</command> as usual. - </para> - - <para> - You can use <filename>test.valid.xml</filename> and - <filename>test.invalid.xml</filename> as examples of valid and invalid - XML documents. - </para> - - <para> - To get things automatically loaded each time you start Emacs, add: - </para> - -<screen> -<computeroutput> -(load "~/nxml-mode-200YMMDD/rng-auto.el") -</computeroutput> -</screen> - - <para> - to your <filename>.emacs</filename>, where - <computeroutput>~/nxml-mode-200YMMDD</computeroutput> is the directory - containing the <filename>.elc</filename> files. Note that - <filename>rng-auto.el</filename> does not load all of the nxml-mode - code; it merely sets things up so that all the features of nxml-mode - will be autoloaded properly. You should not try to autoload - <filename>rng-auto.el</filename> itself. - </para> - - <para> - To use nxml-mode automatically for files with an extension of - <filename>xml</filename>, <filename>xsl</filename>, - <filename>rng</filename> or <filename>xhtml</filename>, add the - following to your <filename>.emacs</filename> file: - </para> - -<screen> -<computeroutput> -(setq auto-mode-alist - (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) - auto-mode-alist)) -</computeroutput> -</screen> - - <para> - If you edit XML using iso-8859-N encodings other than iso-8859-1 and you - are running Emacs 21.3 or later, then I recommend enabling - unify-8859-on-decoding-mode, by adding the following to your - <filename>.emacs</filename> file: - </para> - -<screen> -<computeroutput>(unify-8859-on-decoding-mode)</computeroutput> -</screen> - - <para> - To get validation and schema-sensitive editing, you need a RELAX NG - Compact Syntax (RNC) schema for you document. The schema directory - includes some schemas for popular document types. - </para> - - <para> - For more on RELAX NG, refer to <ulink - url="http://relaxng.org/">http://relaxng.org/</ulink>. - </para> - - <para> - For a tutorial on RELAX NG Compact Syntax, refer to <ulink - url="http://relaxng.org/compact-tutorial.html">http://relaxng.org/compact-tutorial.html</ulink> - </para> - - <para> - For automatically creating RNC schemas, I recommend my Trang program: - <ulink - url="http://www.thaiopensource.com/relaxng/trang.html">http://eee.thaiopensource.com/relaxng/trang.html"</ulink> - </para> - - <para> - You can use this to - -<itemizedlist> - <listitem> - <para> - Infer an RNC schema from an instance document - </para> - </listitem> - <listitem> - <para> - Convert a DTD to an RNC schema - </para> - </listitem> - <listitem> - <para> - Convert a RELAX NG XML syntax schema to an RNC schema - </para> - </listitem> -</itemizedlist> - </para> - - <para> - To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you can - also use the XSLT stylesheet from <ulink - url="http://www.pantor.com/download.html">http://www.pantor.com/download.html"</ulink>. - </para> - - <para> - To convert a W3C XML Schema to an RNC schema, you need first to convert - it to RELAX NG XML syntax using Sun's RELAX NG converter tool rngconv - (built on top of MSV). Refer to <ulink - url="https://msv.dev.java.net/">https://www.dev.java.net/</ulink>. - </para> - - <para> - The file <filename>NEWS</filename> describes recent changes. - </para> - - <para> - Please use the list <ulink - url="http://groups.yahoo.com/group/emacs-nxml-mode/">http://groups.yahoo.com/group/emacs-nxml-mode</ulink> - for bug reports, discussion. I will announce all new versions there. - </para> - - <para> - James Clark - </para> - <para> - jjc@thaiopensource.com - </para> - </sect1> - </chapter> diff --git a/docs-getting-files-en.xml b/docs-getting-files-en.xml deleted file mode 100644 index 8f362d8..0000000 --- a/docs-getting-files-en.xml +++ /dev/null @@ -1,402 +0,0 @@ -<!-- $Id: --> -<!-- -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - -<!ENTITY BOILERPLATE "This header makes editing XML easier" > -<!ENTITY FDPX "Fedora Docs Project" > -<!ENTITY FED "Fedora" > - -]> ---> -<chapter id="ch-getting-files"> - <title>Prerequisites</title> - - <para> - Before you being working with the &FED; documents, you must have certain tools and packages installed on your system. - The directions below will help you configure your setup. - </para> - - <section id="ch-getting-files-system-packages"> - <title>System Packages</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> - You can verify these packages are on your system by: - </para> - - <screen> - <userinput> -rpm -q xmlto -rpm -q docbook-style-xsl -rpm -q docbook-dtds -</userinput> - </screen> - - <para> - Any missing package can be installed using <application>yum(8)</application> this way: - </para> - - <screen> - <userinput> -su -c 'yum install xmlto' -su -c 'yum install docbook-style-xsl' -su -c 'yum install docbook-dtds' -</userinput> - </screen> - </section> - <section id="ch-getting-files-fdp"> - <title>Fedora Documentation Tools</title> - - <para> - You need perform these steps only once. - These files are common to all the &FDPX; documents. - </para> - - <para> - The custom scripts and stylesheets used are all stored in CVS on the <computeroutput>cvs.fedora.redhat.com</computeroutput> CVS server. - You need to check them out along with the DocBook XML files for the existing docs. - </para> - - <para> - When you see the password prompt, press the <keycap>Enter</keycap> key. - In the example below, we also show how to obtain a copy of an existing &FDPX; document. - </para> - - <screen> -<userinput>mkdir my-fedora-docs-sandbox -cd my-fedora-docs-sandbox -export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs -cvs login -cvs co docs-common -cvs co example-tutorial</userinput> -</screen> - </section> - <section id="ch-getting-files-filenames"> - <title>Filename Conventions</title> - <para> - &FDPX; provides the tools, scripts, and stylesheets to transform your <abbrev>XML</abbrev> documents into either <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> output formats. - In addition, your document can automatically be built into an <abbrev>RPM</abbrev> package. - </para> - <para> - To take advantage of these services, you should follow our conventions for naming your files. - While you may choose whatever filenames you like, adopting our practices will make your life simpler. - Of course, if you are bringing your own document into our building system, changing hundreds of filenames may seem quite a burden; relax, we can use your filenames with just a little work on your part. - Read on to find out how. - </para> - <section id="ch-getting-files-filenames-doc"> - <title>Document Filenames</title> - <para> - Each document lives in a peer directory to the <filename>docs-common</filename> directory you extracted from the &FED; archive earlier. - Name your document directory something related to its subject, just avoid any name already taken. - The <userinput>cvs co -c</userinput> command mentioned earlier will show you the names already taken. - </para> - </section> - <section id="ch-getting-files-i18n"> - <title>Anticipating I18N Translation</title> - <para> - The &FDPX; includes an active translation team. - Project documents are often translated into several languages. - By convention, the translated files share the directory with the original files; filenames must be unique. - </para> - <para> - &FDPX; filenames are constructed appending a dash followed by the <abbrev>ISO</abbrev> language symbol before any file extention. - For example, a file whose language content is <abbrev>US</abbrev> English could be named <filename>mydoc-en.xml</filename>; the file containing its Chinese translation would then be named <filename>mydoc-zh_CN.xml</filename>, and so on. - </para> - <para> - To assist this effort, the document build system assumes that each file is tagged with its <abbrev>I18N</abbrev> locale. - Our filename convention is shown in <xref linkend="ch-getting-files-i18n-table"/> - </para> - <table id="ch-getting-files-i18n-table"> - <title>&FDPX; Filename Conventions</title> - <tgroup cols="2"> - <colspec align="right" colnum="1" colwidth="*1"/> - <colspec colnum="2" colwidth="*5"/> - <thead> - <row> - <entry> - <phrase>Compoment</phrase> - </entry> - <entry> - <phrase>Description</phrase> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <phrase><replaceable>anything_but_dash</replaceable></phrase> - </entry> - <entry> - <para> - The initial portion of a filename can be anything, as long as <emphasis>no dash</emphasis> is used. - </para> - </entry> - </row> - <row> - <entry> - <phrase><filename>-</filename></phrase> - </entry> - <entry> - <para> - A dash (<filename>-</filename>) is to be used only to introduce the <systemitem class="macro">${LANG}</systemitem> filename component. - </para> - </entry> - </row> - <row> - <entry> - <phrase><systemitem class="macro">${LANG}</systemitem></phrase> - </entry> - <entry> - <para> - The <systemitem class="macro">${LANG}</systemitem> component identifies the <wordasword>locale</wordasword> for the file content. - </para> - <para> - In addition to helping classify files according to their language content, we also use the <systemitem class="macro">${LANG}</systemitem> value as an <abbrev>UTF-8</abbrev> locale when rendering the document. - For example, the document <filename>mydoc-it.xml</filename>will be rendered using <systemitem class="resource">it.UTF-8</systemitem> as the language environment. - </para> - <para> - For more information on <abbrev>I18N</abbrev> localization, visit the <ulink url="http://www.openi18n.org"/> web site. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - <warning> - <title>Document Filenames Are Special</title> - <para> - The main file in your document <emphasis>must</emphasis> follow the file naming convention or the document building system cannot find it. - </para> - </warning> - </section> - </section> - <section id="ch-getting-files-build-system"> - <title>The Document Build System</title> - <para> - Common tasks such as rendering the document into either <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> can be performed easily using the document building system. - </para> - <para> - The building system heavily leverages the <application>make(1)</application> tool and shell scripts to automate these activities, but authors need <emphasis>no</emphasis> prior experience with either shell scripts or a <filename>Makefile</filename>. - While individual documents do have their own <filename>Makefile</filename>, it is only a few lines long and very simple. - The document <filename>Makefile</filename> content is designed for cut'n paste. - </para> - <para> - As an example, <xref linkend="ch-getting-files-build-system-makefile"/> shows the whole <filename>Makefile</filename> for a simple document having only one file and one language. - </para> - <example id="ch-getting-files-build-system-makefile"> - <title>Sample Document Makefile</title> -<programlisting width="60"> -DOCBASE = mydoc -LANGUAGES = en -XMLEXTRAFILES-en= -include ../docs-common/Makefile.common -</programlisting> -</example> - <para> - Our main <abbrev>XML</abbrev> file is <filename>mydoc-en.xml</filename>; no translation has been done yet. - </para> - <para> - The <systemitem class="macro">LANGUAGES</systemitem> definition lists the English locale <literal>en</literal>; when other translations become available, their locale will just be appended to this definition. - </para> - <para> - Our document has only the main file <filename>mydoc-en.xml</filename>, but other documents may be split over several files. - The <systemitem class="macro">XMLEXTRAFILES-en</systemitem> definition catalogs these additional files so that the document building system can watch them for changes and rebuild the document when necesssary. - This definition is just a simple list of files. - </para> - <para> - The final line, beginning with <literal>include</literal>, references the main <filename>Makefile</filename> for the build system. - The <filename>Makefile.common</filename> file contains all the <application>make(1)</application> targets and rules to actually build the document and the various archives. - </para> - <para> - Add new document translations by: - </para> - <orderedlist> - <listitem> - <para> - Add the translated document files to the document directory. - Be sure to use the proper <systemitem class="macro">${LANG}</systemitem> filename component to keep the filenames similar, but unique. - </para> - </listitem> - <listitem> - <para> - Edit the <filename>Makefile</filename> to append the new <systemitem class="macro">${LANG}</systemitem> to the <systemitem class="macro">LANGUAGES</systemitem> definition. - </para> - </listitem> - <listitem> - <para> - Create a new <systemitem class="macro">XMLEXTRAFILES-${LANG}</systemitem> definition that references any document files other than the base file. - </para> - </listitem> - </orderedlist> - <section id="ch-getting-files-build-system-targets"> - <title>Build System Actions</title> - <para> - To render the <abbrev>XML</abbrev> document into <abbrev>HTML</abbrev> or <abbrev>PDF</abbrev> the command: <userinput>make html</userinput>, - <userinput>make html-nochunk</userinput>, or <userinput>make pdf</userinput> may be used. - </para> - <para> - <xref linkend="ch-getting-files-build-system-targets-table"/> lists the defined build system targets. - </para> - <table id="ch-getting-files-build-system-targets-table"> - <title>Document Building Targets</title> - <tgroup cols="2"> - <colspec align="right" colnum="1" colwidth="*1"/> - <colspec colnum="2" colwidth="*5"/> - <thead> - <row> - <entry><phrase>Target</phrase></entry> - <entry><phrase>Description</phrase></entry> - </row> - </thead> - <tbody> - <row> - <entry><phrase><filename>all</filename></phrase></entry> - <entry> - <para> - Builds the <abbrev>HTML</abbrev>, and the <abbrev>PDF</abbrev> forms of the document in all its defined translations. - </para> - <para> - Also builds the archives, such as <application>tar(1)</application> and <application>rpm(8)</application>. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>tarball</filename></phrase></entry> - <entry> - <para> - Builds only the <application>tar(1)</application> archive for all document languages. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>pdf</filename></phrase></entry> - <entry> - <para> - Builds only the <abbrev>PDF</abbrev> document for all document languages. - </para> - <para> - Currently, <abbrev>PDF</abbrev> production is problematic and probably will not work for your document. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>html</filename></phrase></entry> - <entry> - <para> - Builds only the <abbrev>HTML</abbrev> document for each defined translation. - Output is placed in a separate directory: - <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>/</filename>; each document section is given its own file within that directory. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>html-nochunks</filename></phrase></entry> - <entry> - <para> - Builds only the <abbrev>HTML</abbrev> document for each defined translation. - Output is placed in a single file: - <systemitem class="macro">${DOCBASE}</systemitem><filename>-</filename><systemitem class="macro">${LANG}</systemitem><filename>.html</filename>; no other files are created. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>clean</filename></phrase></entry> - <entry> - <para> - Deletes any temporary, or generated files. - Does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, or archive files. - </para> - </entry> - </row> - <row> - <entry><phrase><filename>distclean</filename></phrase></entry> - <entry> - <para> - Erases all <abbrev>HTML</abbrev>, <abbrev>PDF</abbrev>, and archive files. - Automatically invokes the <filename>clean</filename> target as well. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - <para> - You can add your own special targets and rules by placing them at the bottom of the document <filename>Makefile</filename>, below the <literal>include</literal> line. - </para> - <para> - Be sure to follow your target definitions with a double colon, not just one. - This will allow you to supply extra steps for the defined targets. - </para> - </section> - <section id="ch-getting-files-build-system-images"> - <title>Using Document Image Files</title> - <para> - Image files, such as <filename>.PNG</filename>, are often used in documents. - While your image files may be placed anywhere you like, we recommend that you store your image files in a <filename>figs/</filename> subdirectory within your document directory. - In other words, place your image <filename>picture.png</filename> in the <filename>mydoc/figs/picture.png</filename> file. - </para> - <note> - <title>Use PNG Images, Not JPG</title> - <para> - Depending on the output media, sometimes images may be scaled, - streteched, or squashed. - To minimize any distortions, we recommend that you use only - <wordasword>PDF</wordasword> images and avoid <wordasword>JPG</wordasword> files. - </para> - <para> - You may find the <systemitem class="filesystem">convert(1)</systemitem> program, from the <application>ImageMagick</application> <abbrev>RPM</abbrev> package, provides a convenient way to reformat any <wordasword>JPG</wordasword> images you already have. - </para> - </note> - <para> - You may organize your image files into as many subdirectories under <filename>figs/</filename> as you choose. - The document building system will recreate your image subdirectory structure in the output documents. - </para> - <para> - In addition, we recommend that you follow our convention on naming the image. - For example, an image often contains a caption or other text. - This text should be translated along with the document content, so keeping <filename>words-en.png</filename> separate from <filename>words-ru.png</filename> is a good practice. - An image file with no text can be named just <filename>picture.png</filename>, for example. - </para> - <para> - Sometimes, a document may require images that do not follow the naming convention. - You may still use these images with the document building system, but it requires that you create an ordinary text file containing the image filenames you want to use. - This file must be named <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> so that the build system can find it as the search for image filenames begins. - </para> - <para> - An easy way to create the <filename>figs/Manifest-</filename><systemitem class="macro">${LANG}</systemitem> file is shown in <xref linkend="ch-getting-files-build-system-manifest"/>. - </para> - <example id="ch-getting-files-build-system-manifest"> - <title>Building A Manifest</title> -<programlisting> -rm -f figs/Manifest-en -find figs -print >/tmp/manifest -mv /tmp/manifest figs/Manifest-en -vi figs/Manifest-en -</programlisting> -</example> - - </section> - </section> -</chapter> diff --git a/docs-intro-en.xml b/docs-intro-en.xml deleted file mode 100644 index 90adb3c..0000000 --- a/docs-intro-en.xml +++ /dev/null @@ -1,43 +0,0 @@ -<!-- $Id: docs-intro-en.xml,v 1.3 2004/08/13 16:08:48 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 &FC; 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> - <listitem> - <para>Emacs with nXML mode (optional, but also 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 deleted file mode 100644 index c799abc..0000000 --- a/docs-rh-guidelines-en.xml +++ /dev/null @@ -1,586 +0,0 @@ - <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.2 2004/08/31 15:45:29 tfox Exp $ --> -</computeroutput> -</screen> - - </sect1> - - <sect1 id="s1-xml-admon"> - <title>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> - - <sect1 id="s1-screenshots"> - <title>Screenshots</title> - - <indexterm> - <primary>screenshots</primary> - <secondary>how to take</secondary> - </indexterm> - <indexterm> - <primary>screen captures</primary> - <see>screenshots</see> - </indexterm> - <indexterm> - <primary>screen grabs</primary> - <see>screenshots</see> - </indexterm> - - <para> - There are two types of screenshots: graphical and textual. The - philosophy on using these two types is <firstterm>rely on text over - graphics</firstterm>. This means, if you can say it in text instead of - showing a graphic, do so. A graphical screenshot of a GUI can create a good - setting of objects to then describe textually, but you don't want to create - a screenshot for each graphical step. - </para> - <para> - The main reason for this preference is that a block of text can usually - convey more meaning than the same physical space of graphics. This is - highly dependent on the graphic; obviously, a photographic image of a - scene can convey more than 1000 words can. A GUI screenshot is usually - full of blank space with a few elements that can just as easily be - described or listed. - </para> - <para> - The steps for taking a graphical screenshot illustrate how using text to - describe a procedure is more concise than a series of screenshots. - </para> - <variablelist> - <varlistentry> - <term>Graphical Screenshot</term> - <listitem> - <procedure> - <step> - <para> - Set the theme to Bluecurve defaults. This gives a look that - is familiar to most readers, and makes &FDP; documents - consistent. From the panel menu, choose - <guimenu>Preferences</guimenu>, - <guimenuitem>Theme</guimenuitem> and select - <guimenuitem>Bluecurve</guimenuitem> from the theme list. - </para> - </step> - <step> - <para> - Set fonts to Bluecurve defaults as well. From the panel menu, - choose <guimenu>Preferences</guimenu>, - <guimenuitem>Fonts</guimenuitem>. Set the - <guilabel>Application font</guilabel> and the - <guilabel>Desktop font</guilabel> to Sans Regular 10. Set the - <guilabel>Window Title font</guilabel> to Sans Bold 10. Set - the <guilabel>Terminal font</guilabel> to Monospace Regular - 10. - </para> - </step> - <step> - <para> - Before taking the screenshot, try to resize the targeted GUI - element(s) to the smallest possible size they can be. Your - target is an image of 500 pixels or less. If you are doing a - screenshot of more than one GUI element, you may need to - resize the screenshot in a following step. - </para> - </step> - <step> - <para> - To take the screenshot, select the GUI element with your - mouse, bringing it to the forefront, or otherwise arranging - the elements. Press <keycombo> <keycap>Alt</keycap> - <keycap>Print Screen</keycap> </keycombo> to capture a single - GUI window. For capturing the entire desktop use - <keycap>Print Screen</keycap>. If you are taking a shot of - multiple elements and have grouped them closely together, you - can crop the resulting image in <application>The - GIMP</application>. The image will be in the PNG format. - </para> - </step> - <step> - <para> - If you need to, you can resize using <application>The - GIMP</application>. With the image open, right-click on it - and choose <guimenu>Image</guimenu> -> <guimenuitem>Scale - Image...</guimenuitem>. With the chain symbol intact, set the - <guilabel>New Width</guilabel> to <guilabel>500 px</guilabel>, - and click <guibutton>OK</guibutton>. Be sure to <keycombo> - <keycap>Ctrl</keycap> <keycap>s</keycap> </keycombo> to save - your changes to your PNG before converting to EPS. - </para> - </step> - <step> - <para> - With the image open in <application>The GIMP</application>, - right-click on the image, selecting <guimenu>File</guimenu> - -> <guimenuitem>Save As...</guimenuitem>. Under - <guimenu>Determine File Type:</guimenu>, select - <guimenuitem>PostScript</guimenuitem>, then click - <guibutton>OK</guibutton>. Allow flattening of the image by - clicking <guibutton>Export</guibutton>. - </para> - <para> - In the <guilabel>Save as PostScript</guilabel> window, select - <guilabel>Encapsulated PostScript</guilabel>, and click - <guibutton>OK</guibutton>. - </para> - </step> - </procedure> - <para> - For more information about calling the images from the XML, refer - to <xref linkend="s1-xml-tags-figure"/>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Text Screenshot</term> - <listitem> - <para>Textual screen information is also useful for readers. If you - use a graphical screenshot to illustrate a function, and the - textual mode has identical functions, you should not include - both, unless omitting either would make your description - unclear. You should make your information generic over specific. - Omit the username and machine information, and separate what the - user types from sample command output. Also, in - <command>screen</command> tags, what the user types should be in - <command>userinput</command> tags, and what the user is shown as - output should be in <command>computeroutput</command> tags. - For example, the usage in - <xref linkend="ex-text-screenshot-bad"/> should look like <xref - linkend="ex-text-screenshot-good"/>. - </para> - <example id="ex-text-screenshot-bad"> - <title>Incorrect Textual Screenshot</title> - <screen> -<userinput>ps ax | grep ssh</userinput> -<computeroutput> - 2564 ? S 0:23 /usr/sbin/sshd - 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients - 8235 ? S 0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost -17223 pts/0 S 0:00 ssh rbalboa@core-router7 -17227 pts/2 S 0:10 ssh rbalboa@smbshare2 -21113 pts/7 S 1:19 ssh rocky@xxx.private -</computeroutput> - </screen> - </example> - <example id="ex-text-screenshot-good"> - <title>Correct Textual Screenshot</title> - <para> - To find all the currently active ssh sessions, execute the - following command: - </para> -<screen> -<command>ps ax | grep ssh</command> -</screen> - - <para> - The output will appear similar to: - </para> - - <screen> -<computeroutput> - 2564 ? S 0:23 /usr/sbin/sshd - 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients - 8032 pts/0 S 0:00 ssh user@host.example.com - 8032 pts/1 S 0:00 ssh root@backup.example.com -</computeroutput> - </screen> - </example> - <para> - For more information about using screen, refer to <xref - linkend="s1-xml-tags-screen"/>. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="s1-diagrams-images"> - <title>Diagrams and Images</title> - - <indexterm> - <primary>images</primary> - </indexterm> - <indexterm> - <primary>diagrams</primary> - <secondary>creating</secondary> - </indexterm> - - <para> - To be written - </para> - - </sect1> - - </chapter> - - - - diff --git a/docs-style-en.xml b/docs-style-en.xml deleted file mode 100644 index 4327a6f..0000000 --- a/docs-style-en.xml +++ /dev/null @@ -1,1965 +0,0 @@ -<!-- $Id: --> - -<chapter id="ch-style"> - - <title>Style</title> - - <para> - Writing good technical documentation is not simply reproducing - command lines and instruction sets. Good documentation is easy to - read, understand, and translate, and presents a concise logical - progression of concepts. Good documentation can also be defined by - what it does <emphasis>not</emphasis> contain. Your tutorial should - avoid: - </para> - <itemizedlist> - <listitem> - <para> - Excessive wordiness - </para> - </listitem> - <listitem> - <para> - Unnecessary or undefined jargon - </para> - </listitem> - <listitem> - <para> - Grammatical or spelling errors - </para> - </listitem> - <listitem> - <para> - References to yourself or your experiences - </para> - </listitem> - <listitem> - <para> - Remarks which might offend or confuse any reader - </para> - </listitem> - </itemizedlist> - <para> - This chapter contains style rules and guidelines for writing &FED; - documentation. Guidelines are not the same as rules. It is - acceptable to violate a guideline when it makes your material easier - to understand. Follow guidelines whenever possible, but follow - rules at all times. Assume any advice is a guideline unless - identified otherwise. - </para> - - <section id="sn-intro-to-style"> - - <title>Why Style Is Important</title> - - <para> - Writing well comes naturally to almost no one. It is a skill that - professional writers, even famous ones, must practice constantly. - <firstterm>Style</firstterm> - <indexterm><primary>style</primary></indexterm> is the quality - that separates elegant writing from the merely functional. - </para> - <para> - Elegance comes in many forms. In prose and poetry, elegant - writing may not follow some (or any) common rules of grammar, - syntax, or spelling. A good example is Episode 18, "Penelope," in - James Joyce's novel <citetitle>Ulysses</citetitle><footnote - id='fn-ulysses'> - <para> - For example, refer to. <ulink - url="http://www.online-literature.com/james_joyce/ulysses/18/">http://www.online-literature.com/james_joyce/ulysses/18/</ulink>. - Please note that this example contains some mature themes and - language, and is not suitable for all readers. - </para> - </footnote>. There, Joyce uses long streams of words without - punctuation to simulate a character's internal consciousness. By - violating basic rules of grammar and syntax, Joyce simulates the - disorganized but loosely connected thought patterns of the - narrator. - </para> - <para> - Technical documentation, however, should always respect these - rules. The more a document departs from standard language usage, - the more difficult the material becomes for the reader. For - example, readers may not be native speakers of the language used, - or they might be reading a translation. If the writer uses slang, - idioms, or jargon, a reader or translator may easily become - confused. The following example compares two different written - executions of the same idea: - </para> - <example> - <title>Incorrect style</title> - - <!-- I prefer "incorrect," because I think terms such as - "problematic" are mealy-mouthed. They remind me of the late - 1980's English textbook trend toward the politically correct yet - wholly unhelpful "standard/nonstandard." But then, I tend to be - dogmatic; it's probably my Catholic upbringing. [PWF] --> - - <para> - So you made the changes I showed you in the last section. What's - the next thing you should do? Just pop your thumb drive onto - your system and read the <filename>messages</filename> log. When - you see "USB device found," then Bob's your uncle. - </para> - </example> - <example> - <title>Correct style</title> - - <!-- I prefer "correct." See above. [PWF] --> - - <para> - After you complete the configuration changes above, attach the - USB removable media to your system. Use the - <command>dmesg</command> command to examine the kernel message - log. The message <computeroutput>USB device - found</computeroutput> indicates that your device was - installed successfully. - </para> - </example> - <para> - The first example is more conversational English, which is not - appropriate for official written documentation. The second - example is more formal, but as a result it is easier to - comprehend, both for native readers and translators. - </para> - <para> - Following style rules and guidelines also makes readers more - comfortable with a set of documents. Consistent style enhances - the professional appearance of documentation, and its perceived - value. On the other hand, lapses in punctuation or poor grammar - negatively affect a reader's reaction to written material. A - reader can feel that an otherwise correct technical document is - lacking in authority, simply because it is poorly written. Readers - feel at ease when they do not have to struggle to understand an - author's use of language. - </para> - <para> - This chapter cannot possibly cover enough material to make every - reader a good writer. Some manuals devoted entirely to writing - style are themselves hundreds of pages long. This chapter - provides enough guidelines for intermediate writers to understand - style usage in technical documentation. - </para> - <para> - If you are not a practiced writer, whether of technical - documentation or otherwise, you may benefit from other style - resources. The following list is far from comprehensive, but - provides a starting point: - </para> - <itemizedlist> - <listitem> - <para> - <citetitle>The Elements of Style</citetitle>, by William - Strunk. Basic rules and links to online versions can be found - at: <ulink - url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink> - </para> - </listitem> -<!-- placeholder for when it's ready - <para> - <citetitle>The Elements of Style</citetitle>, by William - Strunk. Fedora Docs Project version: <ulink - url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink> - </para> ---> - <listitem> - <para> - <citetitle>The Chicago Manual of Style</citetitle>, by the - University of Chicago Press. Online version: <ulink - url="http://www.chicagomanualofstyle.org/">http://www.chicagomanualofstyle.org/</ulink> - </para> - </listitem> - <listitem> - <para> - <citetitle>Paradigm Online Writing Assistant</citetitle>, - maintained by Chuck Guilford, Ph.D. Online only: <ulink - url="http://www.powa.org/">http://www.powa.org/</ulink> - </para> - </listitem> - </itemizedlist> - <para> - There are many free software documentation projects which have - developed their own style guidelines. This chapter, in fact, - draws heavily on the <citetitle>GNOME Documentation Style - Guidelines</citetitle> (<firstterm>GDSG</firstterm>). You may - read the original <citetitle>GDSG</citetitle> at <ulink - url='http://developer.gnome.org/documents/style-guide/'>http://developer.gnome.org/documents/style-guide/</ulink>. - </para> - - </section> - - <section id="sn-tech-docs-fundamentals"> - - <title>Fundamental Concepts of Technical Documentation</title> - - <note> - <title>Bibliographic Information</title> - <para> - This section is drawn primarily from the - <citetitle>GDSG</citetitle>. - </para> - </note> - - <!-- This section will reproduce mostly what is in Chapter 1 of - the GDSG. There may be minor changes. FIXME: Make sure the - appropriate front matter of the Documentation Guide includes - attribution as required by the GNU FDL. --> - - <para> - This chapter provides a brief introduction to writing technical - documentation. - </para> - - <section id="sn-fundamentals-1"> - <title>General Style Requirements</title> - <para> - Technical writing for the &FP; imposes special constraints - beyond the basic requirements of good prose. Good &FED; - technical documentation has the following characteristics: - </para> - <variablelist> - <varlistentry> - <term>Comprehensive</term> - <listitem> - <para> - Describe all of the functionality of a product. Do not - omit functionality that you regard as irrelevant for the - user. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Conforming</term> <!-- I'm having issues with the - sketchy definition of this non-dictionary word and the - associated text. Not wrong, per se, just wishing for - something better. This note shall remind us! - kwade --> - <!-- Hopefully this change helps. Makes sense according to the - gdict tool in Core, at least. - PWF --> - <listitem> - <para> - Describe what you see. Do not describe what you want to - see. Present your information in the order that users - experience the subject matter. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Clear</term> - <listitem> - <para> - Read <citetitle>The Elements of Style</citetitle> (<ulink - url="http://en.wikipedia.org/wiki/The_Elements_of_Style">http://en.wikipedia.org/wiki/The_Elements_of_Style</ulink>) - to help make your writing clear. - </para> -<!-- placeholder for when this is published: - <para> - Read <citetitle>The Elements of Style</citetitle> - &FED;-version (<ulink - url="http://fedora.redhat.com/docs/eos-guide-en/">http://fedora.redhat.com/docs/eos-guide-en/</ulink>) - to help make your writing clear. - </para> ---> - </listitem> - </varlistentry> - <varlistentry> - <term>Consistent</term> - <listitem> - <para> - Use agreed vocabulary throughout your documentation. Use - the same vocabulary as other writers who are working on - related documentation. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Concise</term> - <listitem> - <para> - Review your work frequently as you write your document. - Ask yourself which words you can take out. Refer to <xref - linkend="sn-fundamentals-2"/> for specific guidelines. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sn-fundamentals-2"> - <title>Golden Rules</title> - <para> - This section contains some basic style guidelines. Subsequent - sections in this chapter expand on these guidelines to give more - detailed guidance. - </para> - <variablelist> - <varlistentry> - <term>Golden Rule 1: Be brief</term> - <listitem> - <itemizedlist> - <listitem> - <para> - Limit each sentence to fewer than 25 words. - </para> - </listitem> - <listitem> - <para> - Limit each procedure step to 23 words. - </para> - </listitem> - </itemizedlist> - <example id="ex-golden-rule-1-wrong"> - <title>Incorrect: Too long</title> - <para> Under normal operating conditions, the kernel does - not always immediately write file data to the disks, - storing it in a memory buffer and then periodically - writing to the disks to speed up operations. - </para> - </example> - <example id="ex-golden-rule-1-right"> - <title>Correct: Less wordy</title> - <para> - Normally, the kernel stores the data in memory prior to - periodically writing the data to the disk. - </para> - </example> - </listitem> - </varlistentry> - <varlistentry> - <term>Golden Rule 2: Be organized</term> - <listitem> - <itemizedlist> - <listitem> - <para> - Limit each paragraph to one topic. - </para> - </listitem> - <listitem> - <para> - Limit each sentence to one idea. - </para> - </listitem> - <listitem> - <para> - Limit each procedure step to one action. - </para> - </listitem> - </itemizedlist> - <example id="ex-golden-rule-2-wrong"> - <title>Incorrect: Disorganized topics</title> - <para> - The <application>Workspace Switcher</application> applet - helps you navigate all of the virtual desktops available - on your system. The X Window system, working in hand - with a piece of software called a <emphasis>window - manager</emphasis>, allows you to create more than one - virtual desktop, known as - <emphasis>workspaces</emphasis>, to organize your work, - with different applications running in each workspace. - The <application>Workspace Switcher</application> applet - is a navigational tool to get around the various - workspaces, providing a miniature road map in the GNOME - panel showing all your workspaces and allowing you to - switch easily between them. - </para> - </example> - <example id="ex-golden-rule-2-right"> - <title>Correct: Organized topics</title> - <para> - Use the <application>Workspace Switcher</application> to - add new <emphasis>workspaces</emphasis> to the GNOME - Desktop. You can run different applications in each - workspace. The <application>Workspace - Switcher</application> applet provides a miniature map - that shows all of your workspaces. You can use the - <application>Workspace Switcher</application> applet to - switch between workspaces. - </para> - </example> - <tip> - <para> - Plan the order of paragraphs before you start writing. - Decide which topic you want to cover in each paragraph. - </para> - </tip> - </listitem> - </varlistentry> - <varlistentry> - <term>Golden Rule 3: Be demonstrative</term> - <listitem> - <para> - Use explicit examples to demonstrate how an application - works. Provide instructions rather than descriptions. - </para> - <example id="ex-golden-rule-3-wrong"> - <title>Incorrect: Describes but does not - demonstrate</title> - <para> - There is a text box that you can use to find out the - definition of a word. - </para> - </example> - <example id="ex-golden-rule-3-right"> - <title>Correct: Demonstrates usage</title> - <para> - To request a definition of a word, type the word in the - text box, then select <guilabel>Lookup</guilabel>. - </para> - </example> - <tip> - <para> - Do not apply this guideline too rigidly. Sometimes you - must explain how software works to support your how-to - examples. - </para> - </tip> - </listitem> - </varlistentry> - <varlistentry id="vle-golden-rule-4"> - <term>Golden Rule 4: Be objective</term> - <listitem> - <para> - Write in a neutral tone. - </para> - <example id="ex-golden-rule-4-wrong"> - <title>Incorrect: Sentence takes sides</title> - <para> - The applet is a handy little screen grabber. - </para> - </example> - <example id="ex-golden-rule-4-right"> - <title>Correct: Sentence is objective</title> - <para> - Use the applet to take screenshots. - </para> - </example> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sn-fundamentals-3"> - - <title>Tone</title> - <para> - Inappropriate tone hinders reader access to information. A - neutral tone free of opinion or personal flavor improves the - reader's comprehension. Neutral tone helps writers to work in - parallel on a large technical documentation project. - Furthermore, additional writers may join the project at any - time. Use of a neutral tone helps to achieve consistency across - a documentation set, and thereby facilitates user access to - information. The best way to achieve a common, neutral tone is - to apply the following principles: - </para> - <variablelist> - <varlistentry> - <term>Avoid humor</term> - <listitem> - <para> - Humor distracts from the information you are trying to - provide. Humor also makes documentation difficult to - translate. Stay factual. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid personal opinions</term> - <listitem> - <para> - Whether you think a function is useful or woeful is - irrelevant. Report the function to the user, with - instructions about how to use the function. Stay - accurate. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid colloquial language</term> - <listitem> - <para> - Colloquial language is difficult to translate and usually - culture-specific. Stay neutral. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid topical expressions</term> - <listitem> - <para> - An expression that is in common use today might convey - something completely different tomorrow. Stay technical. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid aspirational statements</term> - <listitem> - <para> - Statements about the future developments of a product do - not belong in technical documentation. Write about what - you see right now. Stay real. - </para> - </listitem> - </varlistentry> - </variablelist> - </section> - <section id="sn-fundamentals-4"> - <title>Reaching the Right Audience</title> - <para> - All of the decisions that you make about the structure and - content of a manual follow from an understanding of the - audience. Consider how the audience accesses the documentation, - what sort of information the audience needs, and the experience - level of the audience. Usually, you need to create - documentation that is suitable for different audiences. The - following sections introduce some of the audience-related topics - you need to consider. - </para> - </section> - <section id="sn-fundamentals-6"> - <title>User Motivation</title> - <para> - Do not waste the time of the user who looks for information in - your documentation. Users do not read technical documentation - for entertainment. Users usually have specific questions. You - need to give clear answers to those questions. - </para> - </section> - <section id="sn-fundamentals-7"> - <title>New Users</title> - <para> - New users to &FC; are likely to consult online tutorials for - guidance about unfamiliar applications or functionality. Each - tutorial should contain enough introductory information to tell - new users how to start using the relevant functions. Each - tutorial should also contain enough usage instructions to tell - users the different actions that they can perform with the - command or function. Keep these instructions task-oriented. Do - not describe GUI screens, dialogs, and dialog elements in a - tutorial, unless there is an unusual feature that affects your - instructions. - </para> - </section> - <section id="sn-fundamentals-8"> - <title>Experienced Users</title> - <para> - Experienced users are more likely to use documentation as a - reference. The documentation therefore needs to be complete, - well-organized, and in the case of printed manuals, - well-indexed. - </para> - </section> - <section id="sn-fundamentals-9"> - <title>Do Not Offend Your Audience</title> - <para> - To avoid offending your readers, apply the following guidelines - to your documentation: - </para> - <variablelist> - <varlistentry> - <term>Avoid insider language</term> - <listitem> - <para> - Insider language includes both undefined jargon and the - tendency of the computer community to shorten words. For - example, use the term <literal>documentation</literal> - instead of the term <literal>docs</literal>. A term may - be jargon if it fails all the following conditions: - </para> - <itemizedlist> - <listitem> - <para> - The term does not appear in the <citetitle>&FED; - Jargon Buster</citetitle> (<ulink - url="http://fedora.redhat.com/docs/jargon-buster/">http://fedora.redhat.com/docs/jargon-buster/</ulink>). - </para> - </listitem> - <listitem> - <para> - The term does not appear in the <citetitle>American - Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/ - </ulink>). - </para> - </listitem> - <listitem> - <para> - The term does not appear in the glossary of the manual - that you are writing. - </para> - </listitem> - <listitem> - <para> - The term is not defined in the body text of the manual - that you are writing. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid gender-specific language</term> - <listitem> - <para> - Pronoun constructions such as <literal>his/her</literal> - or <literal>s/he</literal> do not exist. There is no need - to identify gender in your instructions. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid culture-specific language</term> - <listitem> - <para> - There is little point in giving an example that everyone - in your town knows about, but is a complete mystery to - everyone else in the world. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Avoid talking down to your reader</term> - <listitem> - <para> - There are few experiences more irritating for a user than - documentation that says an action is easy or quick, when - in fact the user cannot complete the action. Do not - qualify or prejudge actions. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Other parts of this guide discuss in more detail tone and - language usage that can cause offense. - </para> - - </section> - - </section> - - <section id="sn-grammar-and-usage"> - - <title>Grammar and Usage Guidelines</title> - - <note> - <title>Bibliographical Information</title> - <para> - This section is drawn partly from the - <citetitle>GDSG</citetitle>, and partly from <citetitle>The - Elements of Style</citetitle>, updated as necessary for the - needs of 21st-century technical documentation writers. - </para> - </note> - - <!-- FIXME: Again, check attribution viz. GNU FDL. This will be more work - than the previous section. --> - - <para> - This section contains an alphabetical list of grammar and usage - guidelines for use in &FED; documentation. Many of these - guidelines are only applicable to English-language usage, refer to - the <citetitle>American Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) - and the <citetitle>Chicago Manual of Style</citetitle> (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) - </para> - <variablelist> - <varlistentry> - <term>Abbreviations</term> - <listitem> - <para> - A shortened form of a word or phrase that takes the place of - the full word or phrase, such as <literal>Dr.</literal>, - <literal>a.m.</literal>, <literal>p.m.</literal>, and so on. - Apply the following rules when you use abbreviations: - </para> - <itemizedlist> - <listitem> - <para> - Avoid creating new abbreviations. Unfamiliar - abbreviations can confuse rather than clarify a concept. - </para> - </listitem> - <listitem> - <para> - Do not explain or expand familiar abbreviations. - </para> - </listitem> - <listitem> - <para> - Do not include familiar abbreviations in the glossary of - your manual. - </para> - </listitem> - </itemizedlist> - <para> - For abbreviations of phrases, such as - <literal>i.e.</literal> for "in other words" and - <literal>e.g.</literal> for "for example", do not use the - abbreviation. Spell out the entire phrase. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Adjectives</term> - <listitem> - <para> - Use adjectives with caution. If an adjective is necessary - to differentiate between items, then use adjectives. In all - cases, test whether the phrase can stand alone without the - adjective. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Acronyms</term> - <listitem> - <para> - A term that represents a multi-word term. Typically, - acronyms are formed in the following ways: - </para> - <itemizedlist> - <listitem> - <para> - From the first letters of each word in a compound term, - for example Table of Contents (TOC). - </para> - </listitem> - <listitem> - <para> - From recognizable parts of a compound term, such as GNU - Object Model Environment (GNOME). - </para> - </listitem> - </itemizedlist> - <para> - Apply the following rules when you use acronyms: - </para> - <itemizedlist> - <listitem> - <para> - On the first occurrence of an acronym, spell out the - full term, with the acronym in parentheses. - </para> - </listitem> - <listitem> - <para> - Do not spell out the full compound for well-known - acronyms, unless you think the information is useful for - readers. - </para> - </listitem> - <listitem> - <para> - Avoid creating new acronyms. Unfamiliar acronyms can - confuse rather than clarify a concept. - </para> - </listitem> - <listitem> - <para> - Write the acronym in uppercase letters, unless there is - a compelling case for lowercase. - </para> - </listitem> - <listitem> - <para> - Include the acronym and the full term in the glossary of - your manual. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Adverbs</term> - <listitem> - <para> - Use adverbs with caution. If an adverb is necessary to - qualify the function of a component, then use an adverb. In - all cases, test whether the phrase can stand alone without - the adverb. Classic superfluous adverbs - <literal>simply</literal>, <literal>easily</literal>, - <literal>quickly</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Anthropomorphism</term> - <listitem> - <itemizedlist> - <listitem> - <para> - Do not apply emotions, desires, or opinions to software - applications. - </para> - </listitem> - <listitem> - <para> - Do not apply a sense of location or dimension to a - software application. A user can not be "in" a text - editor. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Articles</term> - <listitem> - <para> - Do not use the definite article <literal>the</literal> to - begin any of the following items: - </para> - <itemizedlist> - <listitem> - <para> - Manual titles - </para> - </listitem> - <listitem> - <para> - Chapter titles - </para> - </listitem> - <listitem> - <para> - Headings - </para> - </listitem> - <listitem> - <para> - Figure captions - </para> - </listitem> - <listitem> - <para> - Table captions - </para> - </listitem> - <listitem> - <para> - Callouts - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Apostrophe</term> - <listitem> - <para> - Do not use apostrophes except where absolutely required - </para> - <itemizedlist> - <listitem> - <para> - Do not use apostrophes to denote possession. - </para> - </listitem> - <listitem> - <para> - Do not use apostrophes to denote contractions. - </para> - </listitem> - <listitem> - <para> - Do not use apostrophes to denote plurals. - </para> - </listitem> - </itemizedlist> - <example id="ex-apostrophe-wrong"> - <title>Incorrect: Apostrophes</title> - <itemizedlist> - <listitem> - <para> - the <guimenu>Main Menu's</guimenu> - <guimenuitem>Help</guimenuitem> option - </para> - </listitem> - <listitem> - <para> - don't use the default option - </para> - </listitem> - <listitem> - <para> - several SCSI disk's - </para> - </listitem> - </itemizedlist> - </example> - <example id="ex-apostrophe-right"> - <title>Correct: No apostrophes</title> - <itemizedlist> - <listitem> - <para> - the <guimenuitem>Help</guimenuitem> option on the - <guimenu>Main Menu</guimenu> - </para> - </listitem> - <listitem> - <para> - do not use the default option - </para> - </listitem> - <listitem> - <para> - several SCSI disks - </para> - </listitem> - </itemizedlist> - </example> - </listitem> - </varlistentry> - <varlistentry> - <term>Brackets</term> - <listitem> - <itemizedlist> - <listitem> - <para> - Do not use brackets [such as these] as a substitute for - parentheses (such as these). - </para> - </listitem> - <listitem> - <para> - Use brackets for optional command line entries. - </para> - </listitem> - <listitem> - <para> - Do not use angle brackets to indicate variables in text, - instead use the <sgmltag - class="starttag">replaceable</sgmltag> tag. Refer to - <xref linkend="s1-xml-tags-replaceable"/> for - information about using this tag. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Capitalization</term> - <listitem> - <para> - Capitalize in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - All letters in acronyms, unless the acronym is a - well-known exception - </para> - </listitem> - <listitem> - <para> - Initial letter of the first word in a list - </para> - </listitem> - <listitem> - <para> - Initial letter of the first word in a callout - </para> - </listitem> - <listitem> - <para> - Initial letter of a key name, such as the - <keycap>Shift</keycap> key - </para> - </listitem> - <listitem> - <para> - Initial letter of a sentence - </para> - <note> - <title>Command Names</title> - <para> - Avoid starting a sentence with a command name or - application name that has a lowercase initial letter. - </para> - </note> - </listitem> - <listitem> - <para> - Initial letter of a complete sentence after a colon - </para> - </listitem> - </itemizedlist> - <para> - Do not capitalize in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - A compound term that is followed by an abbreviation or - an acronym - </para> - </listitem> - <listitem> - <para> - When you want to emphasize something - </para> - </listitem> - <listitem> - <para> - Variable names - </para> - </listitem> - <listitem> - <para> - The initial letter of an incomplete sentence after a - colon - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Captions</term> - <listitem> - <para> - Use the same rules as for headings, for all captions - accompanying figures and tables. Do not put a period at the - end of a caption. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Colon</term> - <listitem> - <para> - Use a colon in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To introduce a list - </para> - </listitem> - <listitem> - <para> - Before an explanation - </para> - </listitem> - <listitem> - <para> - After an introduction - </para> - </listitem> - </itemizedlist> - <para> - Do not use a colon in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To introduce a figure or a table - </para> - </listitem> - <listitem> - <para> - To introduce headings - </para> - </listitem> - <listitem> - <para> - At the end of an introduction to a procedure - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Column headings</term> - <listitem> - <para> - Use the same rules as for headings. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Comma</term> - <listitem> - <para> - Use commas in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To separate items in a series - </para> - </listitem> - <listitem> - <para> - To separate the parts of a sentence - </para> - </listitem> - <listitem> - <para> - To separate nonrestrictive phrases - </para> - </listitem> - <listitem> - <para> - Instead of dashes to set off appositives - </para> - </listitem> - <listitem> - <para> - With <emphasis>for example</emphasis> and similar - expressions - </para> - </listitem> - </itemizedlist> - <para> - Do not use commas in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - In a series of adjectives used as one modifier - </para> - </listitem> - <listitem> - <para> - Between two short independent clauses - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Commands</term> - <listitem> - <para> - Do not use commands as verbs. - </para> - </listitem> - </varlistentry> - <varlistentry id="vle-contractions"> - <term>Contractions</term> - <listitem> - <para> - Do not use contractions such as <emphasis>can't</emphasis>, - <emphasis>don't</emphasis>, or <emphasis>isn't</emphasis>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Dash</term> - <listitem> - <para> - Do not use the em dash or the en dash. Use a paragraph - break or a colon instead, where you want to create an - introductory piece of text. If you have several items that - you want to introduce, then you can use a variable list. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Ellipsis</term> - <listitem> - <para> - Use an ellipsis in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To show that you have omitted something from a sentence - </para> - </listitem> - <listitem> - <para> - To indicate a pause when you quote displayed text - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Fractions</term> - <listitem> - <para> - Follow these rules when using fractions: - </para> - <itemizedlist> - <listitem> - <para> - Use numerals for fractions in tables and in units of - measurement, but spell out fractions in prose. - </para> - </listitem> - <listitem> - <para> - Use a space between a numeral and a related fraction, if - there is a possible ambiguity. For example: 1 1/2 - instead of 11/2. - </para> - </listitem> - <listitem> - <para> - If a fraction is used in a compound modifier, insert a - hyphen between the fraction and the unit of measurement. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Gender</term> - <listitem> - <para> - Refer to <xref linkend="sn-fundamentals-9"/>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Grammar</term> - <listitem> - <para> - Use standard American English grammar rules, refer to the - <citetitle>Chicago Manual of Style</citetitle> (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html"> - http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Headings</term> - <listitem> - <para> - Use the following capitalization rules in headings: - </para> - <itemizedlist> - <listitem> - <para> - Initial uppercase letter of the first word - </para> - </listitem> - <listitem> - <para> - Initial uppercase letter for all nouns, adjectives, and - verbs. - </para> - </listitem> - <listitem> - <para> - All lowercase letters for conjunctions, articles, and - prepositions of fewer than four letters - </para> - </listitem> - <listitem> - <para> - Initial uppercase letter for prepositions of four - letters or longer - </para> - </listitem> - <listitem> - <para> - Initial uppercase letter for conjunctions of four - letters or longer - </para> - </listitem> - </itemizedlist> - <!-- <para> See <xref linkend="infodesign-2"/> for more - information about headings. </para> --> - </listitem> - </varlistentry> - <varlistentry> - <term>Hyphen</term> - <listitem> - <para> - Use hyphens in the following situations: - </para> - <itemizedlist> - <listitem> - <para> With a numeral in a compound modifier - </para> - </listitem> - <listitem> - <para> - To prevent ambiguity - </para> - </listitem> - <listitem> - <para> - With some standard prefixes and suffixes. Use the - <citetitle>American Heritage Dictionary</citetitle> - (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) - for guidance - </para> - </listitem> - <listitem> - <para> - In spelled-out fractions - </para> - </listitem> - <listitem> - <para> - In variable names of two or more words, such as - <replaceable>directory-name</replaceable>. Note: - <replaceable>filename</replaceable> is an exception. - </para> - </listitem> - </itemizedlist> - <para> - Do not use hyphens in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - For industry-accepted terms - </para> - </listitem> - <listitem> - <para> - To construct verbs - </para> - </listitem> - <listitem> - <para> - With an adverb ending in <emphasis>ly</emphasis> - </para> - </listitem> - <listitem> - <para> - With numerals as single modifiers - </para> - </listitem> - <listitem> - <para> - With a word that is listed as unhyphenated in the - <citetitle>American Heritage Dictionary</citetitle> - (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>), - and that uses a common prefix - </para> - </listitem> - <listitem> - <para> - With trademarked terms - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Latin terms</term> - <listitem> - <para> - Do not use Latin terms. Use an equivalent English term - instead. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Like</term> - <listitem> - <para> - Do not use the term <emphasis>like</emphasis> to denote - equivalence or similarity. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Lists</term> - <listitem> - <para> - Introduce a list with a complete sentence that ends with a - colon. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Numbers</term> - <listitem> - <para> - Spell out numbers in the following situations: - </para> - <itemizedlist> - <listitem> - <para> Numbers from zero through nine unless the number is - part of a measurement - </para> - </listitem> - <listitem> - <para> - Approximations - </para> - </listitem> - <listitem> - <para> - Extreme values such as <emphasis>million</emphasis>, but - precede the value with a numeral - </para> - </listitem> - <listitem> - <para> - Any number that begins a sentence - </para> - </listitem> - <listitem> - <para> - A number that is immediately followed by a numeral, for - example: <literal>two 10 MB files</literal> - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Numerals</term> - <listitem> - <para> - Use numerals in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - The number 10 or greater - </para> - </listitem> - <listitem> - <para> Negative numbers - </para> - </listitem> - <listitem> - <para> - Most fractions - </para> - </listitem> - <listitem> - <para> - Percentages - </para> - </listitem> - <listitem> - <para> - Decimals - </para> - </listitem> - <listitem> - <para> - Measurements - </para> - </listitem> - <listitem> - <para> - Units of time smaller than one second - </para> - </listitem> - <listitem> - <para> - References to bits and bytes - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Parentheses</term> - <listitem> - <para> - Use parentheses in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To contain the abbreviation of a term on the first - occurrence of the full term - </para> - </listitem> - <listitem> - <para> - In man page references, specifically the section number - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Period</term> - <listitem> - <para> - Use a period in the following situations: - </para> - <itemizedlist> - <listitem> - <para> - To end a sentence - </para> - </listitem> - <listitem> - <para> - In file and directory names - </para> - </listitem> - <listitem> - <para> - In abbreviations that can be mistaken for words, such as - a.m. and U.S. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term>Punctuation</term> - <listitem> - <para> - Use standard American English punctuation rules. In - addition to the specific points of punctuation in this - section, refer also to the <citetitle>Chicago Manual of - Style</citetitle> (<ulink - url="http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html">http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html</ulink>.) - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Punctuation in numbers</term> - <listitem> - <para> - Do not use a comma in numerals of four digits. Use a comma - in numerals of more than four digits. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Quotation marks</term> - <listitem> - <para> - Use quotation marks to indicate material that is taken - verbatim from another source. Do not use quotation marks to - excuse terms from legitimacy. If the term is not - legitimate, then use another term. If you must use that - term, declare the term in the glossary and make the term - legitimate. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>See v. Refer to</term> - <listitem> - <para> - When referring a user to another resource, use "refer to" - instead of "see", and "refer also to" instead of "see also". - This differentiates from the <sgmltag - class="starttag">see</sgmltag> and <sgmltag - class="starttag">seealso</sgmltag> tags that are used in - indexing. These tags create special links in the index. To - be consistent throughout the document, we reserve the - special words "see" and "see also" for hyperlinked index - references, and use "refer to" and "refer also to" for - non-hyperlinked and non-indexed references. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Semicolon</term> - <listitem> - <para> - Do not use semicolons. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Slash</term> - <listitem> - <para> - Except where required as part of a filename, do not use - slashes "/" in your writing. The construction - <literal>and/or</literal>, for example, does not exist. Use - one or the other term instead. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Spelling</term> - <listitem> - <para> - Use standard American English spelling rules, refer to the - <citetitle>American Heritage Dictionary</citetitle> (<ulink - url="http://www.bartleby.com/61/">http://www.bartleby.com/61/</ulink>) - for guidelines. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Titles</term> - <listitem> - <para> - For manual titles use the same rules as for headings. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Units</term> - <listitem> - <para> - Follow these rules when using units: - </para> - <itemizedlist> - <listitem> - <para> - Use standard abbreviations for units of measurements, do - not invent your own abbreviations. - </para> - </listitem> - <listitem> - <para> - <!-- See <xref linkend="units"/> for a list of units - relevant to the GNOME Desktop. --> For further - guidelines, refer to the <citetitle>IEEE Standard - Dictionary of Electrical and Electronics - Terms</citetitle>. - </para> - </listitem> - <listitem> - <para> - Use periods for abbreviated units that might be mistaken - for a word. - </para> - </listitem> - <listitem> - <para> - Most standard abbreviations of units account for both - singular and plural usage. - </para> - </listitem> - <listitem> - <para> - Insert a space between the numeral and the unit of - measurement. - </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="sn-composition-tips"> - - <title>Composition Tips</title> - -<!-- - - This section will collect miscellanea and advice for specific - situations that the FDP editors encounter. I hope they will feel - free to e-mail me sticky situations or particularly interesting - examples of work they've beautified. Hopefully not too much will be - drawn from my own work! - PWF. - ---> - - <para> - This section contains usage tips based on situations the &FDP; - editors have encountered in the past. You should read and - understand these examples to improve your own documentation. The - &FDP; editors welcome additional examples. - </para> - - <section id="sn-misc-active-voice"> - <title>Active Voice</title> - <para> - Always use active voice, except when it is awkward to do so. The - tutorial tells the user how to accomplish a task, and should - give instructions clearly and concisely. Avoid using "must," - "need to," and the like. These words are redundant in a - tutorial, since the reader assumes you are outlining necessary - steps to accomplish a task. Also avoid using "maybe," "might," - and other words that indicate you are unsure about the subject - matter. Your tutorial should cover a subject authoritatively. - The reader should never be concerned about unknown effects of - following the tutorial. - </para> - <example id="ex-misc-passive-voice"> - <title>Incorrect: Passive voice</title> - <para> - The <command>yum update</command> command must be run. - </para> - <para> - You might want to run the <command>yum update</command> - command. - </para> - </example> - <example id="ex-misc-active-voice"> - <title>Correct: Active voice</title> - <para> - Run the <command>yum update</command> command. - </para> - </example> - </section> - - <section id="sn-present-tense"> - <title>Present Tense</title> - <para> - Write in the present tense. A good rule of thumb is that the - words "will" and "shall" are almost never needed in describing - what the user should do or see. They add unnecessary length to - sentences and can confuse translators. They are also often - indicators of passive voice; refer also to <xref - linkend="sn-misc-active-voice"/>. - </para> - <example id="ex-misc-future-tense"> - <title>Incorrect: Future tense</title> - <para> - The application will display a list of target files. - </para> - <para> - A list of target files will be displayed by the application. - </para> - </example> - <example id="ex-misc-present-tense"> - <title>Correct: Present tense</title> - <para> - The application displays a list of target files. - </para> - </example> - </section> - - <section id="sn-narrative-voice"> - <title>Narrative Voice</title> - <para> - Do not use the first person "I," "we," or "us" to refer to - yourself the writer (whether including the reader or not), the - &FDP;, the &FED; community, or any other group. Do not refer to - users with a third person pronoun ("he," "she," or "he or she") - or the word "one." It is acceptable to refer to the reader with - the second person pronoun "you." - </para> - <example id="ex-misc-wrong-person"> - <title>Incorrect: First or third person</title> - <para> - As described in the last section, I always run - <command>up2date</command> before configuring the Samba - server. - </para> - <para> - If the user needs to back up his or her files, s/he should use - the <command>tar</command> or <command>cpio</command> command. - </para> - </example> - <example id="ex-misc-correct-person"> - <title>Correct: Second (or no) person</title> - <para> - Refer to the section on <command>up2date</command> before - configuring the Samba server. - </para> - <para> - If necessary, users can back up files with the - <command>tar</command> or <command>cpio</command> command. - </para> - </example> - </section> - - <section id="sn-misc-negative"> - <title>Negative Words</title> - <para> - Avoid negative words when possible, since they give - documentation an overly dogmatic tone. The word "avoid" is - useful for this purpose. Note that contractions are often used - for negative words such as <emphasis>don't</emphasis> or - <emphasis>can't</emphasis>. Refer to <xref - linkend="vle-contractions" />. - </para> - </section> - - <section id="sn-misc-uncertainty"> - <title>Uncertainty</title> - <para> - Avoid overuse of "typically," "usually," "most of," "many," and - the like. While occasional use of these constructions is - acceptable, overuse reduces the authority of your documentation. - The documentation should adequately cover a stock installation - of &FC;. It is impossible for a tutorial-length document to - cover every possible configuration scenario. Address the most - common scenarios and note discrepancies only as required. - </para> - </section> - - <section id="sn-misc-offtopic"> - <title>Redundant Coverage</title> - <para> - Avoid covering redundant material, such as how to update a &FC; - system. These overarching topics may be covered in other - tutorials. Writers frequently violate this guideline because - they feel their tutorial is not long enough. Keep your tutorial - from wandering off-topic. Instead, refer the reader to a - separate tutorial whenever possible for complete coverage of - that topic. - </para> - </section> - - <section id="sn-misc-importance"> - <title>Self-referential Value Judgments</title> - <para> - Avoid statements such as "One of the most important things to do - is <replaceable>XYZ</replaceable>." If the procedure is - important, the reader already expects it to be in your tutorial. - The converse is also true: If a procedure appears in your - tutorial, the reader expects it is important. This is - especially true if you use a whole section for the procedure in - question. Merely state, "Do <replaceable>XYZ</replaceable>." - Then elaborate as required. If the whole section concerns how - to do <replaceable>XYZ</replaceable>, leave this sentence out - entirely. Refer also to <xref linkend="vle-golden-rule-4" />. - </para> - </section> - - <section id="sn-misc-precision"> - <title>Precision of Language</title> - <para> - Use precise words for actions users should take. Do not - instruct users to "go" to a selection, or "find" a menu. - </para> - <example id="ex-precision-wrong"> - <title>Incorrect: Imprecise wording</title> - <itemizedlist> - <listitem> - <para> - Go to the <guimenu>Main Menu</guimenu> -> - <guimenuitem>Foobar</guimenuitem> - </para> - </listitem> - <listitem> - <para> - Find the option labeled <guilabel>Search</guilabel> - </para> - </listitem> - </itemizedlist> - </example> - <example id="ex-precision-right"> - <title>Correct: Precise wording</title> - <itemizedlist> - <listitem> - <para> - From the <guimenu>Main Menu</guimenu>, select - <guimenuitem>Foobar</guimenuitem> - </para> - </listitem> - <listitem> - <para> - Select the <guilabel>Search</guilabel> option - </para> - </listitem> - </itemizedlist> - </example> - <important> - <title>Do Not Discriminate Against Non-GUI Users</title> - <para> - If you are writing about a GUI-only application, you may use - "click" freely. If you are writing about an application that - has a text-mode interface, use "select" instead as shown - above. - </para> - </important> - - </section> - - <section id="sn-misc-docbook-tips"> - <title>DocBook Tips</title> - <para> - This section contains tips on how to use DocBook tags more - effectively in your documentation. - </para> - - <section id="sn-misc-admonitions"> - <title>Admonitions</title> - <para> - Avoid overuse of admonitions. Keep admonitions short and - effective by using only the most important material inside the - admonition. Move any background material required to explain - the admonition statements outside the admonition. Use a short - but descriptive title for an admonition. Use title case for - the admonition title. - </para> - <example id="ex-misc-ineffective-admonition"> - <title>Incorrect: Lengthy admonition</title> - <para> - <warning> - <title>Use <command>sfdisk</command> to check input</title> - <para> - The <command>sfdisk</command> command accepts a script - file as standard input to set up partitions on a hard - disk. Sometimes <command>sfdisk</command> will simply - reject an erroneous input file. In other cases, it will - use the input verbatim, writing an incorrect partition - table to your disk. Always use the <command>sfdisk - -n</command> command to check your input file before - writing to the disk. - </para> - </warning> - </para> - </example> - <example id="ex-misc-good-admonition"> - <title>Correct: Brief admonition</title> - <para> - The <command>sfdisk</command> command accepts a script - file as standard input to set up partitions on a hard disk. - Sometimes <command>sfdisk</command> will simply reject an - erroneous input file. In other cases, it will use the input - verbatim, writing an incorrect partition table to your disk. - <warning> - <title>Check Input</title> - <para> - Always use the <command>sfdisk -n</command> command to - check your input file before writing to the disk. - </para> - </warning> - </para> - </example> - <para> - Avoid punctuation in titles for sections or admonitions, - except for commas only where demanded. Use a title that says - something about the admonition comment, such as "Reboot - Required," instead of simply using the admonition type for a - title ("Note"). - </para> - <para> - Follow the capitalization rules for headings in the title of - an admonition. - </para> - </section> - - <section id="sn-misc-replaceable"> - <title>The <sgmltag class="starttag">replaceable</sgmltag> - Tag</title> - <para> - If your documentation formally states a specific value will be - used as a convention, do not use the <sgmltag - class="starttag">replaceable</sgmltag> tag in your text or - examples. - </para> - </section> - - <section id="sn-misc-entities"> - <title>XML Entities</title> - <para> - Use the entities provided by the &FDP;. These entities are - found in the <filename>common/</filename> folder in the - <filename>fedora-docs</filename> distribution. (Refer also to - <xref linkend="ch-getting-files"/>.) For instance, do not use - abbreviations such as "FC2." Instead, use the predefined - entities "&FC; &FCVER;," which produces the text "&FC; - &FCVER;." - </para> - </section> - - </section> - - </section> - -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: xml -sgml-parent-document:("documentation-guide-en.xml" "book" "chapter") -fill-column: 72 -End: ---> diff --git a/docs-tutorial-en.xml b/docs-tutorial-en.xml deleted file mode 100644 index d748721..0000000 --- a/docs-tutorial-en.xml +++ /dev/null @@ -1,99 +0,0 @@ -<!-- $Id: docs-tutorial-en.xml,v 1.8 2005/12/28 00:40:27 pfrields 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, a link to the entities file that contain common entities that should - be used, and an entity to change the version and date of the tutorial. - </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 XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - -<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml"> -%FEDORA-ENTITIES-EN; - -<!ENTITY VERSION "0.1"> <!-- change version of tutorial here --> - -<!ENTITY DOCID "example-tutorial-&VERSION; (2003-07-07)"> <!-- change last modified date here --> - -<!ENTITY LEGALNOTICE SYSTEM "../common/legalnotice-en.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> - -<index id="generated-index"></index> -</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-vim-en.xml b/docs-vim-en.xml deleted file mode 100644 index e5bb9b4..0000000 --- a/docs-vim-en.xml +++ /dev/null @@ -1,147 +0,0 @@ -<!-- $Id: docs-vim-en.xml,v 1.2 2005/12/23 22:57:30 pfrields Exp $ --> - - <chapter id="ch-vim"> - <title>VIM and DocBook</title> - - <indexterm> - <primary>VIM</primary> - </indexterm> - - <para> - VIM has many features to help you write XML content such as DocBook, - including syntax highlighting and customizable key bindings. - Additionally, one can easily use external programs from VIM for features - such as spell-checking. - This chapter assumes you already know generally how to use VIM; if you - want to learn how, try the <command>vimtutor</command> or by typing - <userinput>:help tutor</userinput> from inside VIM. - </para> - - <sect1 id="s1-vimrc-file"> - <title>Setting Up Your <filename>.vimrc</filename> File</title> - - <indexterm> - <primary>VIM</primary> - <secondary>configuration file</secondary> - </indexterm> - - <para> - Below is a short sample <filename>.vimrc</filename> file that turns on - some VIM features useful for editing SGML or XML content such as - DocBook: -<screen> -<computeroutput>" Turn off vi compatibility settings like limited undo -set nocompatible -" Syntax highlighting based on file extension -syntax on -" Automatically insert newlines after 80 characters -set textwidth=80 -" Automatically indent -set autoindent -" Match SGML tags with % -source $VIMRUNTIME/macros/matchit.vim</computeroutput> -</screen> - </para> - <note> - <para> - Some of these features require the <filename>vim-enhanced</filename> - package to be installed. If you are using or the - <filename>vim-minimal</filename> package, or if you are using an older - version of VIM, you may not have the - <filename>$VIMRUNTIME/macros/matchit.vim</filename> file. You can still - download <ulink - url="http://vim.org/scripts/script.php?script_id=39">matchit.zip from - Vim.org</ulink> and load it separately. - </para> - </note> - </sect1> - - <sect1 id="s1-vim-keymapping"> - <title>Keymapping with VIM</title> - - <para> - VIM can speed up your DocBook creation by mapping frequently typed tags - (or any words or phrases) onto short key combinations. By default, the - keymap leader is the backslash (<literal>\</literal>), but it can be - redefined with a command like <userinput>let mapleader = - ","</userinput>. There are two ways to use the following example; - you can put it directly in your <filename>.vimrc</filename>, or you - can save it in a separate file and load it with a - <userinput>source</userinput> command in your - <filename>.vimrc</filename>. -<screen> -<![CDATA[let mapleader = "," - -" skip ahead to after next tag without leaving insert mode -imap <leader>e <esc>/><cr>:nohlsearch<cr>a - -" common tags that start a new text block -imap<leader>pa <para><cr></para><esc>O -imap<leader>s1 <sect1 id=""><cr><para><esc>jo</sect1><esc>O -imap<leader>pl <programlisting><cr></programlisting><esc>O<esc>0i -imap<leader>cp <computeroutput></computeroutput><esc>O<esc>0i - -" common tags that are placed inline -" use <esc>F>a -imap<leader>en <envar></envar><esc>F>a -imap<leader>fi <filename></filename><esc>F>a -imap<leader>lt <literal></literal><esc>F>a -imap<leader>re <replaceable></replaceable><esc>F>a -imap<leader>ui <userinput></userinput><esc>F>a -imap<leader>ul <ulink url=""></ulink><esc>F>a -imap<leader>si <systemitem></systemitem><esc>F>a -imap<leader>us <systemitem class="username"></systemitem><esc>F>a -imap<leader>sy <systemitem class="systemname"></systemitem><esc>F>a -imap<leader>cm <command></command><esc>F>a -" entities -imap <leader>> > -imap <leader>< <]]> -</screen> - </para> - <para> - Unfortunately, there is not currently a complete macro set for all - DocBook commands, so you will need to define them yourself or customize - the definitions in the examples from <xref - linkend="s1-vim-additional-resources"></xref>. - </para> - </sect1> - - <sect1 id="s1-vim-additional-resources"> - <title>Additional VIM Resources</title> - - <para> - Additional information about VIM may be found from: - </para> - - <itemizedlist> - <listitem> - <para><ulink url= - "http://newbiedoc.sourceforge.net/text_editing/vim.html#JESSE-SGMLRC"> - Example sgml-vimrc</ulink> from the <citetitle>Beginner's guide to - Vi Improved (VIM)</citetitle> - </para> - </listitem> - <listitem> - <para>The <ulink url="http://tnerual.eriogerg.free.fr/vim.html">VIM - Quick Reference Card</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="http://www.pinkjuice.com/howto/vimxml/">Vim as XML - Editor</ulink> - </para> - </listitem> - <listitem> - <para> - The <citetitle>VIM REFERENCE MANUAL</citetitle>, which comes with - the <filename>vim-common</filename> package — - <filename>/usr/share/vim/<replaceable><version></replaceable>/doc/intro.txt</filename> - or type <userinput>:help intro</userinput> from within VIM - </para> - </listitem> - - </itemizedlist> - - </sect1> - </chapter> diff --git a/docs-xml-tags-en.xml b/docs-xml-tags-en.xml deleted file mode 100644 index 91e58cc..0000000 --- a/docs-xml-tags-en.xml +++ /dev/null @@ -1,2491 +0,0 @@ -<!-- $Id: docs-xml-tags-en.xml,v 1.12 2004/09/30 14:25:36 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.12 2004/09/30 14:25:36 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 -<filename>system-config-keyboard</filename> 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 &FC; is no exception. -</computeroutput> -</screen> - - <para> - The output: - </para> - - <para> - Nearly every modern-day operating system uses <firstterm>disk - partitions</firstterm>, and &FC; 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> - <phrase> - Some text description of this image - </phrase> - </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> - -<phrase>Some text description of this image</phrase> <emphasis>==> "Some text..." would be edited</emphasis> -</screen> - - <para> - For more information on taking screenshots, refer to <xref - linkend="s1-screenshots"/>. - </para> - - </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> - - <para>How does the index get generated? If indexterms exist in the - document and the beginning and ending index tags exist before the end - tag for the book or article, an index is created because of the - <command>generate.index</command> stylesheet parameter, which is set to - true by default. - </para> - - </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> - - <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> - - </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 &FC;.</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 not 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, use the tags - <command><replaceable></command> and - <command></replaceable></command> around the text you want to use as a - variable. - </para> - <para> - This example demonstrates how to use the <command>replaceable</command> - tags when referencing the name of an RPM file: - </para> -<screen> -foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm -</screen> - - <para> - The output: - </para> - -<screen> -foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm -</screen> - </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 with the Fedora CSS file, this - appears in box with 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> - The <command><screen></command> tag set may contain other inline - tags, such as <command><computeroutput></command>, - <command><userinput></command>, or - <command><replaceable></command>. Additional inline tags are not - required by definition. The <command><screen></command> tags by - themselves may provide sufficient context, especially for simple examples - or file listings. Consider the context of the example, and use inline tags - if they are helpful to the reader. - </para> - - <para> - If you use inline tags, remember that line breaks inside - <command><screen></command> tags create line breaks in any rendered - output. Place any inline tags <emphasis>on the same line</emphasis> as - their content. Do not overuse tagging within a - <command><screen></command> tag set. - </para> - - <para> - An example of <command><screen></command> is the following: - </para> - -<screen> -<computeroutput><screen> -This is an example of a screen. You do not need &lt;para&gt; tags -within this command. -</screen></computeroutput> -</screen> - - <para> - The output: - </para> - -<screen> -This is an example of a screen. You do not need <para> tags -within this command. -</screen> - - <sect2 id="s2-xml-tags-screen-inline-tags"> - <title>Using Inline Tags with <command>screen</command></title> - <para> - If you choose to use inline tags inside a - <command><screen></command> section, follow these guidelines for - consistency. If the content in the screen is a listing of a - configuration file or the output of a program, use the - <command><computeroutput></command> tag set around the entire - output. If the user should type the example on the command line or in - a configuration file, use the <command><userinput></command> tag - set. Separate input and output with a short sentence of narrative, as - below: - </para> - -<screen> - <command><para></command> - Type the following command: - <command></para></command> - -<command><screen></command> -<command><userinput></command>command -sw file1<command></userinput></command> -<command></screen></command> - - <command><para></command> - You should see the following output: - <command></para></command> - -<command><screen></command> -<command><computeroutput></command>Completed, time = 0.12 sec<command></computeroutput></command> -<command></screen></command> -</screen> - - <para> - The output looks like: - </para> - - <para> - Type the following command: - </para> - -<screen> -<userinput>command -sw file1</userinput> -</screen> - - <para> - You should see the following output: - </para> - -<screen> -<computeroutput>Completed, time = 0.12 sec</computeroutput> -</screen> - - <note> - <title>Note</title> - <para> - When showing a command or series of commands inside - <command>screen</command> tags, do not show the prompt. - </para> - </note> - - <para> - If the <command><screen></command> shows the reader how to - change only <emphasis>part</emphasis> of a line, mark the change with - an inline <command><userinput></command> tag set. You may use - the <command><userinput></command> tag set inside a larger area - that is already marked inline with - <command><computeroutput></command>. Do not include any extra - lines of context in this case, unless excluding them would confuse the - reader. The following example illustrates these guidelines: - </para> - -<screen> - <command><para></command> - Edit the <command><filename></command>/etc/sysconfig/init<command></filename></command> file as follows: - <command></para></command> - -<command><screen></command> -GRAPHICAL=<command><userinput></command>yes<command></userinput></command> -<command></screen></command> -</screen> - - <para> - The output looks like: - </para> - - <para> - Edit the <filename>/etc/sysconfig/init</filename> file as follows: - </para> - -<screen> -GRAPHICAL=<userinput>yes</userinput> -</screen> - - <para> - For an explanation of how to use the <command>replaceable</command> - tags within a set of <command>screen</command> tags, refer to <xref - linkend="s1-xml-tags-replaceable"></xref>. - </para> - - </sect2> - </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> |