420e77 Update `help' functionality:

Authored and Committed by areguera 13 years ago
    Update `help' functionality:
    
        Backends/Texinfo/texinfo_updateNodes.sh
    
            - When documentation entries are created for functions (files
              stored in the first directory level under
              `trunk/Scripts/Functions') a specially design template is
              used for it. This template was built using the `cp' command
              man page structure as reference.
    
            - When documentation entries are created for non-function
              directories, a general purpose structure is used to provide 
              goals, description, usage and related references to the
              documentation entry.
    
            - Start using subversion to copy files. This way, the action
              is also registered on subversion's logs.
    
        Backends/Texinfo/texinfo_updateOutputFileInfo.sh
    
            - Start using the option `--enable-encoding' when exporting to
              info format. This option permits to show special characters
              in Info or plain text output based on `@documentencoding'
              directive.
    
              Set this, all documents written in languages others than
              English must include the `@documentencoding' directive in
              order for info and text files output from them to show
              special characters. It is also required that the terminal
              enconding be the same of that defined by `@documentencoding'
              directory. For example, in the Spanish document we set the
              following directive on `repository.texinfo' file:
    
                @documentlanguage es
                @documentencoding ISO-8859-1
    
              These directives say that the document is in Spanish
              language and codified in iso-8859-1 standard. Now, after
              output the info file from this document and, in order for it
              to show special characters it is required that the terminal
              had been set to use ISO-8859-1 encoding, as well. Otherwise,
              the special characters may no be displayed as you expect.
              
        Backends/Texinfo/texinfo_updateOutputFileXhtml.sh
    
            - Add verification to templates and transformation commands
              required to produce XHTML output through texi2html.
    
            - Add verification to initialization files used by texi2html.
              These files are generally used to localized the output
              produced by texi2html from English to different languages.
    
            - Add language specification (`--lang') to texi2html command.
              This is the value used as key to determine what value to use
              when producing texi2html output in different languages.
    
            - Separate transformation commands in common and
              language-specific transformation commands.  This is required
              because we are supporting more than one language. For
              example, transformation used to build admonition in English
              language use one pattern (in English language) and
              transformation used to build admonitions in Spanish language
              use another pattern (in Spanish language). Other
              transformations like adding `class="www"' to `a' XHTML
              elements is common for all languages, so we kept it as
              common transformation.
    
        Backends/Texinfo/texinfo_createStructure.sh
    
            - Simplify code. Start using the `cli_getFilesList' function.
    
            - Stop using 'texinfo_updateChaptersFiles'. Start using
              `texinfo_createChapters' instead.
    
        Backends/Texinfo/texinfo_createChapter.sh
    
            - Update cli_getFilesList `--pattern'.
    
        Backends/Texinfo/texinfo_updateChaptersMenu.sh
    
            - Don't consider `* Index::' menu-line when the MENUCHAPTERS
              is built. This chapter is treated specially compared with
              `Directories' and `Licenses' chapters. Index is directly
              included at file `repository.texinfo' and uses the file
              `repository-index.texinfo' file as definition. These files
              are created the first time the documentation manual is
              created and `help' functionality doesn't modify them in
              anyway.
    
        Backends/Texinfo/texinfo_getEntry.sh
    
            - Fix invokation of cli_getRepoDirSource based on revision
              3194.
    
            - Use MANUAL_CHAPTER_NAME variable instead of fixed name. 
    
        Backends/Texinfo/texinfo_updateChaptersNodes.sh
    
            - Don't consider '* Index::' menu-line.
    
        Backends/Texinfo/texinfo_editEntry.sh
    
            - Remove MANUAL_CHAPTER_DIR verifications. They are already
              set as part of texinfo_createStructure.
    
            - Verify the parent directory of documentation entries. In
              order to create a documentation entry it is required that a
              parent directory for this documentation entry does exist.
              Otherwise stop script execution with an error message
              describing the issue.
    
        help_getOptions.sh
    
            - Don't suppress subversion actions internally when reading
              documentation entries.
    
        help.sh
    
            - Update texinfo manuals directory structure to support the
              documentation manual in different languages. I don't know of
              a `texi2po' command that can be used here (as we did with
              `xml2po' in SVG files), so one documentation manual
              structure is created for each language (based on LANG
              environment variable):
    
                trunk/Manuals/Texinfo
                |-- $LANG
                |   |-- Directories
                |   |   |-- chapter-menu.texinfo
                |   |   |-- chapter-nodes.texinfo
                |   |   |-- chapter.texinfo
                |   |   `-- trunk.texinfo
                |   |-- Licenses
                |   |   |-- chapter-menu.texinfo
                |   |   |-- chapter-nodes.texinfo
                |   |   `-- chapter.texinfo
                |   |-- repository-index.texinfo
                |   |-- repository-menu.texinfo
                |   |-- repository-nodes.texinfo
                |   `-- repository.texinfo
                    
              In this configuration, no translation is performed to file
              and directory names. Doing so let us to reuse them in all
              manual structures equally, no matter what the prefered
              language be.  This, for example, save us the work of
              considering the manipulation of different file names for
              different documentation manuals (e.g., in English we've the
              word `chapter', but in Spanish we've the word `capĂ­tulo'.)
              which is quiet different.
    
              The `Directories' chapter is created automatically when then
              documentation manual is created for the very first time. The
              documentation entries related to repository directories are
              stored herein, using the same names and organization that
              repository do (e.g., The `trunk.texinfo' file is the
              documentation entry of 'trunk/' directory.)
    
              The `License' chapter is created automatically when the
              documentation manual is created for the very first time. The
              licenses themselves are not copied here, but included from
              `trunk/Scripts/Functions/Help/Backends/Texinfo/$LANG/Licenses/'
              directory structure using the `@include' definition.
    
              The `repository-*.texinfo' files at the base directory
              structure contain document definitions, specific to the
              backend associates (e.g., `texinfo') and are created
              automatically when the documentation manual is created for
              the very first time.
    
              Common information to all languages (e.g., texi2html
              initialization files, CSS, and sed transformations) are
              placed in language-specific templates, a common place that
              all documentation manuals can reuse. For example, both
              English and Spanish XHTML documentation manuals use the same
              CSS definitions.
    
              Language-specific templates are stored inside the help
              functionality directory structure and are required in order
              for a new language-specific documentation manual to be
              created:
    
                trunk/Scripts/Functions/Help/Backends/Texinfo/Templates
                |-- $LANG
                |   |-- Directories
                |   |   |-- chapter-menu.texinfo
                |   |   |-- chapter-nodes.texinfo
                |   |   |-- chapter.texinfo
                |   |   |-- section-functions.texinfo
                |   |   `-- section.texinfo
                |   |-- Licenses
                |   |   |-- GFDL.texinfo
                |   |   |-- GPL.texinfo
                |   |   |-- chapter-menu.texinfo
                |   |   |-- chapter-nodes.texinfo
                |   |   `-- chapter.texinfo
                |   |-- repository-index.texinfo
                |   |-- repository-init.pl
                |   |-- repository-menu.texinfo
                |   |-- repository-nodes.texinfo
                |   |-- repository.sed
                |   `-- repository.texinfo
    
              The help functionality uses these file as reference to
              create documentation entries, translate English messages of
              texi2html to other languages, perform XHTML transformations
              (e.g., to create admonitions).
    
            - There is just one MANUAL_CHAPTER_DIR correct value. This is
              the place where repository documentation entries are stored
              in. All actions performed through help functionality will
              take place in this location. If you change something outside
              this structure (e.g., adding new authors to
              `repository.texinfo'), it is required that you take care of
              committing those by yourself. The help functionality hasn't
              modification scope there.
    
            - There is just one MANUAL_CHAPTER_NAME correct value. This is
              the name of the file (without extension) we use to store
              documentation manual main files (e.g., `repository.texinfo',
              `repository-menu.texinfo', `repository-nodes.texinfo', etc)
    
            - Remove unnecessary definitions of MANUAL_CHAPTER_NAME and
              MANUAL_CHAPTER_DIR.
    
            - Readjust subversion verifications. When the manual is
              created for the first time, commit from working copy to
              central repository. In normal workflow, changes are braught
              from central repository first, later changes from the
              working copy are uploaded. At this poing a clean state of
              the working copy must be set, so an action is performed.
              This action may modify the state of the workgin copy so
              another subversion verification is required here to commit
              any local change up to central repository.
    
    
        
file modified
+50 -73