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.