From 4094bdde5960e97dea463a4c6b3bcc4cf5eee444 Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Wed, 29 Nov 2006 22:18:53 +0000 Subject: Exclude nxml chapter for now, and reorganize first chapter --- en_US/acknowledgments.xml | 4 +- en_US/docs-getting-files.xml | 333 ++-------------------------------------- en_US/docs-module-struct.xml | 348 ++++++++++++++++++++++++++++++++++++++++++ en_US/documentation-guide.xml | 11 +- 4 files changed, 372 insertions(+), 324 deletions(-) create mode 100644 en_US/docs-module-struct.xml (limited to 'en_US') diff --git a/en_US/acknowledgments.xml b/en_US/acknowledgments.xml index 9a71775..47a3f11 100644 --- a/en_US/acknowledgments.xml +++ b/en_US/acknowledgments.xml @@ -25,8 +25,8 @@ 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 . + in docs-xml-tags.xml. diff --git a/en_US/docs-getting-files.xml b/en_US/docs-getting-files.xml index 6e762ea..c86a6d4 100644 --- a/en_US/docs-getting-files.xml +++ b/en_US/docs-getting-files.xml @@ -1,5 +1,5 @@ - @@ -13,7 +13,7 @@ To work on official &FED; documentation you need to install the required - tools. The directions below will help you configure your setup. + tools. Follow the directions below to configure your system.
@@ -44,7 +44,7 @@ The &FDP;'s custom scripts and stylesheets are stored in CVS on the - cvs.fedora.redhat.com CVS + cvs.fedoraproject.org CVS server. Check them out along with the DocBook XML files for the existing docs. @@ -52,7 +52,7 @@ mkdir my-fedora-docs-sandbox cd my-fedora-docs-sandbox -export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/docs +export CVSROOT=:ext:username@cvs.fedora.redhat.com:/cvs/docs cvs login cvs co docs-common @@ -64,8 +64,9 @@ cvs co docs-common Common Files - You need to perform these steps only once. These files are common to - all the official documentation. + You need to perform this "checkout" step only once, although you may + need to update the files later. These files are common to all the + official documentation. @@ -75,18 +76,14 @@ cvs co docs-common
- -
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. + XML documents into other output formats such as + HTML. In addition, these tools can build your document + into a RPM package. To take advantage of these + services, you must follow conventions for naming your files.
Document Filenames @@ -103,320 +100,16 @@ cvs co docs-common Do not use the word &FED; in your module name. Since all documents in the repository are &FED; documentation, - using it creates unnecessary confusion. + using this term 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-module-struct.xml b/en_US/docs-module-struct.xml new file mode 100644 index 0000000..a751f2b --- /dev/null +++ b/en_US/docs-module-struct.xml @@ -0,0 +1,348 @@ + + + +%FEDORA-ENTITIES-EN; + +]> + + + How Modules Work + Documentation modules have a specific structure that enables the + preconfigured tools to work correctly. Follow this structure exactly or you + may have problems building your module. The &FDP; build tools locate + resources in the module and use them to build new output such as HTML or RPM + packages. +
+ Structure of a Module + The following listing shows a directory tree of an example module, + excluding any CVS folders: + + + + + Primary language directory (required) + This is the only directory absolutely required. It is named for the + original language of the document, such as en_US (US English). The primary language + does not have to be US English; all languages are supported. This + directory contains all the XML source for the actual document, as well + as XML source for document-specific + entities + Think of an XML entity as a predefined snippet of information. + It can represent a chunk of XML source, or simply a word or + character. If the information changes, it need be replaced only + once, in the definition, to fix all usage. + . + + + + Graphics directory (optional) + The figs/ directory is an + optional directory where graphics for the document should be stored. If + graphics are screenshots that are particular to a language, the + figs/ directory can and should be + stored in a language directory. + + + Translation (PO) directory (optional) + The po/ directory contains + specially formatted files created and used by translators. The &FDP; + build tools use these files to create translated versions of documents. + The translated documents are not stored in CVS; they are created as + needed from these PO files. + + + Makefile (required) + The Makefile controls the build process. Its + content is discussed below. + +
+
+ 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 and + paste operations. + + + below shows the + whole Makefile for a simple document having + only two files and one language. + + + Sample Document Makefile + + + + + + Do not be concerned with some of the more complicated syntax (in + particular, the XMLFILES_template stanza). An + explanation for this template appears a few paragraphs + below. + + <varname>DOCBASE</varname> + This variable contains the name for the main (parent) XML document. + Follow convention by naming your document after the module name. + + + <varname>PRI_LANG</varname> + This variable contains the ISO code for the original version of the + document, such as en_US. + + + <varname>OTHERS</varname> + This variable contains a listing of ISO codes for any other versions + into which the document has been translated. The module must contain a + po/ directory and a PO file for + any indicated additional languages. + + + <varname>DOC_ENTITIES</varname> + This variable contains a listing of any files containing entity + definitions. The &FDP; uses a special XML format to record + document-specific entities, so they can be translated and built on the + fly like any other XML document. An example is shown later in this + guide. + + + <varname>XMLFILES_template</varname> + This template allows the build tools to work with the + document in multiple languages once it is translated. The + ${1} marking is a variable used to substitute + the appropriate language. This template is not terribly + complicated. For a new module, duplicate this section exactly + except for the actual filenames. Prepend the text + ${1}/, in place of the language code + directory name, to each filename in your document. + + + + Files Exempt From Listing + Do not include the document-specific entities XML file or the + rpm-info.xml file, which will be discussed later in + this guide. + + + + The final line, beginning with include, references the + main Makefile for the build system. This + Makefile.common file contains all the + make(1) targets and rules to actually build the + document and the various archives. + + + 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/documentation-guide.xml b/en_US/documentation-guide.xml index 1d9ae2f..63c719b 100644 --- a/en_US/documentation-guide.xml +++ b/en_US/documentation-guide.xml @@ -1,5 +1,5 @@ - + + + + @@ -34,9 +39,11 @@ xmlns:xi="http://www.w3.org/2001/XInclude" /> - + +