[Babeldoc-devel] Documenting pipeline stage examples

[David G. <dg...@co...>]

Hello to the great and powerful list,

My desire is to create examples for the pipeline stages and place them with 
the descriptions.  Why there, you ask?  As I create pipelines with Babeldoc, 
I sit with the manual open to the stage descriptions so that I know what 
options are available.  It is *very* convenient to have the examples at hand 
with the options so that I know how to implement them.  Going to somewhere 
else in the manual, or to the examples area of the application itself, tend 
to be distracting (IMHO, of course).

Currently the options portion of the manual is auto-generated, with the 
descriptions and options pulled from the actual classes.  To be consistent, 
the examples should also be pulled from the classes, which would mean adding 
another attribute to each pipeline stage class (like, oh I don't know, 
'examples'...?), and modifying the documentation pipeline to include them, as 
well.  I can do this.

However, I'm unclear as to the advantage of the current structure. I 
understand that there is some advantage in using the properties files so that 
translations can be easier to maintain, but since the bulk of the manual is 
in docbook format, it seems that the better solution is to keep everything in 
the same format for ease of maintenance (and translation).  If the concern is 
that people will add options and forget to update the documentation, then 
perhaps we can limit the extaction to just the options, and the description 
can be maintained in the docbook?  Or else, as part of the build process, 
compare extracted options to documented options and flag mis-matches?

I guess I don't really see a strong advantage to the current structure, and 
trying to update it is showing some definite limitations... :-)  Can someone 
let me know if I've missed anything?


Thanks,

David



-- 
David Glick
Transmit Consulting, Inc
619-475-4052
dg...@tr...