[Doxygen-develop] new feature proposal: filter maps

[Francesco M. <f18...@ya...>]

Hi,
    I'd like to propose a new feature for Doxygen; if doxy devs find it 
interesting I'd be willing to provide a patch to implement it.

Using doxygen in a big project I started using doxygen grouping features 
and I must say they're very useful. However the groups created go in the 
HTML output under the "Modules" tab. Unfortunately this is very 
misleading in the context of that project.

I know doxygen can't know that I'd prefer "categories" as tab's label 
since I'm putting there groups of classes classified by category :)

However I think that it shouldn't be difficult to add to Doxygen a 
generic system which allows to override the default strings returned by 
the Translator-derived class selected for use.

I.e. we could add an option, say "OUTPUT_FILTER", which allows the user 
to specify a text file to use as "filter map".
Suppose I want in my project to have "Modules" label (returned by 
trModules() function) replaced by a "SomethingElse" label and  the text 
returned by trGeneratedAutomatically(const char*s) replaced by 
"Generated for " + s + " by Doxygen".
Then I could simply write in the "filter map":

trModules=SomethingElse
trGeneratedAutomatically=Generated for \1 by Doxygen

i.e. use argument substitution like it's done for ALIASes.

Doxygen modifications would consist in:
  1) creation of the control code for the new option
  2) in the setTranslator() function, if OUTPUT_FILTER option is 
non-empty, assign to theTranslator global the instance of a new 
TranslatorFilter (derived from Translator) chained to the "real" 
translator instance (e.g. TranslatorEnglish)
  3) write the TranslatorFilter; for each trXXX() function it should 
read the message from the filter map; if the message is there, just 
substitute \1, \2... and return the custom text; otherwise return 
m_realTranslator->trXXX();

Using a static "filter map" as I suggested means however that functions 
like trClass() which takes boolean to "decide" to return a plural form 
or not, and in general all trXXX() functions which involve "decision" 
could not be filtered in a smart way (i.e. doing decisions), since 
decision constructs would be an overkill for both the filter map parser 
and in general for this feature.

However the trXXX() functions which take such booleans are really few 
and the main things one may need to filter are argument-less trXXX() 
functions.

Dimitri, what do you think of this idea?
It should be an easy-to-implement and fairly robust solution, which 
avoids the user to install sed and write sed postprocessing scripts to 
fix the naming of some fixed labels in the output....

Thanks,
Francesco