Re: [Doxygen-develop] new feature proposal: filter maps

[Dimitri V. H. <do...@gm...>]

Hi Francesco,

On 21 mrt 2008, at 10:59, Francesco Montorsi wrote:

> Hi,
>    I have some free time in these days and I'd like to implement this
> new feature if it's ok to do it as I described... however I still have
> got no clear comments in this sense...
>
> Please tell me if a patch implementing this proposal would be  
> accepted.
>
> Thanks,
> Francesco
>
>
> Francesco Montorsi ha scritto:
>> 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....

It sounds a bit too much like a hack to me, so I'm not too  
enthusiastic about it.
A better solution would then be to allow translators to be plugins  
loaded at
startup. Either as a dynamically loadable library (but that is  
difficult to do in a portable way)
or as an XML file. One can even go one step further and implemented  
item 9 on the todo
list (http://www.doxygen.org/todo.html), i.e. a template file that  
defines the structure of the output.

Regards,
   Dimitri