Re: [Doxygen-develop] Adding of new (all) HTML entities? A one line solution?

[Xavier O. <xav...@an...>]

Dimitri van Heesch wrote:

> On Thu, Jul 19, 2001 at 12:37:10PM +0200, Xavier Outhier wrote:
> > Hi,
> >
> >
> > As far as I understand, what is to be done for each new entity
> > is the following:
> >
> > -1 Add a new pure virtual method named writeEntity() in
> >     class BaseOutputDocInterface (outputgen.h)
> > -2 Add a new method
> >     void writeEntity()
> >     { forall(&OutputGenerator::writeEntity); }
> >    in class OutputList (outputlist.h)
> > -3 Add non pure virtual method in generators:
> >     void writeEntity()        {}
> >    in classes
> >     class ManGenerator (mangen.h)
> >     class LatexGenerator (latexgen.h)
> >     class HtmlGenerator (htmlgen.h)
> >
> > Remarks:
> > I do not understand what doc.cpp does really. I suppose it has also
> > to be changed but I don't know how.
>
> doc.cpp is a generated file. Look at the flex file doc.l: You'll see lines like
> these:
>
> <DocScan,Text>"&"[cC]"cedil;"           { outDoc->writeCCedil(yytext[1]); }
>
> these consist of a set of states (between <>), a regular expression,
> and some code.
>
> The code is executed when the input matches the regular expression. yytext
> is a char* containing the actual text that was matched. So the
> above matches &ccedil; and &Ccedil;
>
> > Besides, I know what to do with HTML and LaTeX (maybe not for
> > all symbols, I have to check in my documentation) but I don't know
> > what to do with man.
>
> This has always been a mistery to me too.

The mystery will be thicker now.

> > Questions:
> > Is the process (with the 3 steps) correct? Is something missing?
>
> Seems ok to me.
>
> > As my free time is so precious (as for everybody), is it possible
> > tha I only change the files and send them back for merging,
> > compiling and so on?
>
> Yes, that is fine. You can choose to do only those entities that you
> need as well.

[...]
Until discussion with Petr is not over, I will do it.

I wonder if the work, allowing all entities to be transparent
for Doxygen, could not be done in a straight forward ...
at least for HTML output.

I propose that:
 -1 Add a new method in BaseOutputDocInterface
virtual void writeEntity(const char* const text) = 0;
-2 Add a new method
    void writeEntity()
    { forall(&OutputGenerator::Entity); }
   in class OutputList (outputlist.h)
-3 Add non pure virtual method in generators:
    void writeSpecCharEntity()        {}
   in classes
    class ManGenerator (mangen.h)
    class LatexGenerator (latexgen.h)
    class HtmlGenerator (htmlgen.h)

The straight forwardness is for HTML only (later
intermediate XML):
void HtmlGenerator::writeEntity(const char* const text)
{ t << "&" << text << ";" ;}

doc.l would be modify and this line added:
<DocScan,Text>"&"[a-zA-Z0-9]{1}";"   { outDoc->writeEntity(yytext[1]); }
<DocScan,Text>"&"[a-zA-Z0-9]{2}";"   { outDoc->writeEntity(yytext[2]); }
<DocScan,Text>"&"[a-zA-Z0-9]{3}";"   { outDoc->writeEntity(yytext[3]); }
<DocScan,Text>"&"[a-zA-Z0-9]{4}";"   { outDoc->writeEntity(yytext[4]); }

I have several questions...:

 -Q1: Are the following single line could replace the 4 lines?
<DocScan,Text>"&"[a-zA-Z0-9]{1,4}";"   { outDoc->writeEntity(yytext[4]); }
(I'm very lazy! :-)
-Q2:  There is a theorical problem: what is the order of scanning? to be
         backward compatible, the added regex should be check if nothing
         else has already matched.
-Q3: Could it be all what to do if later Doxygen use XML (DocBook or
        other)? Maybe, we would have to remove all the single entities already
        added?

... and some remarks:
 - R1: If matching order is configurable, then it would solved all HTML
          entities (and SGML, sorry I'm really not a specialist of this domain),
          wouldn't be?
 - R2: For LaTeX, RTF and man (but not XML), more work should be
          done. Is a big switch reasonable in this case? There would be
          255 cases if all entities defined in HTML 4.0 are used.
          But if the current discussion on XML leads to have a runnable version
          in less that 2 or 3 months, it maybe not useful to do that work.
          If it's for longer term (I think it will), then I could begin to do that
          at least for LaTeX.
 - R3: If the "one line" solution is not possible I will only do the changes
          for greek letters (HTML and LaTeX) that could also be useful for
          others.

Waiting the answers to all my questions I will work a little for me. :-)

Xavier.