From 2978c374a745e38b0c300d15d3bbe2648d3a8c64 Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Thu, 23 Nov 2006 20:32:31 +0000 Subject: Remove old files in en locale --- acknowledgments-en.xml | 45 - docs-emacs-en.xml | 727 ------------- docs-emacs-nxml-en.xml | 339 ------ docs-getting-files-en.xml | 402 -------- docs-intro-en.xml | 43 - docs-rh-guidelines-en.xml | 586 ----------- docs-style-en.xml | 1965 ----------------------------------- docs-tutorial-en.xml | 99 -- docs-vim-en.xml | 147 --- docs-xml-tags-en.xml | 2491 --------------------------------------------- 10 files changed, 6844 deletions(-) delete mode 100644 acknowledgments-en.xml delete mode 100644 docs-emacs-en.xml delete mode 100644 docs-emacs-nxml-en.xml delete mode 100644 docs-getting-files-en.xml delete mode 100644 docs-intro-en.xml delete mode 100644 docs-rh-guidelines-en.xml delete mode 100644 docs-style-en.xml delete mode 100644 docs-tutorial-en.xml delete mode 100644 docs-vim-en.xml delete mode 100644 docs-xml-tags-en.xml 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 @@ - - Acknowledgments - - - 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). - - - - 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. - - - - Patches from Gavin Henry (ghenry at suretecsystems.com) have been applied - to add the trailing slashes to the figure tag example - in docs-xml-tags.xml and to add . - - - - A patch from Joshua Daniel Franklin (joshuadfranklin at yahoo.com) has been - applied to add . - - - - A patch from Karsten Wade (kwade at redhat.com) has been applied to add - . It was edited by Paul - W. Frields (stickstr5 at hotmail.com). - - - - A patch from Paul W. Frields (stickstr5 at hotmail.com) has been applied - to add more explanation of the screen tag set to . - - - - A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been - applied to more fully explaing the document building system. - - - 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 @@ - - - - Emacs and PSGML Mode - - - PSGML - - - - Emacs - - - - Emacs - PSGML mode - - - - You can use the PSGML mode available for Emacs to make it easier to write - in XML format. PSGML mode provides syntax-highlighting, tag completion, - and more. - - - - Setting Up Your <filename>.emacs</filename> File - - - Emacs - configuration file - - - - .emacs - - - - For Emacs to parse your DocBook documents correctly, you must have a - .emacs file. Cut and paste the following into your - existing .emacs file or create a new one that - contains the following lines: - - - -;; turn on auto-fill in `text-mode' and derived modes -;;(mail, news, etc) -(add-hook 'text-mode-hook 'turn-on-auto-fill) - -;; -;;MODES -;; - -(setq auto-mode-alist (cons '("\\.sgml$" . sgml-mode) auto-mode-alist)) -(setq auto-mode-alist (cons '("\\.sgm$" . sgml-mode) auto-mode-alist)) - -;; -;;XML!! -;; -;;############################################################# - -;; -;;PSGML mode stuff -;; - -(autoload 'sgml-mode "psgml" "My Most Major Mode" t) - -(setq sgml-mode-hook '(lambda () "Defaults for XML mode." (turn-on-auto-fill) -(setq fill-column 80))) - -(defun My-XML-keymap () - (local-set-key [(alt i)] - '(lambda () - (interactive) - (sgml-indent-line) - (sgml-insert-element 'item) - (sgml-indent-line))) - (local-set-key [(alt l)] - '(lambda () - (interactive) - (sgml-insert-element 'list) - (sgml-insert-element 'item) - (sgml-indent-line))) - (local-set-key [(alt p)] - '(lambda () - (interactive) - (sgml-indent-line) - (sgml-insert-element 'para) - (sgml-indent-line))) - (local-set-key [(alt -)] - '(lambda () - (interactive) - (insert "—")))) - -(add-hook 'sgml-mode-hook 'My-XML-keymap) - -;; -;; Fix up indentation of data... -;; - -(setq-default sgml-indent-data t) - -;; -;; XML markup faces. -;; - -(setq-default sgml-set-face t) - - -(make-face 'sgml-comment-face) -(make-face 'sgml-doctype-face) -(make-face 'sgml-end-tag-face) -(make-face 'sgml-entity-face) -(make-face 'sgml-ignored-face) -(make-face 'sgml-ms-end-face) -(make-face 'sgml-ms-start-face) -(make-face 'sgml-pi-face) -(make-face 'sgml-sgml-face) -(make-face 'sgml-short-ref-face) -(make-face 'sgml-start-tag-face) - -(set-face-foreground 'sgml-comment-face "maroon") -(set-face-foreground 'sgml-doctype-face "dark green") -(set-face-foreground 'sgml-end-tag-face "blue2") -(set-face-foreground 'sgml-entity-face "red2") -(set-face-foreground 'sgml-ignored-face "maroon") -(set-face-background 'sgml-ignored-face "gray90") -(set-face-foreground 'sgml-ms-end-face "maroon") -(set-face-foreground 'sgml-ms-start-face "maroon") -(set-face-foreground 'sgml-pi-face "maroon") -(set-face-foreground 'sgml-sgml-face "maroon") -(set-face-foreground 'sgml-short-ref-face "goldenrod") -(set-face-foreground 'sgml-start-tag-face "blue2") - -(setq-default sgml-markup-faces - '((comment . sgml-comment-face) - (doctype . sgml-doctype-face) - (end-tag . sgml-end-tag-face) - (entity . sgml-entity-face) - (ignored . sgml-ignored-face) - (ms-end . sgml-ms-end-face) - (ms-start . sgml-ms-start-face) - (pi . sgml-pi-face) - (sgml . sgml-sgml-face) - (short-ref . sgml-short-ref-face) - (start-tag . sgml-start-tag-face))) - - -(defun docbook-mode () - (sgml-mode) - ) - - - -;; -;;END XML STUFF -;; -;;################################################################## - -;PO mode stuff - -(setq auto-mode-alist - (cons '("\\.pox?\\'" . po-mode) auto-mode-alist)) -(autoload 'po-mode "po-mode") - - - (global-set-key [(f1)] (lambda () (interactive) (manual- - entry (current-word)))) - - - - - - - - Do you have a cool wheel mouse? If so, you can add the following to your - .emacs file so your wheel will work in - Emacs (must be - Emacs version 21): - - - - -;; Enable wheelmouse support by default for emacs 21 -(cond (window-system -(mwheel-install) -)) - - - - - If you are using the older version 20 of - Emacs, add the following instead: - - - - -;; Enable wheelmouse support by default -(require 'mwheel) - - - - - - - - - - Customizing Emacs - - - Emacs - customizing - - - - .Xresources - - - - Emacs - colors - - - - Emacs - font - - - - Emacs - geometry - - - - The colors, font, and geometry (default size of window) for Emacs in your - ~/.Xresources file. The format for the settings is - emacs.keyword:value - - - - The following is a sample ~/.Xresources file. - - - Note - If you have other settings in your - ~/.Xresources, add the following to the end of - the file. - - - - - -emacs.background: light gray -emacs.foreground: black -emacs.pointerColor: blue -emacs.cursorColor: blue -emacs.bitmapIcon: on -emacs.font: fixed -emacs.geometry: 90x25 - - - - After modifying this file, you must execute the command - - -xrdb -merge ~/.Xresources - - - and restart Emacs for the changes to take - place. - - - - - - Create Recompiled DTD Subset - - - Emacs will perform syntax highlighting and indent correctly on - DocBook XML files if you provide it with the proper Document Type - Declarations (DTD) file. These two features will make your XML file - look pretty and help you spot errors. - - - - To create a loadable Parsed DTD file: - - - Find the parent file for the group of DocBook files. You will - recognize this file by the header <!DOCTYPE article - PUBLIC "-//OASIS//DTD DocBook V4.1//EN". An easy way - to find this parent file is to use the command grep - DocBook *.xml. Once you find the parent file, open it - in Emacs with the command emacs - <parentfile>.xml (where - <parentfile>.xml is the parent - file you found. - - - - - Choose DTD -> Parse DTD from the pulldown - menu. - - - - - You will know the parsing is finished when you see the message - Fontifying...done at the bottom - of your screen. Save the parsed DTD to a file by choosing - DTD -> Save Parsed DTD from the pulldown menu. - - - - - Press Enter to save the file to the default - filename or rename the file keeping the .ced - extension. It can be useful to name it something generic such as - docbook.ced so you can refer to it when - opening all DocBook files. This file can also be copied from - directory to directory to be loaded. - - - - - - - - Tip - - You can also use the Emacs command Meta-x - sgml-parse-prolog to parse the file, and then use the - command Meta-x sgml-save-dtd to save the parsed DTD - to a .ced file. - - - - - - - Load the Parsed DTD - - - Now that you have saved the DTD settings, you can load the - .ced file and see the syntax highlighting for your - .sgml files. - - - - To load a parsed DTD file: - - - Open an XML file in Emacs. - - - - - Choose DTD -> Load DTD from the pulldown menu - and choose the file you saved from the previous step. For - instance, choose docbook.ced. - - - - - You will know it is finished when you see the message - Fontifying...done at the bottom - of your screen. Loading the parsed DTD might take a long time. - You can start editing the file before it finishes. - - - - - - - - - Tip - - You can also use the Emacs command Meta-x - sgml-load-dtd to load the parsed DTD. - - - - - - - Basic Emacs Commands - - - The Meta key is usually the Alt key. - - - - Emacs Commands - - - - - - - Shortcut - Description - - - - - - Metax - sgml-parse-prolog, Enter - Parse DTD - - - Metax - sgml-save-dtd, Enter - Save the Parse DTD - - - Metax - sgml-load-dtd, Enter - Load DTD - - - Ctrl c - , Shift - , Tab - Display list of valid tags - - - Ctrl c - , Shift - , type beginning of tag, - Tab - Complete the tag - - - Ctrl g - - Cancel a command in the minibuffer - - - Ctrl c - , / - Close tag - - - Ctrl a - - Move cursor to beginning of line - - - Ctrle - - Move cursor to the end of the line - - - CtrlHome - - Move cursor to the beginning of the file - - - CtrlEnd - - Move cursor to the end of the file - - - Ctrlk - - Cut line - - - Ctrl y - - Paste line - - - Ctrl s - - Search forward in the file - - - Ctrlr - - Search backwards in the file - - - Meta$ - - Check spelling of current word - - - Metax - ispell-word, Enter - Check spelling of current word - - - Metax - ispell-buffer, Enter - Check spelling of current buffer - - - Ctrlx - , Ctrlf - - Open file - - - Ctrlx - , Ctrls - - Save file - - - Ctrlx - , Ctrlc - - Exit Emacs and prompt to save - files if necessary - - - Meta q - - Fill paragraph - - - Ctrlc - , Ctrla - - Edit attributes for a tag (for example, you can edit the - url attribute of the - ulink tag) - - - Ctrl c - , - Ctrlc - - Exit edit attributes - - - -
- - - - - Examples - - - The table or reference card of Emacs and PSGML commands can be confusing - for beginners. This section provides some examples of how to use them. - - - - Tag Completion - - - Note - This section assumes that you have already loaded the DTD file - (.ced). - - - - - Instead of typing a tag each time you need to use it, use - the key combination Ctrl-c, - followed by <. At the bottom of the - Emacs window, you will see: - - -Tag: < - - - - To view a list of available tags, use either the Tab - or ?. Or, if you know the first few letters of a tag, - you can enter them followed by Tab for a complete - list of available tags beginning with those letters or for a tag - completion. - - - - Try the following: Type Ctrl-c - followed by <. Then enter the letter - k, followed by Tab. You may have to - use the Tab key several times to get a complete list. - - - - The output should look similar to the example below: - - - - -Click mouse-2 on a completion to select it. -In this buffer, type RET to select the completion near point. - -Possible completions are: -<keycap> <keycode> -<keycombo> <keysym> - - - - - - Tag Closure - - - Once you have started the tag of choice, you must close it. The easiest - way to close an open tag is to use the keycombo - Ctrl-c, followed by - /. This will close the closest open tag you have. - - - - - - Other Emacs Tasks - - - Working with one window: Sometimes in - Emacs the window becomes split (with tags - completions or other text in the bottom window). The easiest way to - get it back so that only your XML and text appear on one screen is to - use the keycombo Ctrl-x, followed by - 1. - - - - Saving your work: To save your work, use the - following keycombo, Ctrl-x followed by - Ctrl-s. - - - - The "clear/quit" command: I have found on some - occasions that I have gotten too far into the tag completion process and - need to just exit back out to my text. The easiest way to do this is the - keycombo Ctrl-g. This command quits - what you have been doing within the file, without quitting the file - itself. - - - - Opening a new file: To open a new file, use the - keycombo Ctrl-x followed by - Ctrl-f. At the bottom of the emacs - window, you will be able to enter in the file name (using - Tab completion if needed) of the file you wish to - open. - - - - Closing emacs: The easiest way to close - emacs is to use the keycombo - Ctrl-x followed by - Ctrl-c. If you have not saved your work, - it will prompt you to save the file, otherwise it will just quit the - current emacs session you have been working with. - - - - - - - Additional Resources - - Additional Emacs and PSGML references are available at the - following locations: - - - - - http://wks.uts.ohio-state.edu/unix_course/intro-135.html - — Emacs Quick Reference Guide - - - Emacs reference card that comes with the - emacs package. You can print it out as a - reference. — - /usr/share/emacs/<version>/etc/refcard.ps - - - - Read Editing XML with Emacs and PSGML - in /usr/share/doc/psgml-<version>/psgml.ps. - - - http://www.snee.com/bob/sgmlfree/psgmqref.html - — Emacs/PSGML Quick Reference is a - reference table of Emacs commands for PSGML mode. - - - - http://www.snee.com/bob/sgmlfree/emcspsgm.html - — PSGML Tricks - - - - - - - - - - - - - - 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 @@ - - Emacs and nXML Mode - - - nXML - - - - Emacs - - - - Emacs - nXML mode - - - - You can also use the nXML mode available for - Emacs 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!! - - - - Early stages - - Please be aware the nxml-mode for Emacs 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 . - - - - - - Getting the nXML RPM - - - nXML - RPM - - - - nXML RPM - - - - To use nXML mode with emacs, you will need to install the nXML RPM - available from Tim - Waugh's website or the source from http://www.thaiopensource.com/download/. The - source requires a lot more work to setup, therefore we will only be - concentrating on the RPM version. - - - - Information on where to get the source is available in . - - - - - - Examples - - - Compared to PSGML mode there are only couple of commands that you - need. This speeds up writing with Emacs - considerably, which means you can concentrate more on the content of - your article. - - - - Commands - - - To create a tag, type < and then type the - keyword. To complete the keyword, press Ctrl-Ret, - then add the last >. To close a tag, type - </. - - - - Important - - 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. - - - - - To load the schema, type Ctrl-c, then - Ctrl-s and navigate to - /usr/share/emacs/site-lisp/nxml-mode/schema/ and - load - docbook.rnc. Emacs - will then prompt you to save it in the current working directory. - - - - - Tip - - The commands already discussed are the only differences between - using Emacs with PSGML mode and - Emacs with nXML mode. You will still need - to use all the same commands as discussed in . - - - - - - - Additional Resources - - - Additional Emacs and nXML references are available at the following - locations: - - - - - http://www.thaiopensource.com/download/ - — Author's download area - - - - http://wks.uts.ohio-state.edu/unix_course/intro-135.html - — Emacs Quick Reference Guide - - - - Emacs reference card that comes with the - emacs package. You can print it out as a - reference. — - /usr/share/emacs/<version>/etc/refcard.ps - - - - - - - nXML README File - - - Note - - This file can be found in the directory you extracted the source - into, or in - /usr/share/doc/nxml-mode-<version>/ - if you installed the RPM. - - - - README file: - - - 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. - - - - 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: - - - -M-x load-file RET rng-auto.el RET - - - - This defines the necessary autoloads. Now, visit a file containing - an XML document, and do the following: - - - -M-x nxml-mode - - - - Now do - - - -C-h m - - - - For information on how to use nxml-mode. The beginnings of a manual are - in nxml-mode.info. You can read this using: - - - -C-u M-x info RET nxml-mode.info RET - - - - It's also installed as an entry at the end of the top-level info - directory. So you can read it with C-h i as usual. - - - - You can use test.valid.xml and - test.invalid.xml as examples of valid and invalid - XML documents. - - - - To get things automatically loaded each time you start Emacs, add: - - - - -(load "~/nxml-mode-200YMMDD/rng-auto.el") - - - - - to your .emacs, where - ~/nxml-mode-200YMMDD is the directory - containing the .elc files. Note that - rng-auto.el 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 - rng-auto.el itself. - - - - To use nxml-mode automatically for files with an extension of - xml, xsl, - rng or xhtml, add the - following to your .emacs file: - - - - -(setq auto-mode-alist - (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) - auto-mode-alist)) - - - - - 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 - .emacs file: - - - -(unify-8859-on-decoding-mode) - - - - 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. - - - - For more on RELAX NG, refer to http://relaxng.org/. - - - - For a tutorial on RELAX NG Compact Syntax, refer to http://relaxng.org/compact-tutorial.html - - - - For automatically creating RNC schemas, I recommend my Trang program: - http://eee.thaiopensource.com/relaxng/trang.html" - - - - You can use this to - - - - - Infer an RNC schema from an instance document - - - - - Convert a DTD to an RNC schema - - - - - Convert a RELAX NG XML syntax schema to an RNC schema - - - - - - - To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you can - also use the XSLT stylesheet from http://www.pantor.com/download.html". - - - - 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 https://www.dev.java.net/. - - - - The file NEWS describes recent changes. - - - - Please use the list http://groups.yahoo.com/group/emacs-nxml-mode - for bug reports, discussion. I will announce all new versions there. - - - - James Clark - - - jjc@thaiopensource.com - - - 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 @@ - - - - Prerequisites - - - 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. - - -
- System Packages - - To start working on the Docs Project, you will need the appropriate DocBook XML files, stylesheets, and scripts. - The following packages are required: - - - - - - xmlto — for producing HTML and PDF outputs. - - - - - docbook-style-xsl — for the default XSLT stylesheets we build on. - - - - - docbook-dtds — XML versions of the DocBook DTD - - - - - - You can verify these packages are on your system by: - - - - -rpm -q xmlto -rpm -q docbook-style-xsl -rpm -q docbook-dtds - - - - - Any missing package can be installed using yum(8) this way: - - - - -su -c 'yum install xmlto' -su -c 'yum install docbook-style-xsl' -su -c 'yum install docbook-dtds' - - -
-
- Fedora Documentation Tools - - - You need perform these steps only once. - These files are common to all the &FDPX; documents. - - - - The custom scripts and stylesheets used are all stored in CVS on the cvs.fedora.redhat.com CVS server. - You need to check them out along with the DocBook XML files for the existing docs. - - - - When you see the password prompt, press the Enter key. - In the example below, we also show how to obtain a copy of an existing &FDPX; document. - - - -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 - -
-
- Filename Conventions - - &FDPX; provides the tools, scripts, and stylesheets to transform your XML documents into either HTML or PDF output formats. - In addition, your document can automatically be built into an RPM package. - - - 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. - -
- Document Filenames - - Each document lives in a peer directory to the docs-common directory you extracted from the &FED; archive earlier. - Name your document directory something related to its subject, just avoid any name already taken. - The cvs co -c command mentioned earlier will show you the names already taken. - -
-
- Anticipating I18N Translation - - 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. - - - &FDPX; filenames are constructed appending a dash followed by the ISO language symbol before any file extention. - For example, a file whose language content is US English could be named mydoc-en.xml; the file containing its Chinese translation would then be named mydoc-zh_CN.xml, and so on. - - - To assist this effort, the document build system assumes that each file is tagged with its I18N locale. - Our filename convention is shown in - - - &FDPX; Filename Conventions - - - - - - - Compoment - - - Description - - - - - - - anything_but_dash - - - - The initial portion of a filename can be anything, as long as no dash is used. - - - - - - - - - - - A dash (-) is to be used only to introduce the ${LANG} filename component. - - - - - - ${LANG} - - - - The ${LANG} component identifies the locale for the file content. - - - In addition to helping classify files according to their language content, we also use the ${LANG} value as an UTF-8 locale when rendering the document. - For example, the document mydoc-it.xmlwill be rendered using it.UTF-8 as the language environment. - - - For more information on I18N localization, visit the web site. - - - - - -
- - Document Filenames Are Special - - The main file in your document must follow the file naming convention or the document building system cannot find it. - - -
-
-
- The Document Build System - - Common tasks such as rendering the document into either HTML or PDF can be performed easily using the document building system. - - - The building system heavily leverages the make(1) tool and shell scripts to automate these activities, but authors need no prior experience with either shell scripts or a Makefile. - While individual documents do have their own Makefile, it is only a few lines long and very simple. - The document Makefile content is designed for cut'n paste. - - - As an example, shows the whole Makefile for a simple document having only one file and one language. - - - Sample Document Makefile - -DOCBASE = mydoc -LANGUAGES = en -XMLEXTRAFILES-en= -include ../docs-common/Makefile.common - - - - Our main XML file is mydoc-en.xml; no translation has been done yet. - - - The LANGUAGES definition lists the English locale en; when other translations become available, their locale will just be appended to this definition. - - - Our document has only the main file mydoc-en.xml, but other documents may be split over several files. - The XMLEXTRAFILES-en 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. - - - The final line, beginning with include, references the main Makefile for the build system. - The Makefile.common file contains all the make(1) targets and rules to actually build the document and the various archives. - - - Add new document translations by: - - - - - Add the translated document files to the document directory. - Be sure to use the proper ${LANG} filename component to keep the filenames similar, but unique. - - - - - Edit the Makefile to append the new ${LANG} to the LANGUAGES definition. - - - - - Create a new XMLEXTRAFILES-${LANG} definition that references any document files other than the base file. - - - -
- Build System Actions - - To render the XML document into HTML or PDF the command: make html, - make html-nochunk, or make pdf may be used. - - - lists the defined build system targets. - - - Document Building Targets - - - - - - Target - Description - - - - - all - - - Builds the HTML, and the PDF forms of the document in all its defined translations. - - - Also builds the archives, such as tar(1) and rpm(8). - - - - - tarball - - - Builds only the tar(1) archive for all document languages. - - - - - pdf - - - Builds only the PDF document for all document languages. - - - Currently, PDF production is problematic and probably will not work for your document. - - - - - html - - - Builds only the HTML document for each defined translation. - Output is placed in a separate directory: - ${DOCBASE}-${LANG}/; each document section is given its own file within that directory. - - - - - html-nochunks - - - Builds only the HTML document for each defined translation. - Output is placed in a single file: - ${DOCBASE}-${LANG}.html; no other files are created. - - - - - clean - - - Deletes any temporary, or generated files. - Does not erase any HTML, PDF, or archive files. - - - - - distclean - - - Erases all HTML, PDF, and archive files. - Automatically invokes the clean target as well. - - - - - -
- - You can add your own special targets and rules by placing them at the bottom of the document Makefile, below the include line. - - - 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. - -
-
- Using Document Image Files - - Image files, such as .PNG, 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 figs/ subdirectory within your document directory. - In other words, place your image picture.png in the mydoc/figs/picture.png file. - - - Use PNG Images, Not JPG - - Depending on the output media, sometimes images may be scaled, - streteched, or squashed. - To minimize any distortions, we recommend that you use only - PDF images and avoid JPG files. - - - You may find the convert(1) program, from the ImageMagick RPM package, provides a convenient way to reformat any JPG images you already have. - - - - You may organize your image files into as many subdirectories under figs/ as you choose. - The document building system will recreate your image subdirectory structure in the output documents. - - - 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 words-en.png separate from words-ru.png is a good practice. - An image file with no text can be named just picture.png, for example. - - - 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 figs/Manifest-${LANG} so that the build system can find it as the search for image filenames begins. - - - An easy way to create the figs/Manifest-${LANG} file is shown in . - - - Building A Manifest - -rm -f figs/Manifest-en -find figs -print >/tmp/manifest -mv /tmp/manifest figs/Manifest-en -vi figs/Manifest-en - - - -
-
- 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 @@ - - - - Introduction - - - The goal of the Docs Project is to create easy-to-follow, task-based - documentation for &FC; users and developers. Other than the - &IG;, each tutorial should be in DocBook XML - article format, with one article per topic. This way, writers can - contribute documentation about a specific topic without having to worry - about how it fits into a manual or how it flows with other topics. - - - - The following tools are used: - - - - - DocBook XML v4.1 - - - Custom XSLT stylesheets for both print and HTML versions - - - Custom scripts to generate PDF and HTML output (use xmlto) - - - Emacs with PSGML mode (optional, but recommended) - - - Emacs with nXML mode (optional, but also recommended) - - - - - The purpose of this document is to explain the tools used by the Docs - Project as well as to provide writing and tagging guidelines so that the - documentation is consistent and easy-to-follow. - - - diff --git a/docs-rh-guidelines-en.xml b/docs-rh-guidelines-en.xml deleted file mode 100644 index c799abc..0000000 --- a/docs-rh-guidelines-en.xml +++ /dev/null @@ -1,586 +0,0 @@ - - &RH; Documentation Guidelines - - - recursion - recursion - - - - RTFM - read the f*'ing manual - humor - - - - humor - RTFM - - - Please read this chapter carefully. This chapter describes the - guidelines that must be followed such as naming conventions. - - - - ID Naming Conventions - - - XML tags - naming conventions - - - - naming conventions - - - You will see certain ID names referred to below and this will - help to explain how we come up with those names. For example: - - - - -<chapter id="ch-uniquename"> - -<sect3="s3-install-make-disks"> - -<figure id="fig-redhat-config-kickstart-basic"> - - - - IDs are unique identifiers, allowing DocBook XML to know where to - cross-reference a section or chapter or the like. - - - The general rules for defining an ID are: - - - XML tags - rules for defining an ID - - - - naming conventions - rules for defining an ID - - - - - Keep it 32 characters or under (this is counted as - everything between the quotation marks) - - - Keep it as short and simple as possible - - - Make sure the name is relevant to the information (make it - recognizable) - - - - Some examples are "ch-uniquename" (with 13 - characters) and "s3-install-make-disks" (with 21 - characters). - - - A section within a particular chapter always uses the chapter - name (minus the "ch-") in its ID. For example, you - are working with the "ch-intro" chapter and need to - create your first section on disk partitions. That section ID would look - similar to "s1-intro-partition" which contains the - section number, the main chapter ID, and a unique ID for that section. - - - - Naming Conventions - - - - - - - Tag - Prefix - - - - - preface - pr- - - - chapter - ch- - - - section - sn- - - - sect1 - s1- - - - sect2 - s2- - - - sect3 - s3- - - - sect4 - s4- - - - figure - fig- - - - table - tb- - - - appendix - ap- - - - part - pt- - - - example - ex- - - - -
- - - - - File Header - - - All the files must contain the CVS Id header. - - - - If you create a new file, the first line must be: - - - -<!-- $Id: --> - - - - - The first time it is committed to CVS (and every time it is committed to - CVS) the line is updated automatically to include information about the - file. For example: - - - - -<!-- $Id: docs-rh-guidelines-en.xml,v 1.2 2004/08/31 15:45:29 tfox Exp $ --> - - - - - - - Admonitions - - - admonitions - - - - XML tags - warning - - - - XML tags - tip - - - - XML tags - note - - - - XML tags - caution - - - - XML tags - important - - - - XML tags - admonitions - warning - - - - XML tags - admonitions - tip - - - - XML tags - admonitions - note - - - - XML tags - admonitions - caution - - - - XML tags - admonitions - important - - - There are five types of admonitions in DocBook: Caution, Important, - Note, Tip, and Warning. - - All of the admonitions have the same structure: an optional Title - followed by paragraph-level elements. The DocBook DTD does not impose any - specific semantics on the individual admonitions. For example, DocBook - does not mandate that Warnings be reserved for cases where bodily harm can - result. - - - - Creating Notes, Tips, Cautions, Importants, and Warnings - - - XML tags - note - - - - XML tags - tip - - - - XML tags - caution - - - - XML tags - important - - - - XML tags - warning - - - There are several ways to bring attention to text within a - document. A Note is used to bring additional - information to the users' attention. A Tip is - used to show the user helpful information or another way to do - something. A Caution is used to show the user - they must be careful when attempting a certain step. An - Important tag set can be used to show the user a - piece of information that should not be overlooked. While this - information may not change anything the user is doing, it should show - the user that this piece of information could be vital. A - Warning is used to show the reader that their - current setup will change or be altered, such as files being removed, - and they should not choose this operation unless they are alright with - the consequences. - - The following lines of code will show the basic setup for each - case as mentioned above, along with an example of how it would be - displayed in the HTML. - - - - -<note> -<title>Note</title> -<para>Body of text goes here.</para> -</note> - - - - - Note Body of text goes here. - - - - - -<tip> -<title>Tip</title> -<para>Body of text goes here.</para> -</tip> - - - - - Tip - Body of text goes here - - - - -<caution> -<title>Caution</title> -<para>Body of text goes here.</para> -</caution> - - - - - Caution Body of text goes here. - - - - - -<important> -<title>Important</title> -<para>Body of text goes here.</para> -</important> - - - - - Important - Body of text goes here. - - - - -<warning> -<title>Warning</title> -<para>Body of text goes here.</para> -</warning> - - - - - Warning Body of text goes here. - - - - - - - Screenshots - - - screenshots - how to take - - - screen captures - screenshots - - - screen grabs - screenshots - - - - There are two types of screenshots: graphical and textual. The - philosophy on using these two types is rely on text over - graphics. 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. - - - 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. - - - The steps for taking a graphical screenshot illustrate how using text to - describe a procedure is more concise than a series of screenshots. - - - - Graphical Screenshot - - - - - 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 - Preferences, - Theme and select - Bluecurve from the theme list. - - - - - Set fonts to Bluecurve defaults as well. From the panel menu, - choose Preferences, - Fonts. Set the - Application font and the - Desktop font to Sans Regular 10. Set the - Window Title font to Sans Bold 10. Set - the Terminal font to Monospace Regular - 10. - - - - - 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. - - - - - To take the screenshot, select the GUI element with your - mouse, bringing it to the forefront, or otherwise arranging - the elements. Press Alt - Print Screen to capture a single - GUI window. For capturing the entire desktop use - Print Screen. If you are taking a shot of - multiple elements and have grouped them closely together, you - can crop the resulting image in The - GIMP. The image will be in the PNG format. - - - - - If you need to, you can resize using The - GIMP. With the image open, right-click on it - and choose Image -> Scale - Image.... With the chain symbol intact, set the - New Width to 500 px, - and click OK. Be sure to - Ctrl s to save - your changes to your PNG before converting to EPS. - - - - - With the image open in The GIMP, - right-click on the image, selecting File - -> Save As.... Under - Determine File Type:, select - PostScript, then click - OK. Allow flattening of the image by - clicking Export. - - - In the Save as PostScript window, select - Encapsulated PostScript, and click - OK. - - - - - For more information about calling the images from the XML, refer - to . - - - - - Text Screenshot - - 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 - screen tags, what the user types should be in - userinput tags, and what the user is shown as - output should be in computeroutput tags. - For example, the usage in - should look like . - - - Incorrect Textual Screenshot - -ps ax | grep ssh - - 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 - - - - - Correct Textual Screenshot - - To find all the currently active ssh sessions, execute the - following command: - - -ps ax | grep ssh - - - - The output will appear similar to: - - - - - 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 - - - - - For more information about using screen, refer to . - - - - - - - - Diagrams and Images - - - images - - - diagrams - creating - - - - To be written - - - - - - - - - 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 @@ - - - - - Style - - - 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 not contain. Your tutorial should - avoid: - - - - - Excessive wordiness - - - - - Unnecessary or undefined jargon - - - - - Grammatical or spelling errors - - - - - References to yourself or your experiences - - - - - Remarks which might offend or confuse any reader - - - - - 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. - - -
- - Why Style Is Important - - - Writing well comes naturally to almost no one. It is a skill that - professional writers, even famous ones, must practice constantly. - Style - style is the quality - that separates elegant writing from the merely functional. - - - 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 Ulysses - - For example, refer to. http://www.online-literature.com/james_joyce/ulysses/18/. - Please note that this example contains some mature themes and - language, and is not suitable for all readers. - - . 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. - - - 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: - - - Incorrect style - - - - - 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 messages log. When - you see "USB device found," then Bob's your uncle. - - - - Correct style - - - - - After you complete the configuration changes above, attach the - USB removable media to your system. Use the - dmesg command to examine the kernel message - log. The message USB device - found indicates that your device was - installed successfully. - - - - 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. - - - 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. - - - 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. - - - 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: - - - - - The Elements of Style, by William - Strunk. Basic rules and links to online versions can be found - at: http://en.wikipedia.org/wiki/The_Elements_of_Style - - - - - - The Chicago Manual of Style, by the - University of Chicago Press. Online version: http://www.chicagomanualofstyle.org/ - - - - - Paradigm Online Writing Assistant, - maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ - - - - - There are many free software documentation projects which have - developed their own style guidelines. This chapter, in fact, - draws heavily on the GNOME Documentation Style - Guidelines (GDSG). You may - read the original GDSG at http://developer.gnome.org/documents/style-guide/. - - -
- -
- - Fundamental Concepts of Technical Documentation - - - Bibliographic Information - - This section is drawn primarily from the - GDSG. - - - - - - - This chapter provides a brief introduction to writing technical - documentation. - - -
- General Style Requirements - - Technical writing for the &FP; imposes special constraints - beyond the basic requirements of good prose. Good &FED; - technical documentation has the following characteristics: - - - - Comprehensive - - - Describe all of the functionality of a product. Do not - omit functionality that you regard as irrelevant for the - user. - - - - - Conforming - - - - Describe what you see. Do not describe what you want to - see. Present your information in the order that users - experience the subject matter. - - - - - Clear - - - Read The Elements of Style (http://en.wikipedia.org/wiki/The_Elements_of_Style) - to help make your writing clear. - - - - - - Consistent - - - Use agreed vocabulary throughout your documentation. Use - the same vocabulary as other writers who are working on - related documentation. - - - - - Concise - - - Review your work frequently as you write your document. - Ask yourself which words you can take out. Refer to for specific guidelines. - - - - -
-
- Golden Rules - - This section contains some basic style guidelines. Subsequent - sections in this chapter expand on these guidelines to give more - detailed guidance. - - - - Golden Rule 1: Be brief - - - - - Limit each sentence to fewer than 25 words. - - - - - Limit each procedure step to 23 words. - - - - - Incorrect: Too long - 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. - - - - Correct: Less wordy - - Normally, the kernel stores the data in memory prior to - periodically writing the data to the disk. - - - - - - Golden Rule 2: Be organized - - - - - Limit each paragraph to one topic. - - - - - Limit each sentence to one idea. - - - - - Limit each procedure step to one action. - - - - - Incorrect: Disorganized topics - - The Workspace Switcher 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 window - manager, allows you to create more than one - virtual desktop, known as - workspaces, to organize your work, - with different applications running in each workspace. - The Workspace Switcher 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. - - - - Correct: Organized topics - - Use the Workspace Switcher to - add new workspaces to the GNOME - Desktop. You can run different applications in each - workspace. The Workspace - Switcher applet provides a miniature map - that shows all of your workspaces. You can use the - Workspace Switcher applet to - switch between workspaces. - - - - - Plan the order of paragraphs before you start writing. - Decide which topic you want to cover in each paragraph. - - - - - - Golden Rule 3: Be demonstrative - - - Use explicit examples to demonstrate how an application - works. Provide instructions rather than descriptions. - - - Incorrect: Describes but does not - demonstrate - - There is a text box that you can use to find out the - definition of a word. - - - - Correct: Demonstrates usage - - To request a definition of a word, type the word in the - text box, then select Lookup. - - - - - Do not apply this guideline too rigidly. Sometimes you - must explain how software works to support your how-to - examples. - - - - - - Golden Rule 4: Be objective - - - Write in a neutral tone. - - - Incorrect: Sentence takes sides - - The applet is a handy little screen grabber. - - - - Correct: Sentence is objective - - Use the applet to take screenshots. - - - - - - -
- -
- - Tone - - 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: - - - - Avoid humor - - - Humor distracts from the information you are trying to - provide. Humor also makes documentation difficult to - translate. Stay factual. - - - - - Avoid personal opinions - - - 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. - - - - - Avoid colloquial language - - - Colloquial language is difficult to translate and usually - culture-specific. Stay neutral. - - - - - Avoid topical expressions - - - An expression that is in common use today might convey - something completely different tomorrow. Stay technical. - - - - - Avoid aspirational statements - - - Statements about the future developments of a product do - not belong in technical documentation. Write about what - you see right now. Stay real. - - - - -
-
- Reaching the Right Audience - - 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. - -
-
- User Motivation - - 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. - -
-
- New Users - - 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. - -
-
- Experienced Users - - 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. - -
-
- Do Not Offend Your Audience - - To avoid offending your readers, apply the following guidelines - to your documentation: - - - - Avoid insider language - - - Insider language includes both undefined jargon and the - tendency of the computer community to shorten words. For - example, use the term documentation - instead of the term docs. A term may - be jargon if it fails all the following conditions: - - - - - The term does not appear in the &FED; - Jargon Buster (http://fedora.redhat.com/docs/jargon-buster/). - - - - - The term does not appear in the American - Heritage Dictionary (http://www.bartleby.com/61/ - ). - - - - - The term does not appear in the glossary of the manual - that you are writing. - - - - - The term is not defined in the body text of the manual - that you are writing. - - - - - - - Avoid gender-specific language - - - Pronoun constructions such as his/her - or s/he do not exist. There is no need - to identify gender in your instructions. - - - - - Avoid culture-specific language - - - 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. - - - - - Avoid talking down to your reader - - - 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. - - - - - - Other parts of this guide discuss in more detail tone and - language usage that can cause offense. - - -
- -
- -
- - Grammar and Usage Guidelines - - - Bibliographical Information - - This section is drawn partly from the - GDSG, and partly from The - Elements of Style, updated as necessary for the - needs of 21st-century technical documentation writers. - - - - - - - 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 American Heritage Dictionary (http://www.bartleby.com/61/) - and the Chicago Manual of Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) - - - - Abbreviations - - - A shortened form of a word or phrase that takes the place of - the full word or phrase, such as Dr., - a.m., p.m., and so on. - Apply the following rules when you use abbreviations: - - - - - Avoid creating new abbreviations. Unfamiliar - abbreviations can confuse rather than clarify a concept. - - - - - Do not explain or expand familiar abbreviations. - - - - - Do not include familiar abbreviations in the glossary of - your manual. - - - - - For abbreviations of phrases, such as - i.e. for "in other words" and - e.g. for "for example", do not use the - abbreviation. Spell out the entire phrase. - - - - - Adjectives - - - 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. - - - - - Acronyms - - - A term that represents a multi-word term. Typically, - acronyms are formed in the following ways: - - - - - From the first letters of each word in a compound term, - for example Table of Contents (TOC). - - - - - From recognizable parts of a compound term, such as GNU - Object Model Environment (GNOME). - - - - - Apply the following rules when you use acronyms: - - - - - On the first occurrence of an acronym, spell out the - full term, with the acronym in parentheses. - - - - - Do not spell out the full compound for well-known - acronyms, unless you think the information is useful for - readers. - - - - - Avoid creating new acronyms. Unfamiliar acronyms can - confuse rather than clarify a concept. - - - - - Write the acronym in uppercase letters, unless there is - a compelling case for lowercase. - - - - - Include the acronym and the full term in the glossary of - your manual. - - - - - - - Adverbs - - - 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 - simply, easily, - quickly. - - - - - Anthropomorphism - - - - - Do not apply emotions, desires, or opinions to software - applications. - - - - - Do not apply a sense of location or dimension to a - software application. A user can not be "in" a text - editor. - - - - - - - Articles - - - Do not use the definite article the to - begin any of the following items: - - - - - Manual titles - - - - - Chapter titles - - - - - Headings - - - - - Figure captions - - - - - Table captions - - - - - Callouts - - - - - - - Apostrophe - - - Do not use apostrophes except where absolutely required - - - - - Do not use apostrophes to denote possession. - - - - - Do not use apostrophes to denote contractions. - - - - - Do not use apostrophes to denote plurals. - - - - - Incorrect: Apostrophes - - - - the Main Menu's - Help option - - - - - don't use the default option - - - - - several SCSI disk's - - - - - - Correct: No apostrophes - - - - the Help option on the - Main Menu - - - - - do not use the default option - - - - - several SCSI disks - - - - - - - - Brackets - - - - - Do not use brackets [such as these] as a substitute for - parentheses (such as these). - - - - - Use brackets for optional command line entries. - - - - - Do not use angle brackets to indicate variables in text, - instead use the replaceable tag. Refer to - for - information about using this tag. - - - - - - - Capitalization - - - Capitalize in the following situations: - - - - - All letters in acronyms, unless the acronym is a - well-known exception - - - - - Initial letter of the first word in a list - - - - - Initial letter of the first word in a callout - - - - - Initial letter of a key name, such as the - Shift key - - - - - Initial letter of a sentence - - - Command Names - - Avoid starting a sentence with a command name or - application name that has a lowercase initial letter. - - - - - - Initial letter of a complete sentence after a colon - - - - - Do not capitalize in the following situations: - - - - - A compound term that is followed by an abbreviation or - an acronym - - - - - When you want to emphasize something - - - - - Variable names - - - - - The initial letter of an incomplete sentence after a - colon - - - - - - - Captions - - - 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. - - - - - Colon - - - Use a colon in the following situations: - - - - - To introduce a list - - - - - Before an explanation - - - - - After an introduction - - - - - Do not use a colon in the following situations: - - - - - To introduce a figure or a table - - - - - To introduce headings - - - - - At the end of an introduction to a procedure - - - - - - - Column headings - - - Use the same rules as for headings. - - - - - Comma - - - Use commas in the following situations: - - - - - To separate items in a series - - - - - To separate the parts of a sentence - - - - - To separate nonrestrictive phrases - - - - - Instead of dashes to set off appositives - - - - - With for example and similar - expressions - - - - - Do not use commas in the following situations: - - - - - In a series of adjectives used as one modifier - - - - - Between two short independent clauses - - - - - - - Commands - - - Do not use commands as verbs. - - - - - Contractions - - - Do not use contractions such as can't, - don't, or isn't. - - - - - Dash - - - 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. - - - - - Ellipsis - - - Use an ellipsis in the following situations: - - - - - To show that you have omitted something from a sentence - - - - - To indicate a pause when you quote displayed text - - - - - - - Fractions - - - Follow these rules when using fractions: - - - - - Use numerals for fractions in tables and in units of - measurement, but spell out fractions in prose. - - - - - 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. - - - - - If a fraction is used in a compound modifier, insert a - hyphen between the fraction and the unit of measurement. - - - - - - - Gender - - - Refer to . - - - - - Grammar - - - Use standard American English grammar rules, refer to the - Chicago Manual of Style ( - http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) - - - - - Headings - - - Use the following capitalization rules in headings: - - - - - Initial uppercase letter of the first word - - - - - Initial uppercase letter for all nouns, adjectives, and - verbs. - - - - - All lowercase letters for conjunctions, articles, and - prepositions of fewer than four letters - - - - - Initial uppercase letter for prepositions of four - letters or longer - - - - - Initial uppercase letter for conjunctions of four - letters or longer - - - - - - - - Hyphen - - - Use hyphens in the following situations: - - - - With a numeral in a compound modifier - - - - - To prevent ambiguity - - - - - With some standard prefixes and suffixes. Use the - American Heritage Dictionary - (http://www.bartleby.com/61/) - for guidance - - - - - In spelled-out fractions - - - - - In variable names of two or more words, such as - directory-name. Note: - filename is an exception. - - - - - Do not use hyphens in the following situations: - - - - - For industry-accepted terms - - - - - To construct verbs - - - - - With an adverb ending in ly - - - - - With numerals as single modifiers - - - - - With a word that is listed as unhyphenated in the - American Heritage Dictionary - (http://www.bartleby.com/61/), - and that uses a common prefix - - - - - With trademarked terms - - - - - - - Latin terms - - - Do not use Latin terms. Use an equivalent English term - instead. - - - - - Like - - - Do not use the term like to denote - equivalence or similarity. - - - - - Lists - - - Introduce a list with a complete sentence that ends with a - colon. - - - - - Numbers - - - Spell out numbers in the following situations: - - - - Numbers from zero through nine unless the number is - part of a measurement - - - - - Approximations - - - - - Extreme values such as million, but - precede the value with a numeral - - - - - Any number that begins a sentence - - - - - A number that is immediately followed by a numeral, for - example: two 10 MB files - - - - - - - Numerals - - - Use numerals in the following situations: - - - - - The number 10 or greater - - - - Negative numbers - - - - - Most fractions - - - - - Percentages - - - - - Decimals - - - - - Measurements - - - - - Units of time smaller than one second - - - - - References to bits and bytes - - - - - - - Parentheses - - - Use parentheses in the following situations: - - - - - To contain the abbreviation of a term on the first - occurrence of the full term - - - - - In man page references, specifically the section number - - - - - - - Period - - - Use a period in the following situations: - - - - - To end a sentence - - - - - In file and directory names - - - - - In abbreviations that can be mistaken for words, such as - a.m. and U.S. - - - - - - - Punctuation - - - Use standard American English punctuation rules. In - addition to the specific points of punctuation in this - section, refer also to the Chicago Manual of - Style (http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.) - - - - - Punctuation in numbers - - - Do not use a comma in numerals of four digits. Use a comma - in numerals of more than four digits. - - - - - Quotation marks - - - 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. - - - - - See v. Refer to - - - 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 see and seealso 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. - - - - - Semicolon - - - Do not use semicolons. - - - - - Slash - - - Except where required as part of a filename, do not use - slashes "/" in your writing. The construction - and/or, for example, does not exist. Use - one or the other term instead. - - - - - Spelling - - - Use standard American English spelling rules, refer to the - American Heritage Dictionary (http://www.bartleby.com/61/) - for guidelines. - - - - - Titles - - - For manual titles use the same rules as for headings. - - - - - Units - - - Follow these rules when using units: - - - - - Use standard abbreviations for units of measurements, do - not invent your own abbreviations. - - - - - For further - guidelines, refer to the IEEE Standard - Dictionary of Electrical and Electronics - Terms. - - - - - Use periods for abbreviated units that might be mistaken - for a word. - - - - - Most standard abbreviations of units account for both - singular and plural usage. - - - - - Insert a space between the numeral and the unit of - measurement. - - - - - - - -
- -
- - Composition Tips - - - - - 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. - - -
- Active Voice - - 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. - - - Incorrect: Passive voice - - The yum update command must be run. - - - You might want to run the yum update - command. - - - - Correct: Active voice - - Run the yum update command. - - -
- -
- Present Tense - - 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 . - - - Incorrect: Future tense - - The application will display a list of target files. - - - A list of target files will be displayed by the application. - - - - Correct: Present tense - - The application displays a list of target files. - - -
- -
- Narrative Voice - - 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." - - - Incorrect: First or third person - - As described in the last section, I always run - up2date before configuring the Samba - server. - - - If the user needs to back up his or her files, s/he should use - the tar or cpio command. - - - - Correct: Second (or no) person - - Refer to the section on up2date before - configuring the Samba server. - - - If necessary, users can back up files with the - tar or cpio command. - - -
- -
- Negative Words - - 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 don't or - can't. Refer to . - -
- -
- Uncertainty - - 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. - -
- -
- Redundant Coverage - - 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. - -
- -
- Self-referential Value Judgments - - Avoid statements such as "One of the most important things to do - is XYZ." 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 XYZ." - Then elaborate as required. If the whole section concerns how - to do XYZ, leave this sentence out - entirely. Refer also to . - -
- -
- Precision of Language - - Use precise words for actions users should take. Do not - instruct users to "go" to a selection, or "find" a menu. - - - Incorrect: Imprecise wording - - - - Go to the Main Menu -> - Foobar - - - - - Find the option labeled Search - - - - - - Correct: Precise wording - - - - From the Main Menu, select - Foobar - - - - - Select the Search option - - - - - - Do Not Discriminate Against Non-GUI Users - - 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. - - - -
- -
- DocBook Tips - - This section contains tips on how to use DocBook tags more - effectively in your documentation. - - -
- Admonitions - - 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. - - - Incorrect: Lengthy admonition - - - Use <command>sfdisk</command> to check input - - The sfdisk command accepts a script - file as standard input to set up partitions on a hard - disk. Sometimes sfdisk 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 sfdisk - -n command to check your input file before - writing to the disk. - - - - - - Correct: Brief admonition - - The sfdisk command accepts a script - file as standard input to set up partitions on a hard disk. - Sometimes sfdisk will simply reject an - erroneous input file. In other cases, it will use the input - verbatim, writing an incorrect partition table to your disk. - - Check Input - - Always use the sfdisk -n command to - check your input file before writing to the disk. - - - - - - 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"). - - - Follow the capitalization rules for headings in the title of - an admonition. - -
- -
- The <sgmltag class="starttag">replaceable</sgmltag> - Tag - - If your documentation formally states a specific value will be - used as a convention, do not use the replaceable tag in your text or - examples. - -
- -
- XML Entities - - Use the entities provided by the &FDP;. These entities are - found in the common/ folder in the - fedora-docs distribution. (Refer also to - .) For instance, do not use - abbreviations such as "FC2." Instead, use the predefined - entities "&FC; &FCVER;," which produces the text "&FC; - &FCVER;." - -
- -
- -
- - - - 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 @@ - - - The Layout of a Tutorial - - - In this chapter, you will find an example of a &PROJECT; documentation - parent file. This example is specific to the way the Docs Project uses - DocBook XML. The parent file contains the main structural format of the - book, 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. - - - - The Parent File - - - Below is a sample parent file: - - - - -<!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> - - - - - - - Including the License Information - - - tutorial layout - license - - - - All &PROJECT; manuals must contain the file - legalnotice.xml. This file makes the license for - the file the GNU Free Documentation License (FDL). - - - - The sample parent file shows how it is included. - - - - - - - diff --git a/docs-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 @@ - - - - VIM and DocBook - - - VIM - - - - 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 vimtutor or by typing - :help tutor from inside VIM. - - - - Setting Up Your <filename>.vimrc</filename> File - - - VIM - configuration file - - - - Below is a short sample .vimrc file that turns on - some VIM features useful for editing SGML or XML content such as - DocBook: - -" 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 - - - - - Some of these features require the vim-enhanced - package to be installed. If you are using or the - vim-minimal package, or if you are using an older - version of VIM, you may not have the - $VIMRUNTIME/macros/matchit.vim file. You can still - download matchit.zip from - Vim.org and load it separately. - - - - - - Keymapping with VIM - - - 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 (\), but it can be - redefined with a command like let mapleader = - ",". There are two ways to use the following example; - you can put it directly in your .vimrc, or you - can save it in a separate file and load it with a - source command in your - .vimrc. - -e />:nohlsearcha - -" common tags that start a new text block -imappa O -imaps1 joO -imappl O0i -imapcp O0i - -" common tags that are placed inline -" use F>a -imapen F>a -imapfi F>a -imaplt F>a -imapre F>a -imapui F>a -imapul F>a -imapsi F>a -imapus F>a -imapsy F>a -imapcm F>a -" entities -imap > > -imap < <]]> - - - - 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 . - - - - - Additional VIM Resources - - - Additional information about VIM may be found from: - - - - - - Example sgml-vimrc from the Beginner's guide to - Vi Improved (VIM) - - - - The VIM - Quick Reference Card - - - - - Vim as XML - Editor - - - - - The VIM REFERENCE MANUAL, which comes with - the vim-common package — - /usr/share/vim/<version>/doc/intro.txt - or type :help intro from within VIM - - - - - - - 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 @@ - - - - DocBook XML Tags - - - XML - tags - XML tags - - - Please read this chapter carefully. This chapter describes the tags - used by the Docs Project. Some of the rules described are specific to the - project. - - - If these tags are used appropriately, document searches will provide - meaningful results. These tags help search engines identify the - information relevant to the search request. Another benefit is that all - &PROJECT; documents will have a similar look and feel (however, they will have - some differences depending upon the output format). - - - - XML - general tag information - - - All tags in XML must have an opening and closing tag Additionally, - proper XML conventions say that there must be a unique identifier for - sections, chapters, figures, tables, and so on, so that they may be - correctly identified, and cross referenced if needed. - - Although XML is capable of handling many document types, the format - discussed here is the article format. - - - This chapter only discusses tags used for documentation for the &PROJECT;, - not all available DocBook XML tags. For the complete list, refer to: - - - -http://www.docbook.org/tdg/en/html/docbook.html - - - - - Tags and Entities Caveats - - - xml tags - caveats - - - - It is very important that you remember the caveats in this section. Even - though they are more strict than valid DocBook XML, these rules exist - so that both the HTML and PDF outputs look proper. - - - - - Do Not Use Trademark Entities - - Do not use the trademark entities &trade;, &copy;, or - &reg; because the do not produce HTML output that works for all - charsets. The HTML output produces by these entities are declared in - the DTD and cannot be changed via the stylesheet. - Instead, use the trademark tag and its - associates classes as follows: - - - - <trademark>trademark symbol after me</trademark> - - - - <trademark class="registered">registered trademark symbol after me</trademark> - - - - <trademark class="copyright">copyright symbol after me</trademark> - - - - - - Content inside para tags - - Do not use para tags around anything other - than a simple paragraph. Doing so will create additional white space - within the text itself in the PDF version. - - Specifically, do not use para tags around - the following (or, to put this another way, do not embed the - following within para tags): - - - - <screen> - - - <itemizedlist> - - - <orderedlist> - - - <variablelist> - - - <table> - - - - - - Content inside para tags within - listitem tags - - Content inside para tags within - listitem tags must start - immediately after the beginning <para> tag to avoid extra - white space in the PDF version. - - - - - Content inside screen tags - - The screen tags (<screen> and - </screen>) must be flush left in the - XML file, and all the content inside the - screen tags must be flush left as well unless - the white space in intentional; otherwise, the extraneous - whitespace will appear in the HTML version. - - - - - - - - - <command>application</command> - - - XML tags - application - - - An application is the name of a GUI software program. A command is - the name of an executable (text) program or a software command. - - The <application> and - </application> tags allow you to refer to an - application or program. For example, the following XML: - - - - -To view the Web in Linux, you can use -<application>Mozilla</application> or -<application>lynx</application> if you only want a text-based -browser. - - - - - produces the following output: - - - - To view the Web in Linux, you can use Mozilla - or lynx if you only want a text-based browser. - - - - - - <command>chapter</command> - - - XML tags - chapter - - - - A DocBook book can be divided into chapters such as: - - - - -<!--$Id: docs-xml-tags-en.xml,v 1.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> - - - - - The chapter can also be further divided into sections - (sect1, sect2, - sect3, etc.). Refer to for details. - - - - - - - <command>citetitle</command> - - - XML tags - citetitle - - - - - The <citetitle> tag provides formatting for a - specific references (title can be manually typed out or if already - defined within your document set, given as an entityAn - entity is a short hand way of referring to another manual or guide. It - can be defined within the parent document or within a set of files that - your DTD references for your specific documentation set. - - ). - - - For example: - - - -<citetitle>IG;</citetitle>. - - - - The output looks like &IG; because &IG; is an - entity. - - - - - - <command>command</command> - - - XML tags - command - - - An application is the name of a GUI software program. A command is - the name of an executable (text) program or a software command. Any - program that is a command line or text-based only tool is marked with - command tags. - - - If you have text that is a command, use the - <command> and - </command> tags such as: - - - - - - -To change your keyboard after installation, become root -and use the <command>redhat-config-keyboard</command> command, -or you can type <command>setup</command> at the root prompt. - - - - - The output: - - - To change your keyboard after installation, become root and use - the redhat-config-keyboard command, or you can type - setup at the root prompt. - - - Another example would be: - - - -<command>MAILNOVIOLATIONS</command> — If set -to <command>true</command> this option tells Tripwire to -email a report at a regular interval regardless of whether or not -any violations have occured. The default value is -<command>true</command>. - - - - - with the output: - - - - MAILNOVIOLATIONS — If set to - true this variable tells Tripwire to email a report - at a regular interval regardless of whether or not any violations have - occured. The default value is true. - - - - Note In this example, the option value (true) is - defined with a <command> tag set. Because a option is a - configuration file option (command line options which would use the - <option> tag set), and because there is no configuration file - option tag available to use, we are extending the <command> tag - set to define options in a configuration file. - - - - Terms marked with command tags because there aren't - exact tags for them: - - - - Options in configuration files such as Apache directives - - - daemon names - - - - - - - <command>computeroutput</command> - - - XML tags - computeroutput - - - - To show computer output use the following tags: - - - -<computeroutput>Do you want to delete this file? y n</computeroutput> - - - - - The output: - - - Do you really want to delete this file? y n - - - - - <command>emphasis</command> - - - XML tags - emphasis - - - - To emphasis content, use the <emphasis> and - </emphasis> tags. For example: - - - -This installation <emphasis>will remove all</emphasis> existing -Linux partitions on <emphasis>all</emphasis> hard drives in your -system; non-Linux partitions will not be removed. - - - - - The output: - - - - This installation will remove all existing Linux - partitions on all hard drives in your system; - non-Linux partitions will not be removed. - - - - - <command>example</command> - - - XML tags - example - - - The <example> and - </example> tags are used to format text within a - document and is great for adding emphasis to show examples of code, - exercises, and more. - - The <example> tag set should be given an ID - and title: - - - <example id="static-ip"> - <title>Static IP Address using DHCP</title> - -<screen width=60> -<computeroutput> -host apex { - option host-name "apex.example.com"; - hardware ethernet 00:A0:78:8E:9E:AA; - fixed-address 192.168.1.4; -} -<computeroutput> -</screen> - - </example> - - - - The output: - - - - Static IP Address using DHCP - - - -host apex { - option host-name "apex.example.com"; - hardware ethernet 00:A0:78:8E:9E:AA; - fixed-address 192.168.1.4; -} - - - - - - - - - <command>filename</command> - - - XML tags - filename - - - - The <filename> and - </filename> tags define a filename or path to a - file. Since directories are just special files, they are marked with the - filename tags as well. For example: - - -Edit the <filename>/home/smoore/sam.xml</filename> file to make -changes or add comments. - - - The output: - - - Edit the /home/smoore/sam.xml file to make changes - or add comments. - - - - They are also used to markup an RPM package name. For example: - - -To use the <application>Keyboard Configuration Tool</application>, the -<filename>system-config-keyboard</filename> RPM package must be installed. - - - The output: - - - To use the Keyboard Configuration Tool, the - redhat-config-keyboard RPM package must be installed. - - - - Note - - Directory names must end with a forward slash - (/) to distinguish them from file - names. - - - - - - - <command>firstterm</command> - - - XML tags - firstterm - - - - The <firstterm> and - </firstterm> tags helps to define a word that - may be unfamiliar to the user, but that will be seen commonly throughout - the text. For example: - - - -Nearly every modern-day operating system uses <firstterm>disk -partitions</firstterm>, and &FC; is no exception. - - - - - The output: - - - - Nearly every modern-day operating system uses disk - partitions, and &FC; is no exception. - - - - - - <command>footnote</command> - - - XML tags - footnote - - - - If you need to make a footnote, use the following example: - - - -For those of you who need to perform a server-class -<footnote> -<para> -A server-class installation sets up a typical server -environment. Note, no graphical environment is -installed during a server-class installation. -</para> -</footnote> installation, refer to the <citetitle>Installation Guide</citetitle>. - - - - - The output: - - - - For those of you who need to perform a server-class A - server-class installation sets up a typical server environment. Please note, no - graphical environment is installed during a server-class installation. - installation, refer to the - Installation Guide. - - - - - - <command>figure</command> - - - XML tags - figure - - - - Important - - Order matters! The EPS file must be declared - first. - - - - - An example figure declaration: - - - - -<figure id="fig-ksconfig-basic"> - <title>Basic Configuration</title> - <mediaobject> - <imageobject> - <imagedata fileref="./figs/ksconfig/ksconfig-basic.eps" - format="EPS"/> - </imageobject> - <imageobject> - <imagedata fileref="./figs/ksconfig/ksconfig-basic.png" - format="PNG"/> - </imageobject> - <textobject> - <phrase> - Some text description of this image - </phrase> - </textobject> - </mediaobject> -</figure> - - - - - The following describes what needs to be edited: - - - -<figure id="fig-ksconfig-basic"> ==> id="" would be edited - -<title>Basic Configuration</title> ==> title would be edited - -fileref="./figs/ksconfig/ksconfig-basics.eps"> ==> .eps location would be edited - -fileref="./figs/ksconfig/ksconfig-basics.png"> ==> .png location would be edited - -<phrase>Some text description of this image</phrase> ==> "Some text..." would be edited - - - - For more information on taking screenshots, refer to . - - - - - - GUI Tags - - - XML tags - GUI tags - - - - <command>guilabel</command> - - - XML tags - GUI tags - guilabel - - - - XML tags - guilabel - - - - Use the <guilabel> and - </guilabel> tags as a default for GUI - descriptions, like a screen name or screen title. For example: - - - -The <guilabel>Authentication Configuration</guilabel> screen -shows you how to make your system more secure. - - - - - The output: - - - - The Authentication Configuration screen shows you how to - make your system more secure. - - - - - <command>guibutton</command> - - - XML tags - GUI tags - guibutton - - - - XML tags - guibutton - - - - Use the <guibutton> and - </guibutton> tags to denote a button on a screen or - menu. For example: - - - -Check the <guibutton>Activate on boot</guibutton> button -to have the X Window System start automatically. - - - - - The output: - - - - Check the Activate on boot button to have the X - Window System start automatically. - - - - - <command>guiicon</command> - - - XML tags - GUI tags - guiicon - - - - XML tags - guiicon - - - - The <guiicon> and </guiicon> - tags are used to denote a panel or desktop icon. For example: - - - -Double-click the <guiicon>Start Here</guiicon> icon on the desktop. - - - - - The output: - - - - Double-click the Start Here icon on the desktop. - - - - - - <command>guimenu</command> and - <command>guimenuitem</command> - - - XML tags - GUI tags - guimenu - - - - XML tags - guimenu - - - - XML tags - GUI tags - guimenuitem - - - - XML tags - guimenuitem - - - - To note a menu (like in the installation program or within the control panel), - use the <guimenu> and - </guimenu> tags. - - - - To note submenu items, use the <guimenuitem> and - </guimenuitem> tags. (Please note that there should not - be any breaks between these commands, but for printing purposes breaks have been - inserted). For example: - - - -Select -<guimenu>Main Menu</guimenu> => - <guimenuitem>Programming</guimenuitem> => <guimenuitem>Emacs</guimenuitem> to start the -<application>Emacs</application> text editor. - - - - - The output: - - - - From the control panel, click on Main Menu => - Programming => - Emacs to start the - Emacs text editor. - - - - - - <command>keycap</command> - - - XML tags - keycap - - - - To denote a specific key, you will need to use the - <keycap> and </keycap> - tags. Brackets are automatically added around the keycap, so do not add - them in your XML code. For example: - - - -To make your selection, press the <keycap>Enter</keycap> key. - - - - - The output: - - - - To make your selection, press the Enter key. - - - - <command>menuchoice</command> - - - XML tags - menuchoice - - - - Often using a mouse is tedious for common tasks. Therefore, - programmers often build in keyboard-shortcuts to simplify their - program. These should be described using the shortcut tag as a wrapper - for the keyboard tags. The shortcut tag must be wrapped inside the - menuchoice tag. For example: - - - - -Go to the menu bar and choose: - <menuchoice> - <shortcut> - <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> - </shortcut> - <guimenu><accel>F</accel>ile</guimenu> - <guimenuitem><accel>S</accel>ave</guimenuitem> - </menuchoice>. - - - - - - The output: - - - - Go to the menu bar and choose: - - - Ctrls - - File - Save - . - - - - - - <command>keycombo</command> - - - XML tags - keycombo - - - - To illustrate a key combination, you need to use the - <keycombo> and - </keycombo>, - <keycap> and - </keycap> tags. For example: - - - -To reboot your system, press <keycombo> -<keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap> -</keycombo>. - - - - - The output: - - - - To reboot your system, press - CtrlAltDel - . - - - - - - - - Lists - - - lists - creating - - - There are several types of lists you can create using XML. You - can have a itemized (bulleted) list, a ordered (numbered) list, or a - variable list (presents a term and then a separate paragraph). - - There is also a list format for tables and for for creating a - list of glossary terms and their definitions. - - The sections below will discuss the proper uses for the various - list and how to create them. - - - <command>itemizedlist</command> - - - XML tags - itemizedlist - - - - XML tags - lists - itemizedlist - - - - lists - itemizedlist - - - An ItemizedList is best used to present - information that is important for the reader to know, but that does - not need to be in a specific order. It is shorter than a - VariableList and presents the information in a - very simple way. - - To create an ItemizedList (otherwise known as - bulleted list), use the following command sequence: - - - Note Notice below that the text for the list - item is directly surrounded by the para - tags. If you do not do this, you will find extra whitespace in - your lists where the text does not line up correctly. This is most - noticeable when you have a series of list items that consist of - multiple lines of text. This whitespace is not as noticeable in - the HTML output as it is in the PDFs. - - - - -<itemizedlist> - <listitem> - <para>Getting familiar with the installation program's user interface</para> - </listitem> - - <listitem> - <para>Starting the installation program</para> - </listitem> - - <listitem> - <para>Selecting an installation method</para> - </listitem> -</itemizedlist> - - - - The output looks like: - - - - Getting familiar with the installation program's user interface - - - - Starting the installation program - - - - Selecting an installation method - - - - - - - <command>OrderedList</command> - - - XML tags - orderedlist - - - - lists - orderedlist - - - - XML tags - lists - orderedlist - - - An orderedlist is best used to present - information that is important for the reader to know in a specific - order. orderedlists are a good way to convey - step-by-step senarios to the audience you are writing for. - - - To create an orderedlist (numbered list), use the - following XML code sequence: - - - - Note Notice below that the text for the list - item is directly surrounded by the para - tags. If you do not do this, you will find extra whitespace in - your lists where the text does not line up correctly. This is most - noticeable when you have a series of list items that consist of - multiple lines of text. This whitespace is not as noticeable in - the HTML output as it is in the PDFs. - - - - -<orderedlist> - <listitem> - <para>Online &mdash; http://www.redhat.com/support/errata; supplies errata - you can read online, and you can download diskette images - easily.</para> - </listitem> - - <listitem> - <para>Email &mdash; By sending an empty mail message to errata@redhat.com, - you will receive an email containing a text listing of the - complete errata of the installation program and related software - (if errata exist at that time). Also included are URLs to each - updated package and diskette image in the errata. Using these - URLs, you can download any necessary diskette images. Please - note: use binary mode when transferring a diskette image.</para> - </listitem> -</orderedlist> - - - - The output looks like: - - - - Online — http://www.redhat.com/support/errata; supplies errata - you can read online, and you can download diskette images - easily. - - - - - - Email — By sending an empty mail message to - errata@redhat.com, you will receive an email containing a text - listing of the complete errata of the installation program and - related software (if errata exist at that time). Also included - are URLs to each updated package and diskette image in the - errata. Using these URLs, you can download any necessary - diskette images. Please note: use binary mode when transferring - a diskette image. - - - - - - - - <command>Variablelist</command> - - - XML tags - variablelist - - - - XML tags - lists - variablelist - - - - lists - variablelist - - - A variablelist best represents a list of - terms and definitions or descriptions for those terms. - - To create a variablelist, use the following - command sequence: - - - - Note Notice below that the text for the list - item is directly surrounded by the para tags. If - you do not do this, you will find extra whitespace in your lists - where the text does not line up correctly. This is most noticeable - when you have a series of list items that consist of multiple lines - of text. This whitespace is not as noticeable in the HTML output as - it is in the PDFs. - - - - -<variablelist> - <varlistentry> - <term> New Multi-CD Install </term> - <listitem> - <para>As the installation program continues to grow, Red Hat has developed - an installation program capable of installing from - multiple CD-ROMs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>XFree 4.0 </term> - <listitem> - <para>Configuration of your X Window System during the installation has - never been more thorough. From choosing your monitor and its correct - settings, to video card probing, to testing your desired X setup, - Xconfigurator will help you set everything just right.</para> - </listitem> - </varlistentry> -</variablelist> - - - - The output looks like: - - - - New Multi-CD Install As the - installation program continues to grow, Red Hat has developed an - installation program capable of installing from - multiple CD-ROMs. - - - - - XFree 4.0 - - Configuration of your X Window System during the - installation has never been more thorough. From choosing your - monitor and its correct settings, to video card probing, to - testing your desired X setup, Xconfigurator will help you set - everything just right. - - - - - - Warning - - Do not specify the - frame attribute to the table. Doing - so breaks PDF production. - - - - - - - Creating a List Within a Table Using <command>Simplelist</command> - - - XML tags - simplelist - - - - XML tags - lists - simplelist - - - - lists - simplelist - - - - tables - creating a list within a table - simplelist - - - A simplelist is an unadorned list of - items. simplelists can be inline or arranged in - columns. - - We use simplelist to add separate paragraphs - of text within a table element. A regular list, such as - itemizedlist, cannot be embedded within a table. - - The XML commands for a table look like: - - - - <table id="tb-hwinfo-hostbus"> - <title>Host Bus Adapter Features and Configuration Requirements</title> - - <tgroup cols="3"> - <colspec colnum="1" colname="HostBus" colwidth="33"/> - <colspec colnum="2" colname="Features" colwidth="34"/> - <colspec colnum="3" colname="Single" colwidth="33"/> - - <thead> - <row> - <entry>Host Bus Adapter</entry> - <entry>Features</entry> - <entry>Single-Initiator Configuration</entry> - </row> - </thead> - - <tbody> - - <row> - <entry>Adaptec 2940U2W</entry> - - <entry><simplelist> - <member>Ultra2, wide, LVD.</member> - <member>HD68 external connector.</member> - <member>One channel, with two bus segments.</member> - <member>Set the onboard termination by using the BIOS - utility.</member> - <member>Onboard termination is disabled when the power is - off.</member> - </simplelist></entry> - - <entry><simplelist> - <member>Set the onboard termination to automatic (the - default).</member> - <member>Use the internal SCSI connector for private - (non-cluster) storage.</member> - </simplelist></entry> - </row> - - <row> - <entry>Qlogic QLA1080</entry> - - <entry><simplelist> - <member>Ultra2, wide, LVD</member> - <member>VHDCI external connector</member> - <member>One channel</member> - <member>Set the onboard termination by using the BIOS - utility.</member> - <member>Onboard termination is disabled when the power is off, - unless jumpers are used to enforce termination.</member> - </simplelist></entry> - - - <entry><simplelist> - <member>Set the onboard termination to - automatic (the default).</member> - <member>Use the internal SCSI connector for private - (non-cluster) storage.</member> - </simplelist></entry> - </row> - - </tbody> - </tgroup> - </table> - - - - The output looks like: - - - Host Bus Adapter Features and Configuration Requirements - - - - - - - - - Host Bus Adapter - Features - Single-Initiator Configuration - - - - - - - Adaptec 2940U2W - - - Ultra2, wide, LVD. - HD68 external connector. - One channel, with two bus segments. - Set the onboard termination by using the BIOS - utility. - Onboard termination is disabled when the power is - off. - - - - Set the onboard termination to automatic (the - default). - Use the internal SCSI connector for private - (non-cluster) storage. - - - - - Qlogic QLA1080 - - - Ultra2, wide, LVD - VHDCI external connector - One channel - Set the onboard termination by using the BIOS - utility. - Onboard termination is disabled when the power is off, - unless jumpers are used to enforce termination. - - - - - Set the onboard termination to - automatic (the default). - Use the internal SCSI connector for private - (non-cluster) storage. - - - - - -
- - - Note - Notice how the SimpleList tags are - used. The <entry> and <simplelist> tags must be aligned - beside one another, otherwise you will receive a parsing error. - - - For each paragraph or list item to be added within a - SimpleList, the <member> tag set must be - added around that particular text item. - - - - <command>glosslist</command> - - - XML tags - glosslist - - - - XML tags - lists - glosslist - - - - lists - glosslist - - - Use the glosslist command set to create a - list of glossary terms and their definitions. - - - In XML, an example looks like the following: - - - - <glosslist> - <glossentry> - <glossterm>applet</glossterm> - <glossdef> - <para>A small application, usually a utility or other - simple program.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>architecture</glossterm> - <glossdef> - <para>The design for organization and integration of - components within a computer or computer system.</para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>archive</glossterm> - <glossdef> - <para>To transfer files into storage for the purpose of - saving space and/or organization.</para> - </glossdef> - </glossentry> - </glosslist> - - - - - The output looks like: - - - - - applet - - A small application, usually a utility or other simple program. - - - - - architecture - - The design for organization and integration of components - within a computer or computer system. - - - - - archive - - To transfer files into storage for the purpose of saving - space and/or organization. - - - - - - - - - - <command>option</command> - - - XML tags - option - - - If you have a command that offers an option or a flag, use the - <option> and - </option> tags. - - - - Note - The <option> tag set is only meant to be used for command - line options, not options in configuration files. - - - In XML, specifying an option would look like the - following: - - - -For example, with the command <command>ls</command> you can -specify an option such as <option>-la</option>. - - - - - The output: - - - For example, with the command ls you can - specify an option such as . - - - - - Index Entries - - - indexing - - - - - XML tags - indexing - - - The following command sequence shows you the code inserted into - the body of the text to add an index entry to your document: - - - - -<indexterm> <-- indicates a term to be placed in the index -<primary>foo</primary> <-- indicates that "foo" is the first term -<secondary>bar</secondary> <-- "bar" will be listed under "foo" -</indexterm> <-- closes this index entry - - - - - foo - bar - - - - The <seealso> tag allows you to - reference another index entry or refer to another manual. Make sure - the <seealso> reference you are pointing to - has its own entry. For example: - - - - indexing - seealso tag - - - - -<indexterm> -<primary>SWAK</primary> -<seealso>salutations</seealso> -</indexterm> - - -<indexterm> -<primary>salutations</primary> -</indexterm> - - - - - SWAK - Salutations - - - - Salutations - - - - The <see> tag allows you to reference to - another index entry entirely. For example: - - - indexing - see tag - - - - - -<indexterm> -<primary>Guinness</primary> -<see>beer</see> <-- beer will be listed under -the Guinness entry, but you must make sure beer also has its -own entry to refer to. -</indexterm> - -<indexterm> -<primary>beer</primary> -</indexterm> - - - - - Guinness - Beer - - - - Beer - - - To view the HTML output of the index entries shown here, refer - to the generated-index.html file at the end of - this document. - - 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 - generate.index stylesheet parameter, which is set to - true by default. - - - - - - <command>para</command> - - - - XML tags - para - - - For any paragraph, the <para> and - </para> tags must open and close that - particular paragraph. - - - Do not use para tags around anything other than a simple - paragraph. Doing so will create additional white space within - the text itself. - - Do not use <para> tags around the - following (or, to put this another way, do not embed the - following within <para> tags): - - - - <screen> - - - <itemizedlist> - - - <orderedlist> - - - <variablelist> - - - <table> - - - - - - - <command>part</command> - - - parts - - - - - XML tags - part - - - - In the parent file, you can separate the chapters into parts to divide - them into logical groups. For example, in the parent file, the - part tags surround the chapter entities: - - - -<part id="pt-foo"> - <partintro> - <para>Some text for the part intro</para> - &CHAPTER; - - &ANOTHER-CHAPTER; -</part> - - - - - If you create a part, include a part introduction describing the - contents of the part. For example: - - - - - <part id="pt-setup"> - <title>Getting Setup</title> - <partintro> - <para>This section contains information you will need when you first join - the Docs group. You might need to refer to this part again for - information such as installing &FC;.</para> - </partintro> - - - - - In the HTML output, a separate HTML page is generated with the part - number, title, introduction, and TOC. In the PDF output, the same - information about the part is on a separate page. - - - - - - <command>prompt</command> - - - XML tags - prompt - - - - To show a prompt, such as a root or DOS prompt, use the - <prompt> and </prompt> - commands. For example: - - - -At the <prompt>LILO:</prompt> boot prompt, type linux to -boot into your Linux partition. - -At the <prompt>C:\></prompt> prompt, type .... - - - - - The output: - - - - At the LILO: boot prompt, type linux to boot into your - Linux partition. - - - At the C:\> prompt, type .... - - - - Note - - When showing example computer output (usually in - screen tags), do not include the prompt or command - (unless the command or prompt is the actually computer output you want - to show). - - - - - <command>replaceable</command> - - - XML tags - replaceable - - - - To create replaceable text, use the tags - <replaceable> and - </replaceable> around the text you want to use as a - variable. - - - This example demonstrates how to use the replaceable - tags when referencing the name of an RPM file: - - -foo-<replaceable>version-number</replaceable>.<replaceable>arch</replaceable>.rpm - - - - The output: - - - -foo-version-number.arch.rpm - - - - - <command>screen</command> - - XML tags - screen - - - - The <screen> command is used to format text - within a document and is great for adding emphasis to show examples of - code, computer output, and more. In HTML with the Fedora CSS file, this - appears in box with a grey background. To use this command you only need - the opening <screen> and closing - </screen> tags around the text you are - emphasizing. - - - - Important - - When using the <screen> tag, you must set - everything within that screen, including the - <screen> tags themselves, to flush left. This - must be done so that when it is converted to HTML, it will not have - extra blank space in front of it inside the gray background. - - - - - The <screen> tag set may contain other inline - tags, such as <computeroutput>, - <userinput>, or - <replaceable>. Additional inline tags are not - required by definition. The <screen> 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. - - - - If you use inline tags, remember that line breaks inside - <screen> tags create line breaks in any rendered - output. Place any inline tags on the same line as - their content. Do not overuse tagging within a - <screen> tag set. - - - - An example of <screen> is the following: - - - -<screen> -This is an example of a screen. You do not need &lt;para&gt; tags -within this command. -</screen> - - - - The output: - - - -This is an example of a screen. You do not need <para> tags -within this command. - - - - Using Inline Tags with <command>screen</command> - - If you choose to use inline tags inside a - <screen> 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 - <computeroutput> tag set around the entire - output. If the user should type the example on the command line or in - a configuration file, use the <userinput> tag - set. Separate input and output with a short sentence of narrative, as - below: - - - - <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> - - - - The output looks like: - - - - Type the following command: - - - -command -sw file1 - - - - You should see the following output: - - - -Completed, time = 0.12 sec - - - - Note - - When showing a command or series of commands inside - screen tags, do not show the prompt. - - - - - If the <screen> shows the reader how to - change only part of a line, mark the change with - an inline <userinput> tag set. You may use - the <userinput> tag set inside a larger area - that is already marked inline with - <computeroutput>. 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> - Edit the <filename>/etc/sysconfig/init</filename> file as follows: - </para> - -<screen> -GRAPHICAL=<userinput>yes</userinput> -</screen> - - - - The output looks like: - - - - Edit the /etc/sysconfig/init file as follows: - - - -GRAPHICAL=yes - - - - For an explanation of how to use the replaceable - tags within a set of screen tags, refer to . - - - - - - - Sections - - - XML tags - sections - - - - sections - - - Within an article (or chapter if it is a DocBook XML book like the - &IG;), you can have sections and - subsections. <sect1> is always the highest - section and you cannot have two sections of the same level within one - another (a section 2 can be created within a section 1, but section 1 - has to be closed before another section 1 can be created). The general - layout follows: - - - -<sect1 id="s1-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - - <sect2 id="s2-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - <sect3 id="s3-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> - - </sect3> - - </sect2> - -</sect1> - - - - - If you only need one level of sections in a DocBook article, you can use - the section tag. For example: - - - - -<section id="sn-uniquename"> - <title>Insert Title Here</title> - <para> - Body text goes here. - </para> -</section> -<section id="sn-anothername"> - <title>Insert Title Here</title> - <para> - More body text goes here. - </para> -</section> - - - - - - <command>table</command> - - - XML tags - table - - - - The following is an example of creating a table. - - - -<table id="tb-mockup-before-begin"> - This tells XML that you will be creating a table - and the ID name is "tb-mockup-before-begin." - -<title>Available Features of GNOME and KDE</title> - -<tgroup cols="3"> - This tells XML that you are creating a table - with three columns. - -<colspec colnum="1" colname="Features" colwidth="3"/> - colspec says that you are giving information - about the column to XML colnum="1" - says that you are giving specifications for the first column. - - colname="Features" says that the title for this - column will be "Features." - - colwidth="3" specifies the width of the - column. This can be more tricky: such as two columns with - widths of 1 and 2,the 1 is one-half the width of the 2, in - respect to the page size. But, what if you need the 1 to be a - little more than half of the 2, using a larger number ratio, - such as 10 to 20 would accomplish this. You could then change the - 10 to an 11 or a 12 to make it a little more than half of the - second column of 20. In no value is given, a value of 1 is - assumed. - -<colspec colnum="2" colname="GNOME" colwidth="2"/> -<colspec colnum="3" colname="KDE" colwidth="2"/> - -<thead> - Contains one or more table row elements. - -<row> - Contains one or more table cell (entry) elements. - -<entry>Features</entry> - Table cell element, one of several in a row element, defining - columns within the row. - -<entry>GNOME</entry> -<entry>KDE</entry> -</row> -</thead> - -<tbody> - Contains one or more row elements, for the main text - of the table. - -<row> -<entry>highly configurable</entry> -<entry>yes</entry> -<entry>yes</entry> -</row> -<row> -<entry>multiple window managers </entry> -<entry>yes</entry> -<entry>yes</entry> -</row> -<row> -<entry>Internet applications</entry> -<entry>yes </entry> -<entry>yes </entry> -</row> -</tbody> -</tgroup> -</table> - - - - Available Features of GNOME and KDE - - - - - - - - - Features - GNOME - KDE - - - - - - highly configurable - yes - yes - - - multiple window managers - yes - yes - - - Internet applications - yes - yes - - - -
- - - Creating a List Within a Table - - - XML tags - table - list within a table - - - - Creating a list within a table can be a difficult task. It - requires strict formatting and a set of commands that are not - available for command completion in - Emacs. - - The tags you will need to use are - <simplelist> and - <member>. - - The following example will show you the proper formatting for - creating a list within a table. - - - - -<table id="tb-hardware-powerswitch"> - <title>Power Switch Hardware Table</title> - <tgroup cols="4"> - <colspec colnum="1" colname="Hardware" colwidth="2"/> - <colspec colnum="2" colname="Quantity" colwidth="2"/> - <colspec colnum="3" colname="Description" colwidth="6"/> - <colspec colnum="4" colname="Required" colwidth="2"/> - - <thead> - <row> - <entry>Hardware</entry> - <entry>Quantity</entry> - <entry>Description</entry> - <entry>Required</entry> - </row> - </thead> - - <tbody> - - <row> - <entry>Serial power switches</entry> - - <entry>Two</entry> - - <entry><simplelist> <member>Power switches enable each cluster system - to power-cycle the other cluster system. Note that clusters are - configured with either serial or network attached power switches and - not both.</member> - - <member>The following serial attached power switch has been - fully tested:</member> - - <member>RPS-10 (model M/HD in the US, and model M/EC in - Europe) </member> - - <member>Latent support is provided for the following serial - attached power switch. This switch has not yet been fully - tested:</member> - - <member>APC Serial On/Off Switch (partAP9211), <ulink - url="http://www.apc.com/">http://www.apc.com/</ulink></member> - </simplelist></entry> - - <entry>Strongly recommended for data integrity under all failure - conditions</entry> - - </row> - </tbody> - </tgroup> -</table> - - - - Notice how the <simplelist> tag must be - beside the <entry> tag? If you do not format - this properly, it will not parse cleanly. - - The above example will look like the following: - - - Power Switch Hardware Table - - - - - - - - - Hardware - Quantity - Description - Required - - - - - - - Serial power switches - - Two - - Power switches enable each cluster - system to power-cycle the other cluster system. Note - that clusters are configured with either serial or - network attached power switches and not both. - - The following serial attached power switch has been - fully tested: - - RPS-10 (model M/HD in the US, and model M/EC in - Europe) - - Latent support is provided for the following - serial attached power switch. This switch has not yet - been fully tested: - - APC Serial On/Off Switch (partAP9211), http://www.apc.com/ - - - Strongly recommended for data integrity under all failure - conditions - - - - -
- - - - - - - <command>trademark</command> - - - XML tags - trademark - - - - Do not use the trademark entities &trade;, &copy;, or - &reg; because the do not produce HTML output that works for all - charsets. The HTML output produces by these entities are declared in - the DTD and cannot be changed via the stylesheet. - - Instead, use the trademark tag and its - associates classes as follows: - - - - -<trademark>trademark symbol after me</trademark> -<trademark class="registered">registered trademark symbol after me</trademark> -<trademark class="copyright">copyright symbol after me</trademark> - - - - - - - <command>userinput</command> - - - XML tags - userinput - - - - To show what a user would type, use the userinput - tag. For example: - - - -At the prompt, type: - -<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> - - - - - The output: - - - - At the prompt, type: - - - - dd if=boot.img of=/dev/fd0 bs=1440k - - - - - - - - <command>ulink</command> - - - XML tags - ulink - - - - To create a URL link within your text, use the following example: - - - -Online &mdash; <ulink url="http://www.redhat.com/support/errata/"> -http://www.redhat.com/support/errata/</ulink>; supplies errata -you can read online, and you can download diskette images easily. - - - - - The output: - - - - Online — - http://www.redhat.com/support/errata/; supplies errata - you can read online, and you can download diskette images easily. - - - - Note - - If the URL does not end in a filename, it must end in a slash - (/) to be a properly formed URL. For - example, http://www.redhat.com/. - - - - - - - <command>wordasword</command> - - - XML tags - wordasword - - - The <wordasword> tag set is used to define a word meant - specifically as a word and not representing anything else. - - A lot of technical documentation contains words that have overloaded - meanings. Sometimes it is useful to be able to use a word without invoking - its technical meaning. The <wordasword> element identifies a word or - phrase that might otherwise be interpreted in some specific way, and - asserts that it should be interpreted simply as a word. - - It is unlikely that the presentation of this element will be able to - help readers understand the variation in meaning; good writing will have - to achieve that goal. The real value of <wordasword> lies in the - fact that full-text searching and indexing tools can use it to avoid - false-positives. - - For example: - - -To use <command>grep</command> to search for the word -<wordasword>linux</wordasword>, use the command -<command>grep linux</command>. - - - - The output: - - - To use grep to search for the word - linux, use the command grep - linux. - - In the example, the word "linux" is just a word. It is not - meant to convey anything about Linux as a subject, or to add relevance or - meaning to the content. It can be replaced with any other word without - losing any of the context. - - - - - - <command>xref</command> - - - XML tags - xref - - - - To refer to other sections or chapters within a manual, use the - <xref> tag. - - - - The output of this displays the title of the section or chapter you are - pointing the user to. For example: - - - -For more information about the parent file, refer to -<xref linkend="ch-tutorial"></xref> and <xref linkend="s1-tutorial-parent"></xref> - - - - - The output: - - - - For more information about the parent file, refer to - and . - - - - -- cgit