From cbbe56e0e1c55e880dc080379c3f75e3356e230f Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Thu, 23 Nov 2006 02:24:17 +0000 Subject: Add en_US directory, new file structures --- en_US/acknowledgments.xml | 45 + en_US/docs-emacs-nxml.xml | 340 ++++++ en_US/docs-emacs.xml | 735 ++++++++++++ en_US/docs-getting-files.xml | 422 +++++++ en_US/docs-intro.xml | 52 + en_US/docs-rh-guidelines.xml | 595 ++++++++++ en_US/docs-style.xml | 1974 ++++++++++++++++++++++++++++++++ en_US/docs-tutorial.xml | 108 ++ en_US/docs-vim.xml | 156 +++ en_US/docs-xml-tags.xml | 2500 +++++++++++++++++++++++++++++++++++++++++ en_US/documentation-guide.xml | 93 ++ en_US/rpm-info.xml | 37 + 12 files changed, 7057 insertions(+) create mode 100644 en_US/acknowledgments.xml create mode 100644 en_US/docs-emacs-nxml.xml create mode 100644 en_US/docs-emacs.xml create mode 100644 en_US/docs-getting-files.xml create mode 100644 en_US/docs-intro.xml create mode 100644 en_US/docs-rh-guidelines.xml create mode 100644 en_US/docs-style.xml create mode 100644 en_US/docs-tutorial.xml create mode 100644 en_US/docs-vim.xml create mode 100644 en_US/docs-xml-tags.xml create mode 100644 en_US/documentation-guide.xml create mode 100644 en_US/rpm-info.xml diff --git a/en_US/acknowledgments.xml b/en_US/acknowledgments.xml new file mode 100644 index 0000000..c7dc535 --- /dev/null +++ b/en_US/acknowledgments.xml @@ -0,0 +1,45 @@ + + Acknowledgments + + + This document is based on the a document started by Tammy Fox (tfox at + redhat.com) and contributed to by Sandra Moore (smoore at redhat.com) and + Johnray Fuller (jrfuller at redhat.com). + + + + A patch from Roozbeh Pournader (roozbeh at sharif.edu) has been applied to + fix a few typos and explain that anonymous CVS access does not allow + commits. + + + + Patches from Gavin Henry (ghenry at suretecsystems.com) have been applied + to add the trailing slashes to the figure tag example + in docs-xml-tags.xml and to add . + + + + A patch from Joshua Daniel Franklin (joshuadfranklin at yahoo.com) has been + applied to add . + + + + A patch from Karsten Wade (kwade at redhat.com) has been applied to add + . It was edited by Paul + W. Frields (stickstr5 at hotmail.com). + + + + A patch from Paul W. Frields (stickstr5 at hotmail.com) has been applied + to add more explanation of the screen tag set to . + + + + A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been + applied to more fully explaing the document building system. + + + diff --git a/en_US/docs-emacs-nxml.xml b/en_US/docs-emacs-nxml.xml new file mode 100644 index 0000000..5cc9dac --- /dev/null +++ b/en_US/docs-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/docs-emacs.xml b/en_US/docs-emacs.xml new file mode 100644 index 0000000..8a48c90 --- /dev/null +++ b/en_US/docs-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/docs-getting-files.xml b/en_US/docs-getting-files.xml new file mode 100644 index 0000000..6e762ea --- /dev/null +++ b/en_US/docs-getting-files.xml @@ -0,0 +1,422 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + Prerequisites + + + To work on official &FED; documentation you need to install the required + tools. The directions below will help you configure your setup. + + +
+ 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.fedora.redhat.com 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=:pserver:anonymous@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 these steps only once. 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 either HTML or + PDF output formats. In addition, these tools can build + your document into an 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 it creates unnecessary confusion. + + +
+
+ Anticipating I18N Translation + + The &FDP; includes an active translation team. Project documents are + often translated into several languages. By convention, the translated + files share the directory with the original files. Therefore, filenames + must be unique. + + + To construct a filename, append a dash followed by the + ISO language symbol before any file extension. For + example, a file whose language content is U.S. English + might be named mydoc-en.xml, its Chinese + translation named mydoc-zh_CN.xml, and so on. + + + To assist this effort, the document build system assumes that each file + is tagged with its I18N locale. Our filename + convention is shown in . + + + &FDP; Filename Conventions + + + + + + + Compoment + + + Description + + + + + + + anything_but_dash + + + + The initial portion of a filename can be anything, as long as + no dash is used. + + + + + + - + + + + A dash (-) is to be used only to + introduce the ${LANG} + filename component. + + + + + + ${LANG} + + + + The ${LANG} component + identifies the locale for the file + content. + + + In addition to helping classify files according to their + language content, we also use the ${LANG} value as an + UTF-8 locale when rendering the document. + For example, the document + mydoc-it.xmlwill be rendered using + it.UTF-8 as the + language environment. + + + For more information on I18N localization, + visit the web site. + + + + + +
+ + Document Filenames Are Special + + The main file in your document must follow the + file naming convention or the document building system cannot find it. + + +
+
+
+ The Document Build System + + Common tasks such as rendering the document into either HTML or PDF can be performed easily using the document building system. + + + The building system heavily leverages the make(1) tool and shell scripts to automate these activities, but authors need no prior experience with either shell scripts or a Makefile. + While individual documents do have their own Makefile, it is only a few lines long and very simple. + The document Makefile content is designed for cut'n paste. + + + As an example, shows the whole Makefile for a simple document having only one file and one language. + + + Sample Document Makefile + +DOCBASE = mydoc +LANGUAGES = en +XMLEXTRAFILES-en= +include ../docs-common/Makefile.common + + + + Our main XML file is mydoc-en.xml; no translation has been done yet. + + + The LANGUAGES definition lists the English locale en; when other translations become available, their locale will just be appended to this definition. + + + Our document has only the main file mydoc-en.xml, but other documents may be split over several files. + The XMLEXTRAFILES-en definition catalogs these additional files so that the document building system can watch them for changes and rebuild the document when necesssary. + This definition is just a simple list of files. + + + The final line, beginning with include, references the main Makefile for the build system. + The Makefile.common file contains all the make(1) targets and rules to actually build the document and the various archives. + + + Add new document translations by: + + + + + Add the translated document files to the document directory. + Be sure to use the proper ${LANG} filename component to keep the filenames similar, but unique. + + + + + Edit the Makefile to append the new ${LANG} to the LANGUAGES definition. + + + + + Create a new XMLEXTRAFILES-${LANG} definition that references any document files other than the base file. + + + +
+ Build System Actions + + To render the XML document into HTML or PDF the command: make html, + make html-nochunk, or make pdf may be used. + + + lists the defined build system targets. + + + Document Building Targets + + + + + + Target + Description + + + + + all + + + Builds the HTML, and the PDF forms of the document in all its defined translations. + + + Also builds the archives, such as tar(1) and rpm(8). + + + + + tarball + + + Builds only the tar(1) archive for all document languages. + + + + + pdf + + + Builds only the PDF document for all document languages. + + + Currently, PDF production is problematic and probably will not work for your document. + + + + + html + + + Builds only the HTML document for each defined translation. + Output is placed in a separate directory: + ${DOCBASE}-${LANG}/; each document section is given its own file within that directory. + + + + + html-nochunks + + + Builds only the HTML document for each defined translation. + Output is placed in a single file: + ${DOCBASE}-${LANG}.html; no other files are created. + + + + + clean + + + Deletes any temporary, or generated files. + Does not erase any HTML, PDF, or archive files. + + + + + distclean + + + Erases all HTML, PDF, and archive files. + Automatically invokes the clean target as well. + + + + + +
+ + You can add your own special targets and rules by placing them at the bottom of the document Makefile, below the include line. + + + Be sure to follow your target definitions with a double colon, not just one. + This will allow you to supply extra steps for the defined targets. + +
+
+ Using Document Image Files + + Image files, such as .PNG, are often used in documents. + While your image files may be placed anywhere you like, we recommend that you store your image files in a figs/ subdirectory within your document directory. + In other words, place your image picture.png in the mydoc/figs/picture.png file. + + + Use PNG Images, Not JPG + + Depending on the output media, sometimes images may be scaled, + streteched, or squashed. + To minimize any distortions, we recommend that you use only + PDF images and avoid JPG files. + + + You may find the convert(1) program, from the ImageMagick RPM package, provides a convenient way to reformat any JPG images you already have. + + + + You may organize your image files into as many subdirectories under figs/ as you choose. + The document building system will recreate your image subdirectory structure in the output documents. + + + In addition, we recommend that you follow our convention on naming the image. + For example, an image often contains a caption or other text. + This text should be translated along with the document content, so keeping words-en.png separate from words-ru.png is a good practice. + An image file with no text can be named just picture.png, for example. + + + Sometimes, a document may require images that do not follow the naming convention. + You may still use these images with the document building system, but it requires that you create an ordinary text file containing the image filenames you want to use. + This file must be named figs/Manifest-${LANG} so that the build system can find it as the search for image filenames begins. + + + An easy way to create the figs/Manifest-${LANG} file is shown in . + + + Building A Manifest + +rm -f figs/Manifest-en +find figs -print >/tmp/manifest +mv /tmp/manifest figs/Manifest-en +vi figs/Manifest-en + + + +
+
+ + + diff --git a/en_US/docs-intro.xml b/en_US/docs-intro.xml new file mode 100644 index 0000000..98bc113 --- /dev/null +++ b/en_US/docs-intro.xml @@ -0,0 +1,52 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + + Introduction + + + The goal of the Docs Project is to create easy-to-follow, task-based + documentation for &FC; users and developers. Other than the + &IG;, each tutorial should be in DocBook XML + article format, with one article per topic. This way, writers can + contribute documentation about a specific topic without having to worry + about how it fits into a manual or how it flows with other topics. + + + + The following tools are used: + + + + + DocBook XML v4.1 + + + Custom XSLT stylesheets for both print and HTML versions + + + Custom scripts to generate PDF and HTML output (use xmlto) + + + Emacs with PSGML mode (optional, but recommended) + + + Emacs with nXML mode (optional, but also recommended) + + + + + The purpose of this document is to explain the tools used by the Docs + Project as well as to provide writing and tagging guidelines so that the + documentation is consistent and easy-to-follow. + + + diff --git a/en_US/docs-rh-guidelines.xml b/en_US/docs-rh-guidelines.xml new file mode 100644 index 0000000..c0ee606 --- /dev/null +++ b/en_US/docs-rh-guidelines.xml @@ -0,0 +1,595 @@ + + +%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: + + + + +<chapter id="ch-uniquename"> + +<sect3="s3-install-make-disks"> + +<figure id="fig-redhat-config-kickstart-basic"> + + + + IDs are unique identifiers, allowing DocBook XML to know where to + cross-reference a section or chapter or the like. + + + The general rules for defining an ID are: + + + XML tags + rules for defining an ID + + + + naming conventions + rules for defining an ID + + + + + Keep it 32 characters or under (this is counted as + everything between the quotation marks) + + + Keep it as short and simple as possible + + + Make sure the name is relevant to the information (make it + recognizable) + + + + Some examples are "ch-uniquename" (with 13 + characters) and "s3-install-make-disks" (with 21 + characters). + + + A section within a particular chapter always uses the chapter + name (minus the "ch-") in its ID. For example, you + are working with the "ch-intro" chapter and need to + create your first section on disk partitions. That section ID would look + similar to "s1-intro-partition" which contains the + section number, the main chapter ID, and a unique ID for that section. + + + + Naming Conventions + + + + + + + Tag + Prefix + + + + + preface + pr- + + + chapter + ch- + + + section + sn- + + + sect1 + s1- + + + sect2 + s2- + + + sect3 + s3- + + + sect4 + s4- + + + figure + fig- + + + table + tb- + + + appendix + ap- + + + part + pt- + + + example + ex- + + + +
+ + + + + File Header + + + All the files must contain the CVS Id header. + + + + If you create a new file, the first line must be: + + + +<!-- $Id: --> + + + + + The first time it is committed to CVS (and every time it is committed to + CVS) the line is updated automatically to include information about the + file. For example: + + + + +<!-- $Id: docs-rh-guidelines.xml,v 1.1 2006/11/23 02:24:17 pfrields Exp $ --> + + + + + + + Admonitions + + + admonitions + + + + XML tags + warning + + + + XML tags + tip + + + + XML tags + note + + + + XML tags + caution + + + + XML tags + important + + + + XML tags + admonitions + warning + + + + XML tags + admonitions + tip + + + + XML tags + admonitions + note + + + + XML tags + admonitions + caution + + + + XML tags + admonitions + important + + + There are five types of admonitions in DocBook: Caution, Important, + Note, Tip, and Warning. + + All of the admonitions have the same structure: an optional Title + followed by paragraph-level elements. The DocBook DTD does not impose any + specific semantics on the individual admonitions. For example, DocBook + does not mandate that Warnings be reserved for cases where bodily harm can + result. + + + + Creating Notes, Tips, Cautions, Importants, and Warnings + + + XML tags + note + + + + XML tags + tip + + + + XML tags + caution + + + + XML tags + important + + + + XML tags + warning + + + There are several ways to bring attention to text within a + document. A Note is used to bring additional + information to the users' attention. A Tip is + used to show the user helpful information or another way to do + something. A Caution is used to show the user + they must be careful when attempting a certain step. An + Important tag set can be used to show the user a + piece of information that should not be overlooked. While this + information may not change anything the user is doing, it should show + the user that this piece of information could be vital. A + Warning is used to show the reader that their + current setup will change or be altered, such as files being removed, + and they should not choose this operation unless they are alright with + the consequences. + + The following lines of code will show the basic setup for each + case as mentioned above, along with an example of how it would be + displayed in the HTML. + + + + +<note> +<title>Note</title> +<para>Body of text goes here.</para> +</note> + + + + + Note Body of text goes here. + + + + + +<tip> +<title>Tip</title> +<para>Body of text goes here.</para> +</tip> + + + + + Tip + Body of text goes here + + + + +<caution> +<title>Caution</title> +<para>Body of text goes here.</para> +</caution> + + + + + Caution Body of text goes here. + + + + + +<important> +<title>Important</title> +<para>Body of text goes here.</para> +</important> + + + + + Important + Body of text goes here. + + + + +<warning> +<title>Warning</title> +<para>Body of text goes here.</para> +</warning> + + + + + Warning Body of text goes here. + + + + + + + Screenshots + + + screenshots + how to take + + + screen captures + screenshots + + + screen grabs + screenshots + + + + There are two types of screenshots: graphical and textual. The + philosophy on using these two types is rely on text over + graphics. This means, if you can say it in text instead of + showing a graphic, do so. A graphical screenshot of a GUI can create a good + setting of objects to then describe textually, but you don't want to create + a screenshot for each graphical step. + + + The main reason for this preference is that a block of text can usually + convey more meaning than the same physical space of graphics. This is + highly dependent on the graphic; obviously, a photographic image of a + scene can convey more than 1000 words can. A GUI screenshot is usually + full of blank space with a few elements that can just as easily be + described or listed. + + + The steps for taking a graphical screenshot illustrate how using text to + describe a procedure is more concise than a series of screenshots. + + + + Graphical Screenshot + + + + + Set the theme to Bluecurve defaults. This gives a look that + is familiar to most readers, and makes &FDP; documents + consistent. From the panel menu, choose + Preferences, + Theme and select + Bluecurve from the theme list. + + + + + Set fonts to Bluecurve defaults as well. From the panel menu, + choose Preferences, + Fonts. Set the + Application font and the + Desktop font to Sans Regular 10. Set the + Window Title font to Sans Bold 10. Set + the Terminal font to Monospace Regular + 10. + + + + + Before taking the screenshot, try to resize the targeted GUI + element(s) to the smallest possible size they can be. Your + target is an image of 500 pixels or less. If you are doing a + screenshot of more than one GUI element, you may need to + resize the screenshot in a following step. + + + + + To take the screenshot, select the GUI element with your + mouse, bringing it to the forefront, or otherwise arranging + the elements. Press Alt + Print Screen to capture a single + GUI window. For capturing the entire desktop use + Print Screen. If you are taking a shot of + multiple elements and have grouped them closely together, you + can crop the resulting image in The + GIMP. The image will be in the PNG format. + + + + + If you need to, you can resize using The + GIMP. With the image open, right-click on it + and choose Image -> Scale + Image.... With the chain symbol intact, set the + New Width to 500 px, + and click OK. Be sure to + Ctrl s to save + your changes to your PNG before converting to EPS. + + + + + With the image open in The GIMP, + right-click on the image, selecting File + -> Save As.... Under + Determine File Type:, select + PostScript, then click + OK. Allow flattening of the image by + clicking Export. + + + In the Save as PostScript window, select + Encapsulated PostScript, and click + OK. + + + + + For more information about calling the images from the XML, refer + to . + + + + + Text Screenshot + + Textual screen information is also useful for readers. If you + use a graphical screenshot to illustrate a function, and the + textual mode has identical functions, you should not include + both, unless omitting either would make your description + unclear. You should make your information generic over specific. + Omit the username and machine information, and separate what the + user types from sample command output. Also, in + screen tags, what the user types should be in + userinput tags, and what the user is shown as + output should be in computeroutput tags. + For example, the usage in + should look like . + + + Incorrect Textual Screenshot + +ps ax | grep ssh + + 2564 ? S 0:23 /usr/sbin/sshd + 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients + 8235 ? S 0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost +17223 pts/0 S 0:00 ssh rbalboa@core-router7 +17227 pts/2 S 0:10 ssh rbalboa@smbshare2 +21113 pts/7 S 1:19 ssh rocky@xxx.private + + + + + Correct Textual Screenshot + + To find all the currently active ssh sessions, execute the + following command: + + +ps ax | grep ssh + + + + The output will appear similar to: + + + + + 2564 ? S 0:23 /usr/sbin/sshd + 3092 ? S 0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients + 8032 pts/0 S 0:00 ssh user@host.example.com + 8032 pts/1 S 0:00 ssh root@backup.example.com + + + + + For more information about using screen, refer to . + + + + + + + + Diagrams and Images + + + images + + + diagrams + creating + + + + To be written + + + + + + + + + diff --git a/en_US/docs-style.xml b/en_US/docs-style.xml new file mode 100644 index 0000000..a6bdec3 --- /dev/null +++ b/en_US/docs-style.xml @@ -0,0 +1,1974 @@ + + + +%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 new file mode 100644 index 0000000..7944e62 --- /dev/null +++ b/en_US/docs-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/docs-vim.xml b/en_US/docs-vim.xml new file mode 100644 index 0000000..9175aef --- /dev/null +++ b/en_US/docs-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/docs-xml-tags.xml b/en_US/docs-xml-tags.xml new file mode 100644 index 0000000..f46ac96 --- /dev/null +++ b/en_US/docs-xml-tags.xml @@ -0,0 +1,2500 @@ + + + +%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 + + + All tags in XML must have an opening and closing tag Additionally, + proper XML conventions say that there must be a unique identifier for + sections, chapters, figures, tables, and so on, so that they may be + correctly identified, and cross referenced if needed. + + Although XML is capable of handling many document types, the format + discussed here is the article format. + + + This chapter only discusses tags used for documentation for the &PROJECT;, + not all available DocBook XML tags. For the complete list, refer to: + + + +http://www.docbook.org/tdg/en/html/docbook.html + + + + + Tags and Entities Caveats + + + xml tags + caveats + + + + It is very important that you remember the caveats in this section. Even + though they are more strict than valid DocBook XML, these rules exist + so that both the HTML and PDF outputs look proper. + + + + + Do Not Use Trademark Entities + + Do not use the trademark entities &trade;, &copy;, or + &reg; because the do not produce HTML output that works for all + charsets. The HTML output produces by these entities are declared in + the DTD and cannot be changed via the stylesheet. + Instead, use the trademark tag and its + associates classes as follows: + + + + <trademark>trademark symbol after me</trademark> + + + + <trademark class="registered">registered trademark symbol after me</trademark> + + + + <trademark class="copyright">copyright symbol after me</trademark> + + + + + + Content inside para tags + + Do not use para tags around anything other + than a simple paragraph. Doing so will create additional white space + within the text itself in the PDF version. + + Specifically, do not use para tags around + the following (or, to put this another way, do not embed the + following within para tags): + + + + <screen> + + + <itemizedlist> + + + <orderedlist> + + + <variablelist> + + + <table> + + + + + + Content inside para tags within + listitem tags + + Content inside para tags within + listitem tags must start + immediately after the beginning <para> tag to avoid extra + white space in the PDF version. + + + + + Content inside screen tags + + The screen tags (<screen> and + </screen>) must be flush left in the + XML file, and all the content inside the + screen tags must be flush left as well unless + the white space in intentional; otherwise, the extraneous + whitespace will appear in the HTML version. + + + + + + + + + <command>application</command> + + + XML tags + application + + + An application is the name of a GUI software program. A command is + the name of an executable (text) program or a software command. + + The <application> and + </application> tags allow you to refer to an + application or program. For example, the following XML: + + + + +To view the Web in Linux, you can use +<application>Mozilla</application> or +<application>lynx</application> if you only want a text-based +browser. + + + + + produces the following output: + + + + To view the Web in Linux, you can use Mozilla + or lynx if you only want a text-based browser. + + + + + + <command>chapter</command> + + + XML tags + chapter + + + + A DocBook book can be divided into chapters such as: + + + + +<!--$Id: docs-xml-tags.xml,v 1.1 2006/11/23 02:24:17 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, you must set + everything within that screen, including the + <screen> tags themselves, to flush left. This + must be done so that when it is converted to HTML, it will not have + extra blank space in front of it inside the gray background. + + + + + The <screen> tag set may contain other inline + tags, such as <computeroutput>, + <userinput>, or + <replaceable>. Additional inline tags are not + required by definition. The <screen> tags by + themselves may provide sufficient context, especially for simple examples + or file listings. Consider the context of the example, and use inline tags + if they are helpful to the reader. + + + + If you use inline tags, remember that line breaks inside + <screen> tags create line breaks in any rendered + output. Place any inline tags on the same line as + their content. Do not overuse tagging within a + <screen> tag set. + + + + An example of <screen> is the following: + + + +<screen> +This is an example of a screen. You do not need &lt;para&gt; tags +within this command. +</screen> + + + + The output: + + + +This is an example of a screen. You do not need <para> tags +within this command. + + + + Using Inline Tags with <command>screen</command> + + If you choose to use inline tags inside a + <screen> section, follow these guidelines for + consistency. If the content in the screen is a listing of a + configuration file or the output of a program, use the + <computeroutput> tag set around the entire + output. If the user should type the example on the command line or in + a configuration file, use the <userinput> tag + set. Separate input and output with a short sentence of narrative, as + below: + + + + <para> + Type the following command: + </para> + +<screen> +<userinput>command -sw file1</userinput> +</screen> + + <para> + You should see the following output: + </para> + +<screen> +<computeroutput>Completed, time = 0.12 sec</computeroutput> +</screen> + + + + The output looks like: + + + + Type the following command: + + + +command -sw file1 + + + + You should see the following output: + + + +Completed, time = 0.12 sec + + + + Note + + When showing a command or series of commands inside + screen tags, do not show the prompt. + + + + + If the <screen> shows the reader how to + change only part of a line, mark the change with + an inline <userinput> tag set. You may use + the <userinput> tag set inside a larger area + that is already marked inline with + <computeroutput>. Do not include any extra + lines of context in this case, unless excluding them would confuse the + reader. The following example illustrates these guidelines: + + + + <para> + Edit the <filename>/etc/sysconfig/init</filename> file as follows: + </para> + +<screen> +GRAPHICAL=<userinput>yes</userinput> +</screen> + + + + The output looks like: + + + + Edit the /etc/sysconfig/init file as follows: + + + +GRAPHICAL=yes + + + + For an explanation of how to use the replaceable + tags within a set of screen tags, refer to . + + + + + + + Sections + + + XML tags + sections + + + + sections + + + Within an article (or chapter if it is a DocBook XML book like the + &IG;), you can have sections and + subsections. <sect1> is always the highest + section and you cannot have two sections of the same level within one + another (a section 2 can be created within a section 1, but section 1 + has to be closed before another section 1 can be created). The general + layout follows: + + + +<sect1 id="s1-uniquename"> + <title>Insert Title Here</title> + <para> + Body text goes here. + </para> + + + <sect2 id="s2-uniquename"> + <title>Insert Title Here</title> + <para> + Body text goes here. + </para> + + <sect3 id="s3-uniquename"> + <title>Insert Title Here</title> + <para> + Body text goes here. + </para> + + </sect3> + + </sect2> + +</sect1> + + + + + If you only need one level of sections in a DocBook article, you can use + the section tag. For example: + + + + +<section id="sn-uniquename"> + <title>Insert Title Here</title> + <para> + Body text goes here. + </para> +</section> +<section id="sn-anothername"> + <title>Insert Title Here</title> + <para> + More body text goes here. + </para> +</section> + + + + + + <command>table</command> + + + XML tags + table + + + + The following is an example of creating a table. + + + +<table id="tb-mockup-before-begin"> + This tells XML that you will be creating a table + and the ID name is "tb-mockup-before-begin." + +<title>Available Features of GNOME and KDE</title> + +<tgroup cols="3"> + This tells XML that you are creating a table + with three columns. + +<colspec colnum="1" colname="Features" colwidth="3"/> + colspec says that you are giving information + about the column to XML colnum="1" + says that you are giving specifications for the first column. + + colname="Features" says that the title for this + column will be "Features." + + colwidth="3" specifies the width of the + column. This can be more tricky: such as two columns with + widths of 1 and 2,the 1 is one-half the width of the 2, in + respect to the page size. But, what if you need the 1 to be a + little more than half of the 2, using a larger number ratio, + such as 10 to 20 would accomplish this. You could then change the + 10 to an 11 or a 12 to make it a little more than half of the + second column of 20. In no value is given, a value of 1 is + assumed. + +<colspec colnum="2" colname="GNOME" colwidth="2"/> +<colspec colnum="3" colname="KDE" colwidth="2"/> + +<thead> + Contains one or more table row elements. + +<row> + Contains one or more table cell (entry) elements. + +<entry>Features</entry> + Table cell element, one of several in a row element, defining + columns within the row. + +<entry>GNOME</entry> +<entry>KDE</entry> +</row> +</thead> + +<tbody> + Contains one or more row elements, for the main text + of the table. + +<row> +<entry>highly configurable</entry> +<entry>yes</entry> +<entry>yes</entry> +</row> +<row> +<entry>multiple window managers </entry> +<entry>yes</entry> +<entry>yes</entry> +</row> +<row> +<entry>Internet applications</entry> +<entry>yes </entry> +<entry>yes </entry> +</row> +</tbody> +</tgroup> +</table> + + + + Available Features of GNOME and KDE + + + + + + + + + Features + GNOME + KDE + + + + + + highly configurable + yes + yes + + + multiple window managers + yes + yes + + + Internet applications + yes + yes + + + +
+ + + Creating a List Within a Table + + + XML tags + table + list within a table + + + + Creating a list within a table can be a difficult task. It + requires strict formatting and a set of commands that are not + available for command completion in + Emacs. + + The tags you will need to use are + <simplelist> and + <member>. + + The following example will show you the proper formatting for + creating a list within a table. + + + + +<table id="tb-hardware-powerswitch"> + <title>Power Switch Hardware Table</title> + <tgroup cols="4"> + <colspec colnum="1" colname="Hardware" colwidth="2"/> + <colspec colnum="2" colname="Quantity" colwidth="2"/> + <colspec colnum="3" colname="Description" colwidth="6"/> + <colspec colnum="4" colname="Required" colwidth="2"/> + + <thead> + <row> + <entry>Hardware</entry> + <entry>Quantity</entry> + <entry>Description</entry> + <entry>Required</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>Serial power switches</entry> + + <entry>Two</entry> + + <entry><simplelist> <member>Power switches enable each cluster system + to power-cycle the other cluster system. Note that clusters are + configured with either serial or network attached power switches and + not both.</member> + + <member>The following serial attached power switch has been + fully tested:</member> + + <member>RPS-10 (model M/HD in the US, and model M/EC in + Europe) </member> + + <member>Latent support is provided for the following serial + attached power switch. This switch has not yet been fully + tested:</member> + + <member>APC Serial On/Off Switch (partAP9211), <ulink + url="http://www.apc.com/">http://www.apc.com/</ulink></member> + </simplelist></entry> + + <entry>Strongly recommended for data integrity under all failure + conditions</entry> + + </row> + </tbody> + </tgroup> +</table> + + + + Notice how the <simplelist> tag must be + beside the <entry> tag? If you do not format + this properly, it will not parse cleanly. + + The above example will look like the following: + + + Power Switch Hardware Table + + + + + + + + + Hardware + Quantity + Description + Required + + + + + + + Serial power switches + + Two + + Power switches enable each cluster + system to power-cycle the other cluster system. Note + that clusters are configured with either serial or + network attached power switches and not both. + + The following serial attached power switch has been + fully tested: + + RPS-10 (model M/HD in the US, and model M/EC in + Europe) + + Latent support is provided for the following + serial attached power switch. This switch has not yet + been fully tested: + + APC Serial On/Off Switch (partAP9211), http://www.apc.com/ + + + Strongly recommended for data integrity under all failure + conditions + + + + +
+ + + + + + + <command>trademark</command> + + + XML tags + trademark + + + + Do not use the trademark entities &trade;, &copy;, or + &reg; because the do not produce HTML output that works for all + charsets. The HTML output produces by these entities are declared in + the DTD and cannot be changed via the stylesheet. + + Instead, use the trademark tag and its + associates classes as follows: + + + + +<trademark>trademark symbol after me</trademark> +<trademark class="registered">registered trademark symbol after me</trademark> +<trademark class="copyright">copyright symbol after me</trademark> + + + + + + + <command>userinput</command> + + + XML tags + userinput + + + + To show what a user would type, use the userinput + tag. For example: + + + +At the prompt, type: + +<userinput>dd if=boot.img of=/dev/fd0 bs=1440k</userinput> + + + + + The output: + + + + At the prompt, type: + + + + dd if=boot.img of=/dev/fd0 bs=1440k + + + + + + + + <command>ulink</command> + + + XML tags + ulink + + + + To create a URL link within your text, use the following example: + + + +Online &mdash; <ulink url="http://www.redhat.com/support/errata/"> +http://www.redhat.com/support/errata/</ulink>; supplies errata +you can read online, and you can download diskette images easily. + + + + + The output: + + + + Online — + http://www.redhat.com/support/errata/; supplies errata + you can read online, and you can download diskette images easily. + + + + Note + + If the URL does not end in a filename, it must end in a slash + (/) to be a properly formed URL. For + example, http://www.redhat.com/. + + + + + + + <command>wordasword</command> + + + XML tags + wordasword + + + The <wordasword> tag set is used to define a word meant + specifically as a word and not representing anything else. + + A lot of technical documentation contains words that have overloaded + meanings. Sometimes it is useful to be able to use a word without invoking + its technical meaning. The <wordasword> element identifies a word or + phrase that might otherwise be interpreted in some specific way, and + asserts that it should be interpreted simply as a word. + + It is unlikely that the presentation of this element will be able to + help readers understand the variation in meaning; good writing will have + to achieve that goal. The real value of <wordasword> lies in the + fact that full-text searching and indexing tools can use it to avoid + false-positives. + + For example: + + +To use <command>grep</command> to search for the word +<wordasword>linux</wordasword>, use the command +<command>grep linux</command>. + + + + The output: + + + To use grep to search for the word + linux, use the command grep + linux. + + In the example, the word "linux" is just a word. It is not + meant to convey anything about Linux as a subject, or to add relevance or + meaning to the content. It can be replaced with any other word without + losing any of the context. + + + + + + <command>xref</command> + + + XML tags + xref + + + + To refer to other sections or chapters within a manual, use the + <xref> tag. + + + + The output of this displays the title of the section or chapter you are + pointing the user to. For example: + + + +For more information about the parent file, refer to +<xref linkend="ch-tutorial"></xref> and <xref linkend="s1-tutorial-parent"></xref> + + + + + The output: + + + + For more information about the parent file, refer to + and . + + + + diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml new file mode 100644 index 0000000..55b5f1f --- /dev/null +++ b/en_US/documentation-guide.xml @@ -0,0 +1,93 @@ + + + + +%FEDORA-ENTITIES-EN; + + + + + +]> + + + + &FP; Documentation Guide + Version &VERSION; + + 2003 + 2004 + 2005 + &FORMAL-RHI; + Tammy Fox + Johnray Fuller + Sandra Moore + Paul W. Frields + + + + Fox + Tammy + + + Fuller + Johnray + + + Moore + Sandra + + + Frields + Paul + W. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/en_US/rpm-info.xml b/en_US/rpm-info.xml new file mode 100644 index 0000000..27559aa --- /dev/null +++ b/en_US/rpm-info.xml @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + OPL + 1.0 + + + 2003 + 2004 + 2005 + 2006 + &FORMAL-RHI; + Tammy Fox + Johnray Fuller + Sandra Moore + Paul W. Frields + + Fedora Documentation Guide + Guidelines and procedures for producing documentation for &FED; + + -- cgit