From 35d09733456dc09d1f0da062b7175409587e1f3d Mon Sep 17 00:00:00 2001 From: Tommy Reynolds Date: Tue, 13 Dec 2005 21:56:24 +0000 Subject: Added documentation about the document building system. Dropped the one-line "converting" chapter by creating a "Prerequisites" section in the "getting-files" section. --- Makefile | 10 +- acknowledgments-en.xml | 5 + docs-converting-en.xml | 20 --- docs-converting-zh_CN.xml | 9 -- docs-getting-files-en.xml | 396 +++++++++++++++++++++++++++++++++++++++------ documentation-guide-en.xml | 5 +- 6 files changed, 364 insertions(+), 81 deletions(-) delete mode 100644 docs-converting-en.xml delete mode 100644 docs-converting-zh_CN.xml diff --git a/Makefile b/Makefile index 49c1461..f6edc50 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,19 @@ -############################################################################### +####################################################################### # Makefile for RHLP docs project # Created by: Tammy Fox # Last edited by: Tammy Fox # WARNING: need passivetex 1.24 for pdf generation to work # License: GPL # Copyright 2003 Tammy Fox, Red Hat, Inc. -############################################################################### +####################################################################### LANGUAGES = en zh_CN DOCBASE = documentation-guide -XMLEXTRAFILES-en = +XMLEXTRAFILES-en=acknowledgments-en.xml docs-emacs-en.xml \ + docs-emacs-nxml-en.xml docs-getting-files-en.xml \ + docs-intro-en.xml docs-rh-guidelines-en.xml docs-style-en.xml \ + docs-tutorial-en.xml docs-vim-en.xml docs-xml-tags-en.xml \ + documentation-guide-en.xml ###################################################### include ../docs-common/Makefile.common diff --git a/acknowledgments-en.xml b/acknowledgments-en.xml index 7e53ae5..c7dc535 100644 --- a/acknowledgments-en.xml +++ b/acknowledgments-en.xml @@ -37,4 +37,9 @@ linkend="s1-xml-tags-screen">. + + A patch from Tommy Reynolds (Tommy.Reynolds at MegaCoder.com) has been + applied to more fully explaing the document building system. + + diff --git a/docs-converting-en.xml b/docs-converting-en.xml deleted file mode 100644 index ac0684b..0000000 --- a/docs-converting-en.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - Converting to HTML and PDF - - - Each directory containing a document also has a Makefile. In the directory, - run the command make html to build the HTML version and - make pdf to build the PDF version. - - - - Warning - - The PDF production is somewhat fragile right now. It may or may not - work. - - - - diff --git a/docs-converting-zh_CN.xml b/docs-converting-zh_CN.xml deleted file mode 100644 index dc06576..0000000 --- a/docs-converting-zh_CN.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - 生成 HTML 及 PDF - 每个包含文档的目录都有一个 Makefile。在这个目录下，运行命令 make html 来生成 HTML 版本，运行 make pdf 来生成 PDF 版本。 - - 警告 - PDF 的生成仍然不完善，可能无法工作。 - - diff --git a/docs-getting-files-en.xml b/docs-getting-files-en.xml index 21481d1..abed9c4 100644 --- a/docs-getting-files-en.xml +++ b/docs-getting-files-en.xml @@ -1,83 +1,389 @@ - Getting the Files + Prerequisites + + Before you being working with the &FED; documents, you must have certain tools and packages installed on your system. + The directions below will help you configure your setup. + + +
+ System Packages - To start working on the Docs Project, you will need the appropriate - DocBook XML files, stylesheets, and scripts. The following packages are - required: - + To start working on the Docs Project, you will need the appropriate DocBook XML files, stylesheets, and scripts. + The following packages are required: + - xmlto — for producing HTML and PDF outputs + + xmlto — for producing HTML and PDF outputs. + - docbook-style-xsl — for the default XSLT stylesheets we - build on + + docbook-style-xsl — for the default XSLT stylesheets we build on. + - docbook-dtds — XML versions of the DocBook DTD + + docbook-dtds — XML versions of the DocBook DTD + - The custom scripts and stylesheets used are all stored in CVS on the - cvs.fedora.redhat.com CVS server. - You need to check them out along with the DocBook XML files for the - existing docs. - + You can verify these packages are on your system by: + + + + +rpm -q xmlto +rpm -q docbook-style-xsl +rpm -q docbook-dtds + + - You should perform these steps only once, when you first make a checkout - from docs CVS. When you see the password prompt, press the - Enter key. - + Any missing package can be installed using yum(8) this way: + + + + +su -c 'yum install xmlto' +su -c 'yum install docbook-style-xsl' +su -c 'yum install docbook-dtds' + + +
+
+ Fedora Documentation Tools + + + You need perform these steps only once. + These files are common to all the &FDPX; documents. + + + + The custom scripts and stylesheets used are all stored in CVS on the cvs.fedora.redhat.com CVS server. + You need to check them out along with the DocBook XML files for the existing docs. + + + + When you see the password prompt, press the Enter key. + In the example below, we also show how to obtain a copy of an existing &FDPX; document. + - -mkdir my-fedora-docs -cd my-fedora-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 cvs co example-tutorial - +
+
+ Filename Conventions - When you perform an anonymous CVS checkout, you can view the files and - retreive the latest versions. You cannot add (commit) any updates or new - files back to the repository. To commit changes to CVS, you must have - CVS write access. Refer to to learn - about getting write access to CVS. + &FDPX; provides the tools, scripts, and stylesheets to transform your XML documents into either HTML or PDF output formats. + In addition, your document can automatically be built into an RPM package. - - To see a list of the available documents: + To take advantage of these services, you should follow our conventions for naming your files. + While you may choose whatever filenames you like, adopting our practices will make your life simpler. + Of course, if you are bringing your own document into our building system, changing hundreds of filenames may seem quite a burden; relax, we can use your filenames with just a little work on your part. + Read on to find out how. - -cvs co -c - +
+ Document Filenames + + Each document lives in a peer directory to the docs-common directory you extracted from the &FED; archive earlier. + Name your document directory something related to its subject, just avoid any name already taken. + The cvs co -c command mentioned earlier will show you the names already taken. + +
+
+ Anticipating I18N Translation + + The &FDPX; includes an active translation team. + Project documents are often translated into several languages. + By convention, the translated files share the directory with the original files; filenames must be unique. + + + &FDPX; filenames are constructed appending a dash followed by the ISO language symbol before any file extention. + For example, a file whose language content is US English could be named mydoc-en.xml; the file containing its Chinese translation would then be named mydoc-zh_CN.xml, and so on. + + + To assist this effort, the document build system assumes that each file is tagged with its I18N locale. + Our filename convention is shown in + + + &FDPX; Filename Conventions + + + + + + + Compoment + + + Description + + + + + + + anything_but_dash + + + + The initial portion of a filename can be anything, as long as no dash is used. + + + + + + - + + + + A dash (-) is to be used only to introduce the ${LANG} filename component. + + + + + + ${LANG} + + + + The ${LANG} component identifies the locale for the file content. + + + In addition to helping classify files according to their language content, we also use the ${LANG} value as an UTF-8 locale when rendering the document. + For example, the document mydoc-it.xmlwill be rendered using it.UTF-8 as the language environment. + + + For more information on I18N localization, visit the web site. + + + + + +
+ + Document Filenames Are Special + + The main file in your document must follow the file naming convention or the document building system cannot find it. + + +
+
+
+ The Document Build System - Pick your document of interest and then download it to your working directory: + Common tasks such as rendering the document into either HTML or PDF can be performed easily using the document building system. - -cvs co example-tutorial - - Except for the &IG;, all documentation in CVS must - be tutorials written in DocBook XML article format using the template in - the example-tutorial directory. Each tutorial - must be in its own directory. No XML files should be - in the root directory. + 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's 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. + +
+
+ Finding 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. + + + 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. + + + 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/documentation-guide-en.xml b/documentation-guide-en.xml index 8c1240d..7d7ad19 100644 --- a/documentation-guide-en.xml +++ b/documentation-guide-en.xml @@ -1,4 +1,4 @@ - + - @@ -76,8 +75,6 @@ &STYLE; - &CONVERTING; - &CVS; &ACKNOWLEDGMENTS; -- cgit