From 7648e2b3c70a76ab2f751b60813458a5261e3373 Mon Sep 17 00:00:00 2001 From: Karsten Wade Date: Sat, 3 Feb 2007 22:21:58 +0000 Subject: renaming rh-guidelines to writing-guidelines --- en_US/docs-emacs-nxml.xml | 340 ------ en_US/docs-emacs.xml | 735 ------------ en_US/docs-getting-files.xml | 115 -- en_US/docs-intro.xml | 62 - en_US/docs-module-struct.xml | 418 ------- en_US/docs-rh-guidelines.xml | 535 --------- en_US/docs-style.xml | 1973 -------------------------------- en_US/docs-tutorial.xml | 108 -- en_US/docs-vim.xml | 156 --- en_US/docs-xml-tags.xml | 2509 ----------------------------------------- en_US/documentation-guide.xml | 20 +- en_US/emacs-nxml.xml | 340 ++++++ en_US/emacs.xml | 735 ++++++++++++ en_US/fdp-info.xml | 58 + en_US/getting-files.xml | 115 ++ en_US/intro.xml | 62 + en_US/module-struct.xml | 418 +++++++ en_US/style.xml | 1973 ++++++++++++++++++++++++++++++++ en_US/tutorial.xml | 108 ++ en_US/vim.xml | 156 +++ en_US/writing-guidelines.xml | 535 +++++++++ en_US/xml-tags.xml | 2509 +++++++++++++++++++++++++++++++++++++++++ 22 files changed, 7019 insertions(+), 6961 deletions(-) delete mode 100644 en_US/docs-emacs-nxml.xml delete mode 100644 en_US/docs-emacs.xml delete mode 100644 en_US/docs-getting-files.xml delete mode 100644 en_US/docs-intro.xml delete mode 100644 en_US/docs-module-struct.xml delete mode 100644 en_US/docs-rh-guidelines.xml delete mode 100644 en_US/docs-style.xml delete mode 100644 en_US/docs-tutorial.xml delete mode 100644 en_US/docs-vim.xml delete mode 100644 en_US/docs-xml-tags.xml create mode 100644 en_US/emacs-nxml.xml create mode 100644 en_US/emacs.xml create mode 100644 en_US/fdp-info.xml create mode 100644 en_US/getting-files.xml create mode 100644 en_US/intro.xml create mode 100644 en_US/module-struct.xml create mode 100644 en_US/style.xml create mode 100644 en_US/tutorial.xml create mode 100644 en_US/vim.xml create mode 100644 en_US/writing-guidelines.xml create mode 100644 en_US/xml-tags.xml diff --git a/en_US/docs-emacs-nxml.xml b/en_US/docs-emacs-nxml.xml deleted file mode 100644 index 5cc9dac..0000000 --- a/en_US/docs-emacs-nxml.xml +++ /dev/null @@ -1,340 +0,0 @@ - - -%FEDORA-ENTITIES-EN; - -]> - - - 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/en_US/docs-emacs.xml b/en_US/docs-emacs.xml deleted file mode 100644 index 700900b..0000000 --- a/en_US/docs-emacs.xml +++ /dev/null @@ -1,735 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - 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/en_US/docs-getting-files.xml b/en_US/docs-getting-files.xml deleted file mode 100644 index c86a6d4..0000000 --- a/en_US/docs-getting-files.xml +++ /dev/null @@ -1,115 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - Prerequisites - - - To work on official &FED; documentation you need to install the required - tools. Follow the directions below to configure your system. - - -
- System Packages - - - Install the "Authoring and Publishing" package group, which contains - required DocBook XML files, stylesheets and scripts: - - - -su -c 'yum groupinstall "Authoring and Publishing"' - - - - Next, install the cvs package, which is used to - handle revision control on files in the official repository: - - - -su -c 'yum install cvs' - - -
- -
- Fedora Documentation Tools - - - The &FDP;'s custom scripts and stylesheets are stored in CVS on the - cvs.fedoraproject.org CVS - server. Check them out along with the DocBook XML files for the existing - docs. - - - -mkdir my-fedora-docs-sandbox -cd my-fedora-docs-sandbox -export CVSROOT=:ext:username@cvs.fedora.redhat.com:/cvs/docs -cvs login -cvs co docs-common - - - - At the password prompt, press the Enter key. - - - - Common Files - - You need to perform this "checkout" step only once, although you may - need to update the files later. These files are common to all the - official documentation. - - - - - To work on existing documents in CVS, refer to . - - -
- -
- Filename Conventions - - &FDP; provides the tools, scripts, and stylesheets to transform your - XML documents into other output formats such as - HTML. In addition, these tools can build your document - into a RPM package. To take advantage of these - services, you must follow conventions for naming your files. - -
- Document Filenames - - Each document lives in a peer directory to the - docs-common directory you extracted from the &FED; - archive earlier. On the CVS server, these directories are called - modules. Choose a module name that accurately - reflects your document's subject, but avoid any name already taken. Use - the cvs co -c command to view existing module names. - - - Avoid Redundancy - - Do not use the word &FED; in your module - name. Since all documents in the repository are &FED; documentation, - using this term creates unnecessary confusion. - - -
-
- - - diff --git a/en_US/docs-intro.xml b/en_US/docs-intro.xml deleted file mode 100644 index 2df65f6..0000000 --- a/en_US/docs-intro.xml +++ /dev/null @@ -1,62 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - - Introduction - - - The goal of the &FDP; is to create easy-to-follow, task-based - documentation for &FED; 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.4 - - - Custom XSLT stylesheets for both print and HTML - versions - - - Custom scripts to generate HTML output (use - xmlto) - - - Emacs with PSGML mode (optional, but recommended) - - - Emacs with nXML mode (optional) - - - - - This document explains the tools used by the &FDP; and provides - writing and tagging guidelines to make &FED; documentation is - consistent and easy-to-follow. - - - - - diff --git a/en_US/docs-module-struct.xml b/en_US/docs-module-struct.xml deleted file mode 100644 index cad060f..0000000 --- a/en_US/docs-module-struct.xml +++ /dev/null @@ -1,418 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - How Modules Work - Documentation modules have a specific structure that enables the - preconfigured tools to work correctly. Follow this structure exactly or you - may have problems building your module. The &FDP; build tools locate - resources in the module and use them to build new output such as HTML or RPM - packages. -
- Structure of a Module - shows a directory tree - of an example module, excluding any CVS folders: - - Example Module Structure - - - - Primary language directory (required) - This is the only directory absolutely required. It is named for the - original language of the document, such as en_US (US English). The primary language - does not have to be US English; all languages are supported. This - directory contains all the XML source for the actual document, as well - as XML source for document-specific - entities - Think of an XML entity as a predefined snippet of information. - It can represent a chunk of XML source, or simply a word or - character. If the information changes, it need be replaced only - once, in the definition, to fix all usage. - . - - - - Graphics directory (optional) - The figs/ directory is an - optional directory where graphics for the document should be stored. If - graphics are screenshots that are particular to a language, the - figs/ directory can and should be - stored in a language directory. - - - Translation (PO) directory (optional) - The po/ directory contains - specially formatted files created and used by translators. The &FDP; - build tools use these files to create translated versions of documents. - The translated documents are not stored in CVS; they are created as - needed from these PO files. - - - Makefile (required) - The Makefile controls the build process. Its - content is discussed in . - - - <filename>rpm-info.xml</filename> (required) - The rpm-info.xml file contains document - specific metadata - -
-
- The Document Build System - - The build system can render the document into another format such - as HTML or PDF, using - make(1) and shell scripts. Authors need - no prior experience with either shell scripts - or a make(1). - -
- The Document <filename>Makefile</filename> - - Each individual document has its own - Makefile, which only needs to be a few - lines long. The document Makefile content - is designed for cut and paste operations. - - - below shows the whole - Makefile for a simple document with two - files and two translations. - - - Sample Document Makefile - - - - Do not be concerned with some of the more complicated syntax - such as the XMLFILES_template stanza. An - explanation for this template appears a few paragraphs - below. - - <systemitem class="macro">DOCBASE</systemitem> - This variable contains the name for the main (parent) XML - document. Follow convention by naming your document after the - module name. - - - <systemitem class="macro">PRI_LANG</systemitem> - This variable contains the ISO code for the original - version of the document, such as - en_US. - - - <systemitem class="macro">OTHERS</systemitem> - This variable contains a listing of ISO codes for any - other versions into which the document has been translated. - The module must contain a po/ directory and a PO file for - any indicated additional languages. - - - <systemitem class="macro">DOC_ENTITIES</systemitem> - This variable contains a listing of any files containing - entity definitions. The &FDP; uses a special XML format to - record document-specific entities, so they can be translated and - built on the fly like any other XML document. An example is - shown later in this guide. - - - <systemitem - class="macro">XMLFILES_template</systemitem> - This template allows the build tools to work with the - document in multiple languages once it is translated. The - ${1} marking is a - variable used to substitute the appropriate language. This - template is not terribly complicated. For a new module, - duplicate this section exactly except for the actual - filenames. Prepend the text ${1}/, in place of the language - code directory name, to each filename in your document. - - - - Files Exempt From Listing - Do not include the document-specific entities XML file or - the rpm-info.xml file, which will be - discussed later in this guide. - - - The final line, beginning with include, - references the main Makefile for the build - system. This Makefile.common file contains - all the make(1) targets and rules to - actually build the document and the various archives. - -
-
- The Document <filename>rpm-info.xml</filename> - Each document module's primary language directory contains a - file called rpm-info.xml. This file - contains document-specific metadata used to generate revision - history, copyright, and contributor information. It follows a - DTD specification included with the rest of the build system - tools. - illustrates the content of - this file: - - Example <filename>rpm-info.xml</filename> File - - - - - - - - - - OPL - 1.0 - - - 2006 - John Q. Smith - - My Tutorial - A tutorial about something important - - - -
First draft
- - -]]> - - If you are not familiar with XML editing, copy and paste - this file from an existing module and then edit the values for - the various elements as appropriate. Consult &FDP; members and - help channels for more assistance if needed. -
-
-
- Build System Actions - - To render the XML document into another format, - use one of the following make targets: - - - <systemitem class="macro">html</systemitem> - This target builds the "chunked" HTML - document for each defined translation. Output is placed in a - separate directory named ${DOCBASE}-${LANG}/. Each - document section is a separate file within that - directory. - - - <systemitem - class="macro">html-nochunks</systemitem> - This target builds the "non-chunked" HTML - document for each defined translation. Output is placed in a - single file: ${DOCBASE}-${LANG}.html; no other - files are created. - - - <systemitem class="macro">pdf</systemitem> - This target builds only the PDF document - for all document languages. PDF production is - currently erratic and may not work for your document. - - - <systemitem class="macro">tarball</systemitem> - This target builds only the tar(1) - archive for all document languages. - - - <systemitem class="macro">all</systemitem> - This target builds all targets listed above. - - - <systemitem class="macro">clean</systemitem> - This target deletes any temporary, or generated files, but - does not erase any HTML, - PDF, or archive files. - - - <systemitem class="macro">distclean</systemitem> - This target erases all HTML, - PDF, and archive files. This target - automatically invokes the clean target as - well. - -
- Adding or Changing Targets - - To add a new target and rules, place them at the bottom of the - document Makefile, below the - include line. Follow your target definitions - with a double colon, not a single colon. The double colon - allows you to specify additional rules for existing targets, or - to write rules for a new target. - - - For more information on using make(1), - consult the online documentation with the command info - make in a terminal. - -
-
- Using Document Image Files - - Tutorial documents often make use of images such as .PNG files. Store image files in - a figs/ folder in the - main module directory, as shown in . - - - Depending on the output media, sometimes images may be scaled, - streteched, or squashed. To minimize any distortions, we - recommend that you use only .PNG images. Avoid .JPG files. The - convert(1) program, from the ImageMagick RPM package, - provides a convenient way to reformat .JPG images into .PNG format. For more information - on formatting images such as screenshots, refer to . - - - Image files may be organized into subdirectories under - figs/ if necessary. The document building - system recreates the image subdirectory structure in the output - documents. - - - Images often contain labels or other text which may need to be - localized. A screenshot of a program, for example, may require - a version for each translated language. Name language-dependent - image files such as program screenshots by adding the language - code to the filename, such as - menu-en_US.png. Language-independent - images, such as icon.png, do not need - language codes. - - - Sometimes, a document may require images that do not follow the - naming convention. To use these images with the document - building system, create an ordinary text file containing the - image filenames. This file must be named - figs/Manifest-${LANG} so the build system finds - it when searching for image filenames. - - - - demonstrates one way to create this - Manifest file. - - - Building A Manifest - /tmp/manifest -mv /tmp/manifest figs/Manifest-en]]> - -
-
- Adding a New DocBook XML File - To add a new DocBook XML file to an existing document, - follow these steps: - - - Place the new DocBook XML file in the primary language - directory. - - - Edit the Makefile and add the - filename to the XMLFILES-${1} listing. - Append a \ to the last existing line, and - on the next line add an entry for the new file. Remember to - add the ${1}/ prefix as a substitute for - the language directory name. - - -
-
- Adding a Translation - Translations are stored as PO (portable object) files, which - the toolchain transforms into translated documents. Each PO - file is based on the POT (PO template) for the document and - translated by the &FED; Translation Project. To add a - translation, follow these steps: - - - If the po/ - directory does not exist, create it and add it to - CVS: - - - - If it does not exist, create the POT file: - - - - Add the new translation language to the - OTHERS listing in the - Makefile. - - - Although translators often copy the POT manually to - create the new PO file, the following command also - works: - make po/lang.po - - -
-
- - - diff --git a/en_US/docs-rh-guidelines.xml b/en_US/docs-rh-guidelines.xml deleted file mode 100644 index f243058..0000000 --- a/en_US/docs-rh-guidelines.xml +++ /dev/null @@ -1,535 +0,0 @@ - - -%FEDORA-ENTITIES-EN; - -]> - - - &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: - - - -
- -
]]> - - IDs are unique identifiers, allowing DocBook XML to know where - to cross-reference a section or chapter or the like. The - following general rules apply to IDs: - - - XML tags - rules for defining an ID - - - - naming conventions - rules for defining an ID - - - - - Restrict the ID name, which is everything between the - quotation marks, to 32 characters or fewer - - - Keep it as short and simple as possible - - - Make sure the name is recognizable and relevant to the - information - - - - Some examples are "ch-uniquename" (13 - characters) and "sn-install-make-disks" (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: - - ]]> - - 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: - - ]]> - - - - - 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 - Body of text goes here. -]]> - - - Note - Body of text goes here. - - - - Tip - Body of text goes here. -]]> - - - Tip - Body of text goes here - - - - Caution - Body of text goes here. -]]> - - - Caution - Body of text goes here. - - - - Important - Body of text goes here. -]]> - - - Important - Body of text goes here. - - - - Warning - Body of text goes here. -]]> - - - 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 . - - - - - - - - - - diff --git a/en_US/docs-style.xml b/en_US/docs-style.xml deleted file mode 100644 index 4d78392..0000000 --- a/en_US/docs-style.xml +++ /dev/null @@ -1,1973 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - - - 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/en_US/docs-tutorial.xml b/en_US/docs-tutorial.xml deleted file mode 100644 index 2bbb290..0000000 --- a/en_US/docs-tutorial.xml +++ /dev/null @@ -1,108 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - 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/en_US/docs-vim.xml b/en_US/docs-vim.xml deleted file mode 100644 index 22485f6..0000000 --- a/en_US/docs-vim.xml +++ /dev/null @@ -1,156 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - - 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/en_US/docs-xml-tags.xml b/en_US/docs-xml-tags.xml deleted file mode 100644 index 31a13d2..0000000 --- a/en_US/docs-xml-tags.xml +++ /dev/null @@ -1,2509 +0,0 @@ - - - -%FEDORA-ENTITIES-EN; - -]> - - - - 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 - - - Most tags in XML must have an opening and closing tag. A few - tags, such as xref, have no - content and close themselves. 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 content inside screen tags - (<screen> and </screen>) - must be flush left in the XML file; - otherwise, the extraneous whitespace will appear in the HTML - version. - - - - - - - - - <command>application</command> - - - XML tags - application - - - An application is the name of a GUI software program. A command is - the name of an executable (text) program or a software command. - - The <application> and - </application> tags allow you to refer to an - application or program. For example, the following XML: - - - - -To view the Web in Linux, you can use -<application>Mozilla</application> or -<application>lynx</application> if you only want a text-based -browser. - - - - - produces the following output: - - - - To view the Web in Linux, you can use Mozilla - or lynx if you only want a text-based browser. - - - - - - <command>chapter</command> - - - XML tags - chapter - - - - A DocBook book can be divided into chapters such as: - - - - -<!--$Id: docs-xml-tags.xml,v 1.3 2006/12/23 23:49:59 pfrields 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, set - everything within that screen to flush left. The contents of - the screen element are - rendered exactly as is, including any indentation. Using flush - left prevents extra blank space in front of the text inside the - gray background when the content is converted to HTML. - - - - - 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 . - - - - - - diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml index 0101163..42d1465 100644 --- a/en_US/documentation-guide.xml +++ b/en_US/documentation-guide.xml @@ -1,5 +1,5 @@ - + - - - - - - - - diff --git a/en_US/emacs-nxml.xml b/en_US/emacs-nxml.xml new file mode 100644 index 0000000..5cc9dac --- /dev/null +++ b/en_US/emacs-nxml.xml @@ -0,0 +1,340 @@ + + +%FEDORA-ENTITIES-EN; + +]> + + + 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/en_US/emacs.xml b/en_US/emacs.xml new file mode 100644 index 0000000..66b4de3 --- /dev/null +++ b/en_US/emacs.xml @@ -0,0 +1,735 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + 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/en_US/fdp-info.xml b/en_US/fdp-info.xml new file mode 100644 index 0000000..fd0f67d --- /dev/null +++ b/en_US/fdp-info.xml @@ -0,0 +1,58 @@ + + + + + + + + Fedora Documentation Guide + + 2003 + 2004 + 2005 + 2006 + Red Hat, Inc. + Tammy Fox + Johnray Fuller + Sandra Moore + Paul W. Frields + + + + Fox + Tammy + + + Fuller + Johnray + + + Moore + Sandra + + + Frields + Paul + + + + + 0.2.6.3 + 2005-09-18 + + + + Update to new build requirements + + + + + + diff --git a/en_US/getting-files.xml b/en_US/getting-files.xml new file mode 100644 index 0000000..c86a6d4 --- /dev/null +++ b/en_US/getting-files.xml @@ -0,0 +1,115 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + Prerequisites + + + To work on official &FED; documentation you need to install the required + tools. Follow the directions below to configure your system. + + +
+ System Packages + + + Install the "Authoring and Publishing" package group, which contains + required DocBook XML files, stylesheets and scripts: + + + +su -c 'yum groupinstall "Authoring and Publishing"' + + + + Next, install the cvs package, which is used to + handle revision control on files in the official repository: + + + +su -c 'yum install cvs' + + +
+ +
+ Fedora Documentation Tools + + + The &FDP;'s custom scripts and stylesheets are stored in CVS on the + cvs.fedoraproject.org CVS + server. Check them out along with the DocBook XML files for the existing + docs. + + + +mkdir my-fedora-docs-sandbox +cd my-fedora-docs-sandbox +export CVSROOT=:ext:username@cvs.fedora.redhat.com:/cvs/docs +cvs login +cvs co docs-common + + + + At the password prompt, press the Enter key. + + + + Common Files + + You need to perform this "checkout" step only once, although you may + need to update the files later. These files are common to all the + official documentation. + + + + + To work on existing documents in CVS, refer to . + + +
+ +
+ Filename Conventions + + &FDP; provides the tools, scripts, and stylesheets to transform your + XML documents into other output formats such as + HTML. In addition, these tools can build your document + into a RPM package. To take advantage of these + services, you must follow conventions for naming your files. + +
+ Document Filenames + + Each document lives in a peer directory to the + docs-common directory you extracted from the &FED; + archive earlier. On the CVS server, these directories are called + modules. Choose a module name that accurately + reflects your document's subject, but avoid any name already taken. Use + the cvs co -c command to view existing module names. + + + Avoid Redundancy + + Do not use the word &FED; in your module + name. Since all documents in the repository are &FED; documentation, + using this term creates unnecessary confusion. + + +
+
+ + + diff --git a/en_US/intro.xml b/en_US/intro.xml new file mode 100644 index 0000000..e5295c0 --- /dev/null +++ b/en_US/intro.xml @@ -0,0 +1,62 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + + Introduction + + + The goal of the &FDP; is to create easy-to-follow, task-based + documentation for &FED; 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.4 + + + Custom XSLT stylesheets for both print and HTML + versions + + + Custom scripts to generate HTML output (use + xmlto) + + + Emacs with PSGML mode (optional, but recommended) + + + Emacs with nXML mode (optional) + + + + + This document explains the tools used by the &FDP; and provides + writing and tagging guidelines to make &FED; documentation is + consistent and easy-to-follow. + + + + + diff --git a/en_US/module-struct.xml b/en_US/module-struct.xml new file mode 100644 index 0000000..cad060f --- /dev/null +++ b/en_US/module-struct.xml @@ -0,0 +1,418 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + How Modules Work + Documentation modules have a specific structure that enables the + preconfigured tools to work correctly. Follow this structure exactly or you + may have problems building your module. The &FDP; build tools locate + resources in the module and use them to build new output such as HTML or RPM + packages. +
+ Structure of a Module + shows a directory tree + of an example module, excluding any CVS folders: + + Example Module Structure + + + + Primary language directory (required) + This is the only directory absolutely required. It is named for the + original language of the document, such as en_US (US English). The primary language + does not have to be US English; all languages are supported. This + directory contains all the XML source for the actual document, as well + as XML source for document-specific + entities + Think of an XML entity as a predefined snippet of information. + It can represent a chunk of XML source, or simply a word or + character. If the information changes, it need be replaced only + once, in the definition, to fix all usage. + . + + + + Graphics directory (optional) + The figs/ directory is an + optional directory where graphics for the document should be stored. If + graphics are screenshots that are particular to a language, the + figs/ directory can and should be + stored in a language directory. + + + Translation (PO) directory (optional) + The po/ directory contains + specially formatted files created and used by translators. The &FDP; + build tools use these files to create translated versions of documents. + The translated documents are not stored in CVS; they are created as + needed from these PO files. + + + Makefile (required) + The Makefile controls the build process. Its + content is discussed in . + + + <filename>rpm-info.xml</filename> (required) + The rpm-info.xml file contains document + specific metadata + +
+
+ The Document Build System + + The build system can render the document into another format such + as HTML or PDF, using + make(1) and shell scripts. Authors need + no prior experience with either shell scripts + or a make(1). + +
+ The Document <filename>Makefile</filename> + + Each individual document has its own + Makefile, which only needs to be a few + lines long. The document Makefile content + is designed for cut and paste operations. + + + below shows the whole + Makefile for a simple document with two + files and two translations. + + + Sample Document Makefile + + + + Do not be concerned with some of the more complicated syntax + such as the XMLFILES_template stanza. An + explanation for this template appears a few paragraphs + below. + + <systemitem class="macro">DOCBASE</systemitem> + This variable contains the name for the main (parent) XML + document. Follow convention by naming your document after the + module name. + + + <systemitem class="macro">PRI_LANG</systemitem> + This variable contains the ISO code for the original + version of the document, such as + en_US. + + + <systemitem class="macro">OTHERS</systemitem> + This variable contains a listing of ISO codes for any + other versions into which the document has been translated. + The module must contain a po/ directory and a PO file for + any indicated additional languages. + + + <systemitem class="macro">DOC_ENTITIES</systemitem> + This variable contains a listing of any files containing + entity definitions. The &FDP; uses a special XML format to + record document-specific entities, so they can be translated and + built on the fly like any other XML document. An example is + shown later in this guide. + + + <systemitem + class="macro">XMLFILES_template</systemitem> + This template allows the build tools to work with the + document in multiple languages once it is translated. The + ${1} marking is a + variable used to substitute the appropriate language. This + template is not terribly complicated. For a new module, + duplicate this section exactly except for the actual + filenames. Prepend the text ${1}/, in place of the language + code directory name, to each filename in your document. + + + + Files Exempt From Listing + Do not include the document-specific entities XML file or + the rpm-info.xml file, which will be + discussed later in this guide. + + + The final line, beginning with include, + references the main Makefile for the build + system. This Makefile.common file contains + all the make(1) targets and rules to + actually build the document and the various archives. + +
+
+ The Document <filename>rpm-info.xml</filename> + Each document module's primary language directory contains a + file called rpm-info.xml. This file + contains document-specific metadata used to generate revision + history, copyright, and contributor information. It follows a + DTD specification included with the rest of the build system + tools. + illustrates the content of + this file: + + Example <filename>rpm-info.xml</filename> File + + + + + + + + + + OPL + 1.0 + + + 2006 + John Q. Smith + + My Tutorial + A tutorial about something important + + + +
First draft
+ + +]]> + + If you are not familiar with XML editing, copy and paste + this file from an existing module and then edit the values for + the various elements as appropriate. Consult &FDP; members and + help channels for more assistance if needed. +
+
+
+ Build System Actions + + To render the XML document into another format, + use one of the following make targets: + + + <systemitem class="macro">html</systemitem> + This target builds the "chunked" HTML + document for each defined translation. Output is placed in a + separate directory named ${DOCBASE}-${LANG}/. Each + document section is a separate file within that + directory. + + + <systemitem + class="macro">html-nochunks</systemitem> + This target builds the "non-chunked" HTML + document for each defined translation. Output is placed in a + single file: ${DOCBASE}-${LANG}.html; no other + files are created. + + + <systemitem class="macro">pdf</systemitem> + This target builds only the PDF document + for all document languages. PDF production is + currently erratic and may not work for your document. + + + <systemitem class="macro">tarball</systemitem> + This target builds only the tar(1) + archive for all document languages. + + + <systemitem class="macro">all</systemitem> + This target builds all targets listed above. + + + <systemitem class="macro">clean</systemitem> + This target deletes any temporary, or generated files, but + does not erase any HTML, + PDF, or archive files. + + + <systemitem class="macro">distclean</systemitem> + This target erases all HTML, + PDF, and archive files. This target + automatically invokes the clean target as + well. + +
+ Adding or Changing Targets + + To add a new target and rules, place them at the bottom of the + document Makefile, below the + include line. Follow your target definitions + with a double colon, not a single colon. The double colon + allows you to specify additional rules for existing targets, or + to write rules for a new target. + + + For more information on using make(1), + consult the online documentation with the command info + make in a terminal. + +
+
+ Using Document Image Files + + Tutorial documents often make use of images such as .PNG files. Store image files in + a figs/ folder in the + main module directory, as shown in . + + + Depending on the output media, sometimes images may be scaled, + streteched, or squashed. To minimize any distortions, we + recommend that you use only .PNG images. Avoid .JPG files. The + convert(1) program, from the ImageMagick RPM package, + provides a convenient way to reformat .JPG images into .PNG format. For more information + on formatting images such as screenshots, refer to . + + + Image files may be organized into subdirectories under + figs/ if necessary. The document building + system recreates the image subdirectory structure in the output + documents. + + + Images often contain labels or other text which may need to be + localized. A screenshot of a program, for example, may require + a version for each translated language. Name language-dependent + image files such as program screenshots by adding the language + code to the filename, such as + menu-en_US.png. Language-independent + images, such as icon.png, do not need + language codes. + + + Sometimes, a document may require images that do not follow the + naming convention. To use these images with the document + building system, create an ordinary text file containing the + image filenames. This file must be named + figs/Manifest-${LANG} so the build system finds + it when searching for image filenames. + + + + demonstrates one way to create this + Manifest file. + + + Building A Manifest + /tmp/manifest +mv /tmp/manifest figs/Manifest-en]]> + +
+
+ Adding a New DocBook XML File + To add a new DocBook XML file to an existing document, + follow these steps: + + + Place the new DocBook XML file in the primary language + directory. + + + Edit the Makefile and add the + filename to the XMLFILES-${1} listing. + Append a \ to the last existing line, and + on the next line add an entry for the new file. Remember to + add the ${1}/ prefix as a substitute for + the language directory name. + + +
+
+ Adding a Translation + Translations are stored as PO (portable object) files, which + the toolchain transforms into translated documents. Each PO + file is based on the POT (PO template) for the document and + translated by the &FED; Translation Project. To add a + translation, follow these steps: + + + If the po/ + directory does not exist, create it and add it to + CVS: + + + + If it does not exist, create the POT file: + + + + Add the new translation language to the + OTHERS listing in the + Makefile. + + + Although translators often copy the POT manually to + create the new PO file, the following command also + works: + make po/lang.po + + +
+
+ + + diff --git a/en_US/style.xml b/en_US/style.xml new file mode 100644 index 0000000..4d78392 --- /dev/null +++ b/en_US/style.xml @@ -0,0 +1,1973 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + + + 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/en_US/tutorial.xml b/en_US/tutorial.xml new file mode 100644 index 0000000..eab29a6 --- /dev/null +++ b/en_US/tutorial.xml @@ -0,0 +1,108 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + 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/en_US/vim.xml b/en_US/vim.xml new file mode 100644 index 0000000..eaace93 --- /dev/null +++ b/en_US/vim.xml @@ -0,0 +1,156 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + + 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/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml new file mode 100644 index 0000000..64f2736 --- /dev/null +++ b/en_US/writing-guidelines.xml @@ -0,0 +1,535 @@ + + +%FEDORA-ENTITIES-EN; + +]> + + + &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: + + + +
+ +
]]> + + IDs are unique identifiers, allowing DocBook XML to know where + to cross-reference a section or chapter or the like. The + following general rules apply to IDs: + + + XML tags + rules for defining an ID + + + + naming conventions + rules for defining an ID + + + + + Restrict the ID name, which is everything between the + quotation marks, to 32 characters or fewer + + + Keep it as short and simple as possible + + + Make sure the name is recognizable and relevant to the + information + + + + Some examples are "ch-uniquename" (13 + characters) and "sn-install-make-disks" (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: + + ]]> + + 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: + + ]]> + + + + + 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 + Body of text goes here. +]]> + + + Note + Body of text goes here. + + + + Tip + Body of text goes here. +]]> + + + Tip + Body of text goes here + + + + Caution + Body of text goes here. +]]> + + + Caution + Body of text goes here. + + + + Important + Body of text goes here. +]]> + + + Important + Body of text goes here. + + + + Warning + Body of text goes here. +]]> + + + 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 . + + + + + + + + + + diff --git a/en_US/xml-tags.xml b/en_US/xml-tags.xml new file mode 100644 index 0000000..7390c1d --- /dev/null +++ b/en_US/xml-tags.xml @@ -0,0 +1,2509 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + + 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 + + + Most tags in XML must have an opening and closing tag. A few + tags, such as xref, have no + content and close themselves. 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 content inside screen tags + (<screen> and </screen>) + must be flush left in the XML file; + 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: xml-tags.xml,v 1.1 2007/02/03 22:21:58 kwade 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, set + everything within that screen to flush left. The contents of + the screen element are + rendered exactly as is, including any indentation. Using flush + left prevents extra blank space in front of the text inside the + gray background when the content is converted to HTML. + + + + + 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