This section describes the implementation of Texinfo documentation format inside the functionality of centos-art.sh script. In this section we assume you have a basic understanding of Texinfo documentation system. Otherwise, if you don't know what Texinfo documentation system is, read the Texinfo manual first (e.g., by running the info texinfo command) and then, come back here. The functionality of centos-art.sh provides a document structure that makes documentation manuals created through it to be scalable and maintainable through time. This document structure follows the idea of an upside-down tree to organize chapters, sections, subsections and the like, as described in . The functionality creates documentation manuals source files in the Documentation/Models/Texinfo/ directory and saves output produced from them in the Documentation/Manuals/Texinfo/ directory. To produce documentation manuals initial source files, the functionality uses Texinfo documentation templates, as described in . Inside the documentation models directory, source files are stored inside language-specific directories. The language-specific directories are necessary to implement internationalization of Texinfo source files, as described in . Inside the language-specific directory, the following files exist to store the manual's main definitions (e.g., title, subtitle, author, copyright notice, chapters, appendixes, indexes and all similar stuff a documentation manual usually has). In addition to these files, there is one directory for each chapter created inside the manual. Inside each chapter directory, you'll find the files controlling the section definitions related each chapter they belong to. The section files (a.k.a. documentation entries) are suffixed with a texinfo extension and named arbitrarily, as it is illustrated in . Inside section files it is where you write the manual's content itself. Texinfo document structure Manuals/${MANUAL_NAME} `-- ${LANG} |-- ${CHAPTER_NAME} | |-- chapter-menu.texinfo | |-- chapter-nodes.texinfo | |-- chapter.texinfo | `-- ${SECTION_NAME}.texinfo |-- Licenses | |-- chapter-menu.texinfo | |-- chapter-nodes.texinfo | `-- chapter.texinfo |-- ${MANUAL_NAME}.conf |-- ${MANUAL_NAME}-index.texinfo |-- ${MANUAL_NAME}-menu.texinfo |-- ${MANUAL_NAME}-nodes.texinfo `-- ${MANUAL_NAME}.texinfo Texinfo (as in texinfo-4.8-14.el5) doesn't support part sectioning inside documentation manuals, so neither the functionality does. Nevertheless, you can create several documentation manuals and considered them as part of a bigger documentation manual to workaround this issue. In this document structure, the creation of documentation manuals, chapters and sections is not limitted. You can create as many documenation manuals, chapters and sections as you need. The only limitation would be the amount of free space required to store the Texinfo source files and the output files produced from them in your workstation. Texinfo document templates provide the initial document structure the functionality needs in order to create and maintain document structures, as described in . Texinfo document templates are language-specific. This means that there is (or, at least, must be) one Texinfo document template for each language you plan to support documentation manuals for. By default, &TCAR; provides a default Texinfo document template under en_US directory. This template structure is used when your current locale is English language or when you are creating/editing a documentation manual in a language other than English, but no language-specific document template for that language exists in the Scripts/Documentation/Models/Texinfo/Default/ directory. The Scripts/Documentation/Models/Texinfo/Default/ directory organizes all Texinfo document templates using the format LL_CC, where LL is the language code (as in ISO-639) and CC the country code (as in ISO-3166). The directory structure of Texinfo document templates is illustrated in the and implemented through the following files: manual.texinfo This file can be found inside the language-specific directory and contains the manual's main definitions (e.g., document title, document language, document authors, copyright notice, etc.). manual-menu.texinfo This file can be found inside the language-specific directory and contains the menu definitions of chapters inside the manual. When functionality creates instances of this file, menu definitions inside it are automatically updated when a new chapter is created or deleted through the functionality. Generally, you don't need to edit instances of this file once the documentation manual has been created. When a documentation manual is created for first time, this file is copied from Texinfo document template directory structure to the documentation manual being currently created. At this specific moment, the instance created contains the following Texinfo menu definition: @menu * Licenses:: * Index:: @end menu Later, when chapters are added to or deleted from the documentation manual, the content of this file varies adding or deleting menu entries accordingly. Nevertheless, the two entries shown above are ignored when new chapters are added to or removed from the list, so they will always be present in instances of this file. To preserve the manual consistency, the functionality prevents you from deleting any of these chapters once the documentation manual has been created. manual-nodes.texinfo This file can be found inside the language-specific directory and contains the node definitions of all chapters inside the manual. When functionality creates instances of this file, node definitions inside it are automatically created based on menu definitions (see manual-menu.texinfo file above) and they don't include any content here. Instead, as part of the node definition, the @include command is used to connect each node with its content. Generally, you don't need to edit instances of this file once the documentation manual has been created. manual-index.texinfo This file can be found inside the language-specific directory and contains the Texinfo commands used to generated an organized view of all indexes you defined inside documentation entries so they can be quickly accessed. Generally, you don't need to edit instnaces of this file once the documentation manual has been created. manual.conf This file contains the initial configuration of documentation manuals written in Texinfo format. When a documentation manual is created for first time, this file is copied into its target directory so you be able to customize specific information like menu order, title styles and template assignments therein. The content of this file is described in . chapter.texinfo This file contains Texinfo's main chapter definition used by functionality when new chapters are created inside documentation manuals. When chapters are created for first time, they come without any introduction or documentation entry inside. In case you need to add/update the chapters definition files, edit the related chapter definition file inside the documentation manual you are working on, not the template file used to create it. To edit the chapter definition file, don't provide any section information in the documentation entry. For example, if you want to update the chapter introduction related to trunk chapter inside tcar-fs documentation manual, use the tcar-fs::trunk: documentation entry. chapter-menu.texinfo This file is part of Texinfo's main chapter definition and should be initially empty. Later, when chapters are created for first time, this file is copied as it is (i.e., empty) into the documentation manual to store the Texinfo menu entries related to all documentation entries created inside the chapter. The Texinfo menu entries related to documentation entries are automatically created using Texinfo source files as reference. chapter-nodes.texinfo This file is part of Texinfo's main chapter definition and contains the node definition the functionality uses as reference to create the list of Texinfo nodes related to all documentation entries created inside the chapter. The node definition of documentation entries is automatically created from the menu definition of documentation entries (see chapter-menu.texinfo file above), once it has been updated from Texinfo source files. section.texinfo This file contains the Texinfo section definition used by functionality when new documentation entries are created inside chapters of documentation manuals. When documentation entries are created for first time, they are created as empty documentation entries that you need to fill up with content. Again, if you want to update the content of sections inside the documentation manual, update the related documentation entry inside the documentation manual, not the template file used to create it. The creation of documentation entries inside the documentation manual is represented by the ${SECTION_NAME}.texinfo file, as described in . In this example, ${SECTION_NAME} is a variable string referring the file name of documentation entries. The file names of documentation entries are made of letters, numbers and the minus sign (which is generally used as word separator). Documentation entries are not limited inside chapters of documentation manuals. You can create as many documentation entries as you need to describe the content of your manual. There are other files which aren't related to manual's source files, but to manual's output files. Such files are described below and can be found either inside or outside the language-specific directories so you can control common and specific output settings through them. These files aren't copied into the directory structure of new documentation manuals created through the functionality. Instead, they remain inside the template directory structure so as to be reused each time the output of documentation manuals is rendered. manual-init.pl This file can be found inside and outside language-specific directories and contains the Texi2html initialization script. When this file is outside the language-specific directory, it contains common customizations to all language-specific outputs (e.g., changing the output DTD). When this file is inside the language-specific directory, it contains translations for that language-specific output (e.g., special words like See, Index, Contents, Top, etc., are localized here). manual.sed This file can be found inside and outside language-specific directories and contains special transformations for Texi2html output. Again, when this file is inside language-specific directories the transformation are applied to that language-specific XHTML output and when it is outside language-specific directories the transformations are applied to all language-specific XHTML outputs. Most transformations achieved through this file are to produce admonitions since Texinfo documentation format (as in texinfo-4.8-14.el5) doesn't have an internal command to build them. Template for texinfo document structures Documentation/Models/Texinfo/Default/ |-- ${LANG}/ | |-- Chapters/ | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | |-- chapter.texinfo | | `-- section.texinfo | |-- Licenses/ | | |-- GFDL.texinfo | | |-- GPL.texinfo | | |-- chapter-menu.texinfo | | |-- chapter-nodes.texinfo | | `-- chapter.texinfo | |-- manual-index.texinfo | |-- manual-init.pl | |-- manual-menu.texinfo | |-- manual-nodes.texinfo | |-- manual.conf | |-- manual.sed | `-- manual.texinfo |-- manual-init.pl `-- manual.sed Inside the directory structure of Texinfo document templates, the Chapters directory organizes chapter specific models used to create and maintain both chapter and sections files inside manuals. On the other hand, the Licenses directory organizes the license information linked from all manuals. Notice the license information is not copied into documentation manuals when they are created, but refered from this location where they are maintained. This configuration permites that all documentation manuals written in Texinfo format inside &TCAR; do use the same license information and if a change is committed to the license files, such changes be immediatly propagated to documentation manuals the next time their output files be updated. The document expansions are special constructions the functionality uses to generate content dynamically inside Texinfo source files. This expansion creates a list of links with section entries one level ahead from the section entry being currently processed. In this construction, the TYPE variable can be either itemize, enumerate or menu. When no TYPE variable is provided, the itemize value is considered as default. @c -- <[centos-art(SeeAlso,TYPE) @c -- ]> This expansion might result useful when you are documenting the repository file system. For example, if you are currently editing the documentation entry related to Identity directory and want to create a linkable list of all documentation entries in the first level under it, the code you'll have once the construction be expanded would look like the following: @c -- <[centos-art(SeeAlso) @itemize @item @ref{Trunk Identity Brushes} @item @ref{Trunk Identity Fonts} @item @ref{Trunk Identity Images} @item @ref{Trunk Identity Models} @item @ref{Trunk Identity Palettes} @item @ref{Trunk Identity Patterns} @item @ref{Trunk Identity Webenv} @end itemize @c -- ]> An interesting thing to notice here is that document expansions are executed each time the related documentation entry is edited or updated. Following with the example above, if the documentation entries related to directories under Identity changes for some reason (e.g., they are removed from documentation manual), the list generated as result of document expansion will be updated automatically after editing the documentation entry or updating the documentation manual structure. The document configuration is stored in the ${MANUAL_NAME}.conf file, inside the documentation manual directory structure. This file is originally copied from manual.conf template file when the documentation manual is created for first time. The content of ${MANUAL_NAME}.conf file is organized in sections. Each section here is written in one line of its own and have the form [section_name]. Under sections, the configuration settings take place through name="value" pairs set in one line each. Notice that quotation marks around the option_value are required. Comments are also possible using the # character at the begining of lines. Comments and empty lines (including tabs and white spaces) are ignored. In case more than one section or option appear with the same name inside the configuration file, the first one found will be used. Nested section definitions are not supported. [section_name] # This is a comment. option_name = "option_value" The ${MANUAL_NAME}.conf file is specific to document templates. If you are using Texinfo document template to create documentation manuals, then the default configuration file for that documentation manual is taken from Texinfo document template directory structure. However, if you are using a document template different to Texinfo document template, the default configuration file will be taken from the related document template directory structure you are creating the documentation manual from. The [main] section organizes settings that let you customize the way sections and menu definitions are created inside the documentation manual. The following options are available in this section: manual_format This option specifies the documentation format used by manual. To write documentation manuals in Texinfo format, the value of this option must always be: manual_format = "texinfo" Once the documentation manual has been created, you must not change the value of manual_format option. This will produce an error because there is not a migration feature available yet. In the future, when you change this value, it must be possible to transform documentation manuals from one format to another. manual_section_style This option specifies the title style used by sections inside the manual. Possible values to this option are `cap-each-word' to capitalize each word in the section title, `cap-first-word' to capitalize the first word in the section title only and `directory' to transform each word in the section title into a directory path. From all these options, `cap-each-word' is the one used as default. manual_section_style = "cap-each-word" manual_section_order This option specifies the order used by sections inside the manual. By default new sections added to the manual are put on the end to follow the section order in which they were `created'. Other possible values to this option are `ordered' and `reversed' to sort the list of sections alphabetically from A-Z and Z-A, respectively. manual_section_order = "created" The [templates] section provides the assignment relation between template files and documentation entry files inside the manual. The template definition is set on the left side using relative path and the documentation entry files are described on the right side using a regular expression. The first match wins. Chapters/section.texinfo = "^.+\.texinfo$" To produce localized documentation manuals through Texinfo documentation format it is necessary to create one documentation manual for each language it is desired to support documentation for. Documentation manuals created in this configuration don't have a direct relation among themselves except that one adopted by people writting them to keep their content syncronized. In this configuration translators take one documentation manual as reference (a.k.a. the source manual) and produce several translated manuals based on its content. To keep track of changes inside the source manual, the underlaying version control system must be used considering that there is no direct way to apply gettext The gettext program translates a natural language message into the user's language, by looking up the translation in a message catalog. For more information about the gettext program, run info gettext. procedures to Texinfo source files. In order to maintain localization of Texinfo source files through gettext procedures, it is necessary to convert the Texinfo source files into XML format first. This way it would be possible to make use of and functionalities to maintain translation messages in different languages through portable objects and producing localized XML files based on such portable objects, respectively. Once the localized XML file is available, it would be a matter of using an XSLT processor (see the xsltproc command) to realize the convertion from XML to a localize Texinfo (or possible other) format. Nevertheless, this workaround fails because the Document Type Definition (DTD) required to validate the XML file produced from makeinfo (as in texinfo-4.8-14.el5) is not availabe inside &TCD; (release 5.5), nor it is the XSLT files required to realize the transformation itself for such DTD. Another similar approach to maintain localization of Texinfo source files through gettext procedures would be to convert Texinfo source file to DocBook format; for who the required DTD and XSLT files are available inside &TCD;. This way, following a procedure similar to that one describe for XML files above, it would be possible to end up having localized DocBook files that can be used as source to produce localized output for both online and printing media. However, the DocBook output produced from makeinfo command (as in texinfo-4.8-14.el5) isn't a valid DocBook document according to DocBook DTDs available inside &TCD; (release 5.5) thus provoking the validation and transformation of such a malformed document to fail. The language information of those documentation manuals produced through Texinfo documentation format is declared by Texinfo's @documentlanguage command. This command receives one argument refering the language code (as in ISO-639 standard) and must be set inside the manual's main definition file. Generally, there is no need to change the document language declaration once it has been created by the functionality; unless you mistakently create the manual for a locale code different to that one you previously pretended to do in first place, of course. The language information used in both Texinfo source files and XHTML output produced by the functionality is determined by the user's session LANG environment variable. This variable can be customized in the graphical login screen before login, or once you've login by explicitly setting the value of LANG environment variable inside the ~/.bash_profile file. To create documentation manuals in English language the LANG environment variable must be set to en_US.UTF-8 or something similar. Likewise, if you want to create documentation manuals in a language other than English, be sure the LANG environment variable is set to the appropriate locale code. The appropriate locale code to set here can be found in the output produced by the locale -a | less command. When producing output from Texinfo source files using the makeinfo command (as in the texinfo-4.8-14.el5 package), the language information set by @documentlanguage is ignored in Info and HTML output, but cosidered by Tex program to redefine various English words used in the PDF output (e.g., Chapter, Index, See, and so on) based on the current language set in. The encoding information of documentation manuals produced through Texinfo documentation format is declared by Texinfo's @documentencoding command and can take either US-ASCII, ISO-8859-1, ISO-8859-15 or ISO-8859-2 as argument. Nevertheless, you should be aware that the functionality doesn't declare the @documentencoding inside Texinfo source files. Let's see why. When the @documentencoding command is set in Texinfo source files, the terminal encoding you use to read the Info output produced from such files must be set to that encoding information you provided as argument to @documentencoding command; this, before using an Info reader to open the Info output file in the terminal. Otherwise, when the terminal and the Texinfo source files encoding definition differ one another, characters defined through Texinfo's special way of producing floating accents won't be displayed as expected (even when the --enable-encoding is provided to makeinfo command). On the other hand, when the @documentencoding command is not set in Texinfo source files, it is possible to write and read documentation manuals using the UTF-8 encoding without needing to use Texinfo's special way of producing floating accents because the terminal encoding would be able to interpret the characters entered when the Texinfo source files were written in first place. When Texinfo's special way of producing floating accents isn't used, HTML entities are not produced in XHTML output produced by texi2html, nor in the HTML output produced by makeinfo, nor in PDF output. In this last case, when producing PDF output, you can realize what the floating accents are by trying to produce an accentuated Spanish i letter (e.g., í). When you do so, you'll note that that construction puts the accentuation mark over the i letter's dot, instead of removing the i letter's dot and put the accentuation mark on its place. In the case of XHTML output, however, it is possible to produce well localized XHTML output by setting <meta http-equiv="content-type" content="text/html; charset=UTF-8" /> on the head section of each XHTML output to instruct the web browsers what encoding to use to display the document content. Of course, in order to display the document content correctly, the web browser should provide support for UTF-8 encoding. These contradictions provide the reasons over which it was decided not to set the @documentencoding in those Texinfo source files produced by the functionality. Texinfo documentation format is very good producing online documentation for reading text terminals. It provides feautres to export source files to different output formats both for reading online and paper. However, localized documents becomes hard to maintain because it is required one document structure for each language you want to produce documentation for. Intermediate formats like XML and Docbook provide an alternative to centralize localization of Texinfo document source files, but there is no supported way inside &TCD; to transformed a localized XML file back into texinfo format, nor a way of producing well formed Docbook documents from Texinfo source files. Thus, one Texinfo source structure for each language to support is the solution adopted by functionality. When using Texinfo documentation format it is difficult to produce well localized PDF outputs, but it is possible to produce well localized Info, Text, and XHTML outputs as long as no document encoding be explicitly set inside Texinfo source files and UTF-8 be used as default terminal character encoding.