Thread: [Doxygen-users] alias example in manual does not work properly

Brought to you by: dimitri

doxygen-users

[Doxygen-users] alias example in manual does not work properly

From: Phil E. <ph...@ja...> - 2002-03-27 06:47:46

The manual for 1.2.14 shows an example for the \if command in section 22.37.  It involves an alias section like

    ALIASES = "english=\if english" \
              "endenglish=\endif" \
              "dutch=\if dutch" \
              "enddutch=\endif"

and then the conditional blocks are written

    \english
    ....
    \endenglish

We're using this exact same technique, but we get a warning,

  1556: Documentation block ended in the middle of a conditional section!

The line number is in the middle of a block of code, and the entire
documentation block is not emitted.  (I think this may actually be the
cause of the conditional documentation bug I reported earlier.)

Replacing the aliased \if and \endif commands with regular \if and \endif
causes the warning to stop and the conditional sections to work properly.
I haven't tested this with the code being used in the previous bug report (it
takes about ten minutes for a doxygen run, so I can't spend all day on it),
but if this works around the bug, then we'll just have to give up on using
aliases for conditional blocks.


Phil

-- 
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams

Re: [Doxygen-users] alias example in manual does not work properly

From: Alexander L. <li...@we...> - 2002-03-27 07:53:05

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
I found that "bug" too but didn't realized that it is a bug. I tried to
define some aliases to include the CVS header verbatim
<br>style. So I added the alias section:
<br>&nbsp;&nbsp;&nbsp; ALIASES = "cvsid=@version @verbatim" \
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"endcvsid= @endverbatim"
<br>to my doxygen config file. It just behaves like Phil described: the
whole documentation block is removed from the generated
<br>documentation. When I replace the two commands with the plain verbatim/endverbatim
commands everything works fine.
<p>Alex
<p>Phil Edwards schrieb:
<blockquote TYPE=CITE>The manual for 1.2.14 shows an example for the \if
command in section 22.37.&nbsp; It involves an alias section like
<p>&nbsp;&nbsp;&nbsp; ALIASES = "english=\if english" \
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"endenglish=\endif" \
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dutch=\if dutch" \
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"enddutch=\endif"
<p>and then the conditional blocks are written
<p>&nbsp;&nbsp;&nbsp; \english
<br>&nbsp;&nbsp;&nbsp; ....
<br>&nbsp;&nbsp;&nbsp; \endenglish
<p>We're using this exact same technique, but we get a warning,
<p>&nbsp; 1556: Documentation block ended in the middle of a conditional
section!
<p>The line number is in the middle of a block of code, and the entire
<br>documentation block is not emitted.&nbsp; (I think this may actually
be the
<br>cause of the conditional documentation bug I reported earlier.)
<p>Replacing the aliased \if and \endif commands with regular \if and \endif
<br>causes the warning to stop and the conditional sections to work properly.
<br>I haven't tested this with the code being used in the previous bug
report (it
<br>takes about ten minutes for a doxygen run, so I can't spend all day
on it),
<br>but if this works around the bug, then we'll just have to give up on
using
<br>aliases for conditional blocks.
<p>Phil
<p>--
<br>If ye love wealth greater than liberty, the tranquility of servitude
greater
<br>than the animating contest for freedom, go home and leave us in peace.&nbsp;
We seek
<br>not your counsel, nor your arms.&nbsp; Crouch down and lick the hand
that feeds you;
<br>and may posterity forget that ye were our countrymen.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Samuel Adams
<p>_______________________________________________
<br>Doxygen-users mailing list
<br>Dox...@li...
<br><a href="https://lists.sourceforge.net/lists/listinfo/doxygen-users">https://lists.sourceforge.net/lists/listinfo/doxygen-users</a></blockquote>

<pre>--&nbsp;
Alexander Lichius
Diplom-Ingenieur
Communication and Information Systems
Werum Software &amp; Systems AG&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Wulf-Werum-Strasse 3 | D-21337 Lueneburg
Tel. +49 4131 8900-623 | Fax +49 4131 8900-20&nbsp;
<A HREF="mailto:li...@we...">mailto:li...@we...</A> | <A HREF="http://www.werum.de">http://www.werum.de</A></pre>
&nbsp;</html>

Re: [Doxygen-users] alias example in manual does not work properly

From: Phil E. <ph...@ja...> - 2002-03-27 20:03:26

On Wed, Mar 27, 2002 at 09:02:42AM +0100, Alexander Lichius wrote:
> I found that "bug" too but didn't realized that it is a bug. I tried to
> define some aliases to include the CVS header verbatim
> <br>style. So I added the alias section:
> <br>&nbsp;&nbsp;&nbsp; ALIASES = "cvsid=@version @verbatim" \
> bsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
> "endcvsid= @endverbatim"
> <br>to my doxygen config file. It just behaves like Phil described: the
> whole documentation block is removed from the generated
> <br>documentation. When I replace the two commands with the plain verbatim/endverbatim
> commands everything works fine.

I've gone through and replaced all the the aliases with plain if/endif
commands, and things are working better.  (Not perfetly, but better.)
Either the alising code needs to be redone, or the example in the manual
should be removed.

It appears (this is only a guess) that the alias replacements are done
late in the processing.  We just experimented with an alias like

    "foo=This is some very common text."

But then the @foo in the documentation blocks goes unnoticed, and the output
contains an actual "@foo".  Perhaps this is beyond what the aliases were
originally intended for, since there is no actual Doxygen @ command in
the replacement text.  Bummer, that could have saved us a lot of typing.  :-)

I briefly looked at the source for 1.2.14, to try and move alias expansion
earlier in the processing, but couldn't find where to make such a change.

Phil

-- 
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams

Re: [Doxygen-users] alias example in manual does not work properly

From: Dimitri v. H. <di...@st...> - 2002-03-28 21:32:57

On Wed, Mar 27, 2002 at 03:03:15PM -0500, Phil Edwards wrote:
> On Wed, Mar 27, 2002 at 09:02:42AM +0100, Alexander Lichius wrote:
> > I found that "bug" too but didn't realized that it is a bug. I tried to
> > define some aliases to include the CVS header verbatim
> > <br>style. So I added the alias section:
> > <br>&nbsp;&nbsp;&nbsp; ALIASES = "cvsid=@version @verbatim" \
> > bsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
> > "endcvsid= @endverbatim"
> > <br>to my doxygen config file. It just behaves like Phil described: the
> > whole documentation block is removed from the generated
> > <br>documentation. When I replace the two commands with the plain verbatim/endverbatim
> > commands everything works fine.

Alexander: please don't send HTML to the mailing list!

> 
> I've gone through and replaced all the the aliases with plain if/endif
> commands, and things are working better.  (Not perfetly, but better.)
> Either the alising code needs to be redone, or the example in the manual
> should be removed.
> 
> It appears (this is only a guess) that the alias replacements are done
> late in the processing.  We just experimented with an alias like
> 
>     "foo=This is some very common text."
> 
> But then the @foo in the documentation blocks goes unnoticed, and the output
> contains an actual "@foo".  Perhaps this is beyond what the aliases were
> originally intended for, since there is no actual Doxygen @ command in
> the replacement text.  Bummer, that could have saved us a lot of typing.  :-)

Please report such behaviour as a bug report to me (or the bug tracker
at sourceforge) and include a real source fragment and the config file.
Don't forget to mention the version of doxygen and the platform you 
are using.

> 
> I briefly looked at the source for 1.2.14, to try and move alias expansion
> earlier in the processing, but couldn't find where to make such a change.

The substitutions are done in the source parsing phase (look for aliasDict in
scanner.l). This should be early enough I suppose.

Regards,
  Dimitri

[Doxygen-users] [Doxygen] SGI IRIX problems

From: Henrik P. <hen...@Un...> - 2002-03-27 09:06:28

Attachments: dot.cpp.diff memberdef.cpp.diff

Hi Dimitri, hi all -

I compiled DOXYGEN-1.2.14 on my IRIX 6.5 box (native CC compiler) and had to
make the following changes to the code located in doxygen-1.2.14/src

1) changed 'dot.cpp' (see attachment dot.cpp.diff)
2) changed 'memberdef.cpp' (see attachment memberdef.cpp.diff)
3) 'translator_fr.h' and 'translator_pt.h' have DOS-like linebreaks - this
can not be processed so I had to run a to_unix (on Linux: dos2unix ?!) on
them

to 1) and 2)
The code in these files contain typecasts from pointer to int - this is no
good practice - I'm not sure, if I did it right, but as a quick hack, I
provided a union for the conversion like
union _castPtr {
  void* ptr;
  int i;
};
... assigned the pointer to 'ptr' and used the integer 'i' - this compiles
and the doxygen output looks ok (but my compound list is empty - not sure,
if it should be).

Thanks for the great tool,
-- Henrik

-------

Dipl.-Inform. Henrik Putzer

Universitat der Bundeswehr Munchen		Tel.: +49-(0)89-6004-3579
Werner-Heisenberg-Weg 39			Fax: +49-(0)89-6004-2082
85579 Neubiberg