From 2fbd41eeebe2d59d480f9971dbadd2683ccd87a5 Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Fri, 29 Jun 2007 00:10:59 +0000 Subject: Some content updates, push new bugfix rev 0.3.0.1, no publishing needed yet --- en_US/getting-files.xml | 124 ++++++++++++++++++++++++++++++++++--------- en_US/module-struct.xml | 31 ++++++++--- en_US/rpm-info.xml | 4 ++ en_US/writing-guidelines.xml | 87 ++++++++++++++++-------------- 4 files changed, 174 insertions(+), 72 deletions(-) diff --git a/en_US/getting-files.xml b/en_US/getting-files.xml index 81a777c..21c6481 100644 --- a/en_US/getting-files.xml +++ b/en_US/getting-files.xml @@ -16,7 +16,7 @@ tools. Follow the directions below to configure your system. -
+
System Packages @@ -59,42 +59,114 @@
-
- Filename Conventions +
+ Naming Conventions - The &FDP; provides the tools, scripts, and stylesheets to transform your - XML documents into other output formats such as - HTML. In addition, these tools can build your document - into a RPM package. To take advantage of these - services, you must follow conventions for naming your files. + The &FDP; provides the tools, scripts, and stylesheets to + transform your XML documents into other output + formats such as HTML. In addition, these tools + can build your document into a RPM package. To + take advantage of these services, follow the conventions in this + section to name 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. Use - the cvs co -c command to view existing module names. - - - Partial List of CVS Modules - cd ~/localrepo/fedora-docs/ -developer-guide developer-guide + On the CVS server, directories that contain document files are + called modules. Each module represents a + single document. Each document may consist of several + branches if that document changes with each + release of &DISTRO;. Contributors can check out single branches + of these modules or the entire module. Each document or branch + may contain multiple XML source files. + Use the cvs co -c command to view existing + module names. + + Partial List of CVS Modules + cd ~/localrepo/fedora-docs/ + - +documentation-guide documentation-guide &docs-common]]> + + The leftmost entry in each line is the name of a module you + can check out from CVS. The rest of the line ensures that + checkouts include the proper branch of a document and the common + build tools. For more information on CVS, refer to . + Note in the listing above that the + about-fedora module has two branches + avalable. One branch is for &DISTRO; 7 and one is for forward + development to match the current work of developers. On the other + hand, the documentation-guide module is + not branched. +
+ Module Names Choose a module name that accurately reflects your - document's subject, but avoid any name already taken. + document's subject, but avoid any name already taken. The + document title without any use of the word + &FEDLC; is a reasonable choice in most + cases. Use the length descriptors + tutorial or + guide in the module name where + appropriate. Avoid Redundancy - Do not use the word &FED; to name + Do not use the word &FEDLC; to name modules in the &FDP; CVS repository. + + Correct Module Naming + Document Name + CVS Module Name + + Desktop User Guide + desktop-user-guide + + + Software Management with + Yum + yum-guide + + + Using Pup + pup-tutorial + + +
+
+ File Names + Follow these guidelines for naming files to make + collaboration and document reuse easy: + + + As with module names, avoid using the word + &FEDLC; in file names since it is + redundant. + + + If the document is comprised of many XML files, avoid + repeating the name of the document when naming the + constituent files. + + + Avoid numbering files to show order, since editors and + authors often rearrange documents or reuse their files in + other documents. + +
diff --git a/en_US/module-struct.xml b/en_US/module-struct.xml index 25851ec..46eea9b 100644 --- a/en_US/module-struct.xml +++ b/en_US/module-struct.xml @@ -19,7 +19,8 @@ Structure of a Module shows a directory tree of an example module, excluding any CVS folders: + class="directory">CVS folders. Note that this + example document does not have branches. Example Module Structure Translation (PO) directory optional The po/ directory - contains specially formatted files created and used by - translators. The &FDP; build tools use these files to create - translated versions of documents. The translated documents are - not stored in CVS; they are created as needed from these PO - files. + contains specially formatted Portable Object, or + PO, files created and used by translators. + The &FDP; build tools use these files to create translated + versions of documents. The translated documents are not stored + in CVS; they are created as needed from these PO files. Makefile @@ -97,13 +98,29 @@ document specific metadata + + Common Build Tools + Never add the docs-common build + tools directory to an individual module. Special formatting in + the module list downloads these tools when a user checks out a + document module. For more information, refer to . +
The Document Build System The build system can render the document into another format such as HTML or PDF, using - make(1) and shell scripts. Authors need + make(1) + In Linux and &DISTRO; documentation, references to + commands often include a number inside parentheses. This + number represents the section of + manpages that includes documentation + for that command. To read the manpage for + make(1), use the command man 1 + make. + and shell scripts. Authors need no prior experience with either shell scripts or a make(1). diff --git a/en_US/rpm-info.xml b/en_US/rpm-info.xml index cd047be..d8bc50e 100644 --- a/en_US/rpm-info.xml +++ b/en_US/rpm-info.xml @@ -33,6 +33,10 @@ Fedora Documentation Guide Guidelines and procedures for producing documentation for Fedora + + +
Assorted fixes to reflect newer version of reality
+ diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml index f6bf7ed..0691825 100644 --- a/en_US/writing-guidelines.xml +++ b/en_US/writing-guidelines.xml @@ -34,6 +34,26 @@ . +
+ File Header +
+ XML Header + In accordance with good XML practices, the first line in any + DocBook XML source files should identify the file as XML. Use + the following line as the first line of any new XML file: + ]]> +
+
+ CVS Id Header + All the files must contain the CVS Id header. Use the + following line as the second line of any new XML file: + ]]> + Any time the file is committed to CVS, the line is updated + automatically to include information about the file. For + example: + ]]> +
+
ID Naming Conventions @@ -132,7 +152,9 @@ How To Fold Laundry
Folding Shirts]]> - +
+
+ XML Tags xml tags caveats @@ -157,28 +179,31 @@ cannot be changed via the stylesheet. Instead, use the trademark tag and its - associates classes as follows: - - - - trademarktrademark symbol after - metrademark - - - - trademark - class="registered"registered trademark symbol - after metrademark - - - - trademark - class="copyright"copyright symbol after - metrademark - - - + associates classes as follows: + + DocBook XML source + Rendered content + + trademark symbol after + me]]> + trademark symbol after + me + + + registered trademark symbol after + me]]> + registered trademark + symbol after me + + + copyright + symbol after me]]> + copyright symbol after + me + + + Content inside para tags @@ -239,22 +264,6 @@
-
- File Header - - All the files must contain the CVS Id header. If you create a - new file, the first line must be: - - ]]> - - The first time it is committed to CVS (and every time it is - committed to CVS) the line is updated automatically to include - information about the file. For example: - - ]]> - -
-
Admonitions -- cgit