When a document is about to suffer major modifications, related modules should again pass through some steps of their life cycle.
In order to help translators, the templates should contain
the text of the original version. To do so, it is enough to copy
the original module content just when the writer passes the
pproof
step on that module.
Current overall report page has links to fully compiled
versions of the manuals in all languages. We should remove that
(see Section 3.4, “f3: Publish all available sub-documents”) and instead just put a link per
document to the master.top.{html,pdf}
.
This would add the need to perform weekly (or another, yet to be determined, period) compilations of master.top.{html,pdf} for all languages in order for them to be up-to-date all the time. This implies more load on the compilation machine, but a “light” one compared to all sub-document compilation (see Section 3.4, “f3: Publish all available sub-documents”).
Build an HTML page (make -C reports sub-docs-table.html) containing links to all HTML and PDF versions of all sub-documents available in all languages. This target will also compile all those sub-docs too, of course.
There's an
important prerequisite to this feature: all documents must have a
sub-doc per default. Therefore, the adddoc
target must be modified so that it adds to
manuals/New_Manual/conf.xml
a default
sub-doc, with no exclusions, called New_Manual
.
Needless to say, the overall report page should show a link to
this sub-docs page.
When one adds a new manual with plenty of modules, it is a hassle to assign all tasks for all modules in all languages.
Give the option to define (in conf/manual-default.xml) authors for all tasks in all languages:
<revisions> <lang lang="en"> <type> <name>lproof</name><author>tbn</author> </type> <type> <name>ispell</name><author>tbn</author> </type> <type> <name>pproof</name><author>tbn</author> </type> <type> <name>tproof</name><author>tbn</author> </type> <type> <name>translate</name><author>tbn</author> </type> <type> <name>write</name><author>tbn</author> </type> </lang> <lang lang="fr"> <type> <name>lproof</name><author>tbn</author> </type> <type> <name>ispell</name><author>tbn</author> </type> <type> <name>pproof</name><author>tbn</author> </type> <type> <name>tproof</name><author>tbn</author> </type> <type> <name>translate</name><author>tbn</author> </type> <type> <name>write</name><author>tbn</author> </type> </lang> </revisions>
for example.
This can replace the
<revisions> element in
conf/repository.xml
. Make sure to modify
accordingly all pieces of code that were referring to the old
<revisions> element to retrieve type names or authors.
It is necessary for authors that modify a module to be able to quickly check the output. When updating a module it is also necessary to quickly generate the revisions report to check everything is OK.
The way to achieve that is not
defined yet, perhaps creating a special document
(manuals/modules/
?) with all makefile targets
in it to get the desired result.
Compute the image dependencies in Makefile directly from the source (XML) document. That may significantly increase pre-compilation time...
To ensure
no tasks are forgotten, send all the tasks with no assigned author
(those set to tbn) to the project
administrator. It could be identified in
master.top.xml
by being the <editor>
instead of a simple <author>, or in the
conf/repository.xml
file, assigning an
administrator to each document.
Simply allow
you to define the images width not as a fixed value
(width="10cm"
) but as a width relative to the
media width (scale="80%"
). Just check that
works.
PSGML needs to access a parent document when editing a
module. Instead of pointing to a moving
manuals/Manual/master.xml
, define a fixed
master document which all modules would refer to.
This could be linked to the solution of ???.
Having the index
simply referred to as &index;
in
master.top.xml
generates parsing errors when
the index is not yet ready. Find a cleaner way to call the
index.
It would be nice to have a target that cleans up everything not included in repository.xml.
For example, let's say I start my own project and it will be only written in Spanish. So, instead of manually removing not pertinent things I want to issue something like make repository, and have all directories and files not included in repostory.xml wiped out.
A simple typo in a module can screw the compilation for a whole document.
add a make Module_name.commit target that checks the module's conformity to a DTD (and maybe other, yet to be defined, constraints too) and then commits it to CVS.
All compilation targets (printed, online, etc.) should be made
dependent on manuals/*/conf.xml
, so changes to
the manual's conf.xml
will force
re-compilation of the targets.
This must be done in such a way that only targets for the
corresponding manual is re-compiled. Example: if I make a
modification in manuals/Manual_1/conf.xml
I
only want Manual_1
to be re-compiled and not
Manual_2
, Manual_3
,
etc.