From abc318ff5dbf820057c7a1357235669b7d01502d Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: May 18 2011 02:37:58 +0000 Subject: Update repository documentation manual. --- diff --git a/Manual/Directories/chapter-menu.texi b/Manual/Directories/chapter-menu.texi index ee6dfcd..f527927 100644 --- a/Manual/Directories/chapter-menu.texi +++ b/Manual/Directories/chapter-menu.texi @@ -35,6 +35,9 @@ * Directories trunk Identity Webenv:: * Directories trunk Locales:: * Directories trunk Manual:: +* Directories trunk Manual Directories:: +* Directories trunk Manual Introduction:: +* Directories trunk Manual Licenses:: * Directories trunk Scripts:: * Directories trunk Scripts Functions:: * Directories trunk Scripts Functions Help:: diff --git a/Manual/Directories/chapter-nodes.texi b/Manual/Directories/chapter-nodes.texi index e5b0444..e460183 100644 --- a/Manual/Directories/chapter-nodes.texi +++ b/Manual/Directories/chapter-nodes.texi @@ -178,6 +178,21 @@ @cindex Directories trunk Manual @include Directories/trunk/Manual.texi +@node Directories trunk Manual Directories +@section The @file{trunk/Manual/Directories} Directory +@cindex Directories trunk Manual Directories +@include Directories/trunk/Manual/Directories.texi + +@node Directories trunk Manual Introduction +@section The @file{trunk/Manual/Introduction} Directory +@cindex Directories trunk Manual Introduction +@include Directories/trunk/Manual/Introduction.texi + +@node Directories trunk Manual Licenses +@section The @file{trunk/Manual/Licenses} Directory +@cindex Directories trunk Manual Licenses +@include Directories/trunk/Manual/Licenses.texi + @node Directories trunk Scripts @section The @file{trunk/Scripts} Directory @cindex Directories trunk Scripts diff --git a/Manual/Directories/trunk/Locales.texi b/Manual/Directories/trunk/Locales.texi index cec803d..823d887 100644 --- a/Manual/Directories/trunk/Locales.texi +++ b/Manual/Directories/trunk/Locales.texi @@ -62,12 +62,11 @@ functionality of command-line interface. @subheading Usage @itemize -@item ... +@item @xref{Directories trunk Scripts Functions Locale}. @end itemize @subheading See also @itemize -@ref{Directories trunk Scripts Functions Locale} +@item @ref{Directories trunk} @end itemize - diff --git a/Manual/Directories/trunk/Manual.texi b/Manual/Directories/trunk/Manual.texi index 081eebf..91e1dcc 100644 --- a/Manual/Directories/trunk/Manual.texi +++ b/Manual/Directories/trunk/Manual.texi @@ -1,24 +1,44 @@ @subheading Goals -This @file{trunk/Manual} directory structure provides the -documentation work line. The main goal of documentation work line is -describe what each directory inside the CentOS Artwork Repository is -for, the conceptual ideas behind them and, if possible, how automation -scripts make use of them. +The @file{trunk/Manual} directory is the place where files related to +documentation work line are stored in. The main goal of documentation +work line is to describe what each directory inside the CentOS Artwork +Repository is for, the conceptual ideas behind them and, if possible, +how automation scripts make use of them. @subheading Description +@subsubheading Files +@table @file +@item repository.css +@item repository-index.texi +@item repository.info.bz2 +@item repository-init.pl +@item repository-menu.texi +@item repository-node.texi +@item repository.pdf +@item repository.sed +@item repository.texi +@item repository.txt.bz2 +@item repository.xhtml.bz2 +@item repository.xml +@end table +@subsubheading Directories + @itemize -@item ... +@item @xref{Directories trunk Manual Directories}. +@item @xref{Directories trunk Manual Introduction}. +@item @xref{Directories trunk Manual Licenses}. @end itemize @subheading Usage @itemize -@item ... +@item @xref{Directories trunk Scripts Functions Help}. @end itemize @subheading See also -@menu -@end menu +@itemize +@item @ref{Directories trunk} +@end itemize diff --git a/Manual/Directories/trunk/Manual/Directories.texi b/Manual/Directories/trunk/Manual/Directories.texi new file mode 100755 index 0000000..0a72b17 --- /dev/null +++ b/Manual/Directories/trunk/Manual/Directories.texi @@ -0,0 +1,27 @@ +@subheading Goals + +The @file{trunk/Manual/Directories} directory stores source +documentation files related to repository directories. The directory +structure in this location mirrors the directory structure being +documented in the repository from top level directories (e.g., +@file{trunk}, @file{branches} and @file{tags}) to inner levels, +including the @file{trunk/Manual} location itself where documentation +source files are stored in. + +@subheading Description + +@itemize +@item ... +@end itemize + +@subheading Usage + +@itemize +@item ... +@end itemize + +@subheading See also + +@itemize +@item ... +@end itemize diff --git a/Manual/Directories/trunk/Manual/Introduction.texi b/Manual/Directories/trunk/Manual/Introduction.texi new file mode 100755 index 0000000..d6bb628 --- /dev/null +++ b/Manual/Directories/trunk/Manual/Introduction.texi @@ -0,0 +1,23 @@ +@subheading Goals + +@itemize +@item ... +@end itemize + +@subheading Description + +@itemize +@item ... +@end itemize + +@subheading Usage + +@itemize +@item ... +@end itemize + +@subheading See also + +@itemize +@item ... +@end itemize diff --git a/Manual/Directories/trunk/Manual/Licenses.texi b/Manual/Directories/trunk/Manual/Licenses.texi new file mode 100755 index 0000000..d6bb628 --- /dev/null +++ b/Manual/Directories/trunk/Manual/Licenses.texi @@ -0,0 +1,23 @@ +@subheading Goals + +@itemize +@item ... +@end itemize + +@subheading Description + +@itemize +@item ... +@end itemize + +@subheading Usage + +@itemize +@item ... +@end itemize + +@subheading See also + +@itemize +@item ... +@end itemize diff --git a/Manual/Directories/trunk/Scripts/Functions/Help.texi b/Manual/Directories/trunk/Scripts/Functions/Help.texi index 05ae6ca..34fa724 100644 --- a/Manual/Directories/trunk/Scripts/Functions/Help.texi +++ b/Manual/Directories/trunk/Scripts/Functions/Help.texi @@ -98,15 +98,71 @@ manual structure in a correct state. @subheading Description -@itemize -@item ... -@end itemize +The CentOS Project corporate identity is organized through directories +in The CentOS Artwork Repository. Each directory inside the repository +responds to conceptual ideas and uses files to get the implementation +of those ideas. The @code{help} functionality of +@command{centos-art.sh} script uses this directory layout as reference +to document the conceptual ideas it is based on. Each directory inside +the repository can be documented, in order to provide the explanation +of what it is for and how automation scripts use it. + +@quotation +@strong{Caution} When the repository directory layout changes, the +documentation layout related must be changed as well in order for both +locations to be consistent in their paths. Otherwise, you may end up +having documentation entries that point to unexistent directories in +the repository. +@end quotation + +Files inside the repository are not documented. The only exception to +this rule are files under @file{trunk/Manual} directory, the place +where documentation source files are stored in. Inside this location +you can refer @file{.texi} files for direct actions using the +@code{help} functionality of @command{centos-art.sh} script. File +actions, in this location, are also used to manage specific parts of +the manual which have no association outside @file{trunk/Manual} +directory (e.g., Preface, Introduction, etc.). + +The manual structure (@pxref{Directories trunk Manual}) is supported +by GNU Texinfo, a documentation system that can produce both online +information and a printed manual from a single source. The @code{help} +functionality is an interface you can use to control the source files +in the manual structure. + +The manual output files is produced from Texinfo files and stored in +@file{trunk/Manual} on different formats including Info, Pdf, XHTML, +XML and TXT. + +Whatever your prefered language be, you'll always edit documentation +entries in English language and so will be the output produced from +them, when you use the @code{help} functionality of +@command{centos-art.sh} script. However, you can achieve the manual +localization to your prefered language by applying the @code{locale} +functionality of @command{centos-art.sh} script (@pxref{Directories +trunk Scripts Functions Locale}) to any of the XML-based English +outputs supported by @command{centos-art.sh} script (e.g., XHTML and +Docbook) to produce portable objects for your prefered language and +the @code{render} functionality of @command{centos-art.sh} script +(@pxref{Directories trunk Scripts Functions Render}) to produce the +translated version of the output XHTML files taken in first place. The +translated version is produced in the same format of the file taken +as reference to build the portable objects. XHTML format in this case. @subheading Examples -@itemize -@item ... -@end itemize +@table @command +@item centos-art help --edit trunk/Identity + +This command edits the documentation entry related to +@file{trunk/Identity} directory. + +@item centos-art help --read trunk/Identity + +This command reads the doumentation entry related to +@file{trunk/Identity} directory in info format. + +@end table @subheading Author diff --git a/Manual/Directories/trunk/Scripts/Functions/Locale.texi b/Manual/Directories/trunk/Scripts/Functions/Locale.texi index 187308e..0eb5ff4 100644 --- a/Manual/Directories/trunk/Scripts/Functions/Locale.texi +++ b/Manual/Directories/trunk/Scripts/Functions/Locale.texi @@ -111,18 +111,17 @@ their localization using the @option{--update} and @option{--edit} options as much as it be needed. Once design models have been localized, rendering them in different -language is a matter using the @strong{@code{render}} functionality of +language is a matter using the @code{render} functionality of @command{centos-art.sh} script. @xref{Directories trunk Scripts Functions Render}, for more information about it. @subsubheading Shell script localization -Additionally to design models localization, the @code{locale} -functionality is also used to localize the @command{centos-art.sh} -script itself. The @command{centos-art.sh} script is a shell script -written in Bash, so the @code{locale} functionality uses the -@command{gettext} tools to retrive translatable strings, create -portable objects and machine objects. +The @code{locale} functionality is used to localize the +@command{centos-art.sh} script itself. The @command{centos-art.sh} +script is a shell script written in Bash, so the @code{locale} +functionality uses the @command{gettext} tools to retrive translatable +strings, create portable objects and machine objects. Thanks to @command{gettext}, it is possible for the @code{locale} functionality to separate programming tasks from the translating @@ -160,7 +159,7 @@ This command is executed by translators once the graphic designers have committed updates to Anaconda default design models (e.g., slide text changes). -@item centos-art locale --edit trunk/Identity/Models/Default/Distro/5/Anaconda --dont-create-mo +@item centos-art locale --edit trunk/Identity/Models/Default/Distro/5/Anaconda This command let translators to edit portable objects related to Anaconda default design models of The CentOS Distribution major @@ -168,8 +167,8 @@ release 5. The edit action is where the translator localize translatable strings in English language to another language. When portable objects for XML-base files are produced, there is no -need to retain the machine object format, so we used the -@option{--dont-create-mo}. +need to retain the machine object format, so we the +@option{--dont-create-mo} is automatically assumed. @item centos-art locale --update trunk/Scripts @@ -184,10 +183,48 @@ committed updates @command{centos-art.sh} script. @item centos-art locale --edit trunk/Scripts -This command let translators to edit portable objects related to -@command{centos-art.sh} script. The edit action is where the -translator localize translatable strings in English language to -another language. +This command edits portable objects related to @command{centos-art.sh} +script in your prefered language. + +@item centos-art locale --update trunk/Manual/repository.xhtml + +This command updates portable objects for the XHTML output of the +repository documentation manual. The portable objects are created in +your prefered language and can be used to produced localized versions +of the manual in XHTML format. + +The update action consists on adding new translatable strings to or +removing old translatable strings from the portable objects in order +to keep both the portable object and the manual XHTML output +consistent one another. + +People execute this command after committing changes to the repository +documentation manual. + +@item centos-art locale --edit trunk/Manual/repository.xhtml + +This command takes all the repository documentation manual XHTML +output files, which have not been translated yet inside the +@file{trunk/Manual/repository.xhtml} directory, as input to produce +portable objects from them so as for you to localize translatable +strings to your prefered language (e.g., as specified by the +@env{LANG} environment variable). + +Once the portable objects have been created they are used to produce +the translated version of the manual in XHTML format under the +@file{trunk/Manual/repository.xml/LANG} directory, where @samp{LANG} +refers your prefered language. The translated version of the XHTML +files is produced using the @code{render} functionality of +@command{centos-art.sh} script (@pxref{Directories trunk Scripts +Functions Render}). + +When your prefered language is other but English, the +@command{centos-art.sh} script takes care of updating both the +portable objects and the translated version of files after you've +edited a manual documentation entry, using the @code{help} +functionality of @command{centos-art.sh} script (@pxref{Directories +trunk Scripts Functions Help}). In other situations, you need to do +these actions by yourself. @end table