From 0d214f1c6accbf32ae02ffa4dfd559e1d9f40a46 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Sep 20 2011 02:21:34 +0000 Subject: Remove Texinfo chapter from `Documentation' part inside Tcar-ug documentation manual. Information related to Texinfo documentation format is now handled inside the `Documentation Formats' chapter. --- diff --git a/Manuals/Tcar-ug/Manuals/Texinfo.docbook b/Manuals/Tcar-ug/Manuals/Texinfo.docbook deleted file mode 100644 index 5347d0a..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo.docbook +++ /dev/null @@ -1,11 +0,0 @@ - - - Texinfo Backend - - &manuals-texinfo-intro; - &manuals-texinfo-structure; - &manuals-texinfo-templates; - &manuals-texinfo-localizing; - &manuals-texinfo-configuration; - - diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/configuration.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/configuration.docbook deleted file mode 100644 index 77852dd..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/configuration.docbook +++ /dev/null @@ -1,5 +0,0 @@ - - Texinfo Document Configuration - ... - - diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/intro.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/intro.docbook deleted file mode 100644 index a5f6cad..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/intro.docbook +++ /dev/null @@ -1,27 +0,0 @@ - - - Introduction - - - Texinfo is a documentation system that uses a - single source file to produce both online information and - printed output. This means that instead of writing two - different documents, one for the online information and the - other for a printed work, you need write only one document. - Therefore, when the work is revised, you need revise only that - one document. - - - - The texinfo documentation backend is a collection of function - scripts made available through the help - functionality of centos-art.sh script to - let you create and maintain documentation manuals using the - Texinfo format inside &TCAR;. The texinfo documentation - backend permits you to concentrate yourself on writing - documentation while the structuring tasks related to files - creation and actualization of menus, nodes and cross - references are all automatically arranged for you. - - - diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/localizing.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/localizing.docbook deleted file mode 100644 index e011c33..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/localizing.docbook +++ /dev/null @@ -1,205 +0,0 @@ - - - Texinfo Document Internationalization - - - To produce localized documentation manuals through texinfo - documentation backend 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 - locale and render - functionalities from centos-art.sh script - to maintain translation messages in different languages - through portable objets 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. - - - - Texinfo Document Language - - The language information of those documentation manuals - produced through texinfo documentation backend 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 - help functionality of - centos-art.sh script; 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 help - functionality of centos-art.sh script 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, based on the - output of 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. - - - - - - Texinfo Document Encoding - - The encoding information of documentation manuals produced - through texinfo documentation backend 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 - help functionality of - centos-art.sh script 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 - 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 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 help - functionality of centos-art.sh script. Now, - considering them, we can conclude that it is no viable way to - localize texinfo source files through - gettext procedures so one - documentation manual must be created for each language we - desire to support documentation for. In this configuration, - it is difficult the production of well localized PDF output, - 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. - - - - - diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook deleted file mode 100644 index e69de29..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ /dev/null diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook deleted file mode 100644 index 6b4073f..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook +++ /dev/null @@ -1,94 +0,0 @@ - - - Texinfo Document Structure - - - The document structure provided by texinfo backend creates the - organization needed to make documentation manuals scalable and - maintainable through time. Structuring considerations follow - the idea of an upside-down tree to organize chapters, - sections, subsections, and the like. The document initiates - with a Top node which contains manual's main definitions - (e.g., title, copyright note, abstract, and the list of - chapters). Inside each chapter the information is logically - organized in sections, subsections and subsubsections. - - - - The first time the documentation structure is created through - texinfo backend, the centos-art.sh script - considers the working directory you are placed in order to - determine where to store the documentation manual source - files. When the current working directory is branches/Manuals/Texinfo, the - documentation manual directory is created therein. On all - other situations, the documentation manual directory is - created under trunk/Manuals directory. Once - the documentation manual directory has been created, the - centos-art.sh script creates the related - definition files in conjuction with an appendix named - Licenses. The content stored in the Licenses - appendix isn't inside the documentation manual directory - itself, but refered from texinfo document templates as - described in . - - - - Inside the documentation manual directory, source files are - all stored inside language-specific directories. - Language-specific directories are necessary to implement - localization of source files written in texinfo format, as - described in . - - - - Inside the language-specific directory, the - ${MANUAL_NAME}.texinfo, - ${MANUAL_NAME}-index.texinfo, - ${MANUAL_NAME}-menu.texinfo and - ${MANUAL_NAME}-nodes.texinfo files exist to - set manual's main definitions (e.g., title, subtitle, author, - copyright notice, chapters, appendixes, indexes and all the - similar stuff a documentation manual should have). In - addition to these files, there is one directory for each - chapter created inside the manual. Inside each chapter - directory, the chapter.texinfo, - chapter-menu.texinfo and - chapter-nodes.texinfo files exist to - control section definitions related to the chapter directory - they belong to. The documentation manual content itself is - stored in section files (a.k.a. documentation - entries) suffixed with texinfo extension and arbitrary - names, as it is displayed in . - - - - Texinfo document structure - - Texinfo document structure - - - trunk/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}-index.texinfo - |-- ${MANUAL_NAME}-menu.texinfo - |-- ${MANUAL_NAME}-nodes.texinfo - `-- ${MANUAL_NAME}.texinfo - - - - - - diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/templates.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/templates.docbook deleted file mode 100644 index 0360e2c..0000000 --- a/Manuals/Tcar-ug/Manuals/Texinfo/templates.docbook +++ /dev/null @@ -1,126 +0,0 @@ - - - Texinfo Document Templates - - - Texinfo document templates provide the texinfo document design - model that centos-art.sh script needs in - order to create and maintain texinfo document structures like - that one described in . - - - - Texinfo document templates are language-specific. This means - that there is one texinfo document template for each language - you want to write documentation manuals in texinfo format. - Using one texinfo document template for each leanguage is - required because, in texinfo format, it is not possible to - retrive translatable strings from source files so translators - can localize documentation source files to other languages, - independently from documentors. To create documentation - manuals in different languages, it is required to write a - complete texinfo document structure for each language you plan - to write one documentation manual for; or what might be the - same, to duplicate the source documenation manual you want to - translate and do the translation inside the source files - themselves. This way, in order for the help - functionality of centos-art.sh script to - support creation and maintainance of documentation manual in - different languages, it is necessary that one texinfo document - template be available for each language you pretend to - support. - - - - In order to create multilingual texinfo document templates, - you can duplicate the texinfo document template used to build - documentation manuals in English language from branches/Scripts/Bash/Functions/Help/Texinfo/Templates/en_US - to a new directory at the same directory level and using the - language and country codification described in the standards - iso-639 and iso-3166, respectively. Once the directory has - been duplicated, get into it and localize all the files - inside it. At this point, after localizing files, the recently - created language-specific texinfo document template is ready - for production. - - - - - When you write documentation manuals for a language that - doesn't have a language-specific texinfo document template, - then the texinfo document template written in English language - is used for that document. - - - - - The directory structure used to organize texinfo document - templates take place under branches/Scripts/Bash/Functions/Help/Texinfo/Templates - directory, as displayed in . In this structure, - files suffixed with .texinfo extension exists to - modelate manual's source files. However, other files like - manual-ini.pl, - manual.sed and - manual.conf aren't related to manual's - source files, but to manual's output files. Some of these - files can be found inside and outside the language-specific - directories so as to control common and specific output - settings through them. - - - - Texinfo document template - - Texinfo document template - - - branches/Scripts/Bash/Functions/Help/Texinfo/Templates -|-- ${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 texinfo document templates, the Chapters directory organizes - chapter specific models used to create and maintain both - chapter and sections inside manuals. On the other hand, the - Licenses organizes - license information used by all manuals created from such - template. License information is not copied to documentation - manuals, but refered from them to 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. - - -