3. First stable version: 1.0

3.1. f0: Support major version numbers

When a document is about to suffer major modifications, related modules should pass again through some steps of their life cycle.

3.2. f1: Fill translations' templates with original text

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.

3.3. f2: Publish documents' guidelines in reports

Current overall report page has links to fully compiled versions of the manuals in all lanaguages. We should remove that (see Section 3.4) and instead just put a link per document to the master.top.{html,pdf}.

Note

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-documents compilation (see Section 3.4).

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.

3.5. f4: Define default author

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.

3.6. 583846-597703: Single module output and report

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.

3.7. f6: Compile only needed images

Compute the image dependencies in Makefile directly from the source (XML) document. That may significantly increase pre-compilation time...

3.8. f7: Send TBN tasks to project admin

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.

3.9. f8: Allow relative images width

Simply allow 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.

3.10. 608871: Fixed master.xml parent document for PSGML

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 Section 3.6.

3.11. f10: Clean index support

Having the index simply referred to as &index; in master.top.xmlgenerates parsing errors when the index is not yet ready. Find a cleaner way to call the index.

3.12. 566873: Clean repository

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 dirs and files not included in repostory.xml wiped out.

3.13. f11: check source files validity before commit

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.

3.14. f12: make all compilation targets depend on the manual's conf.xml file

All compilation targets (printed, online, etc.) should be made dependant 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.