doxygen-users — List for users of doxygen

RE: [Doxygen-users] Using @link to reference a file

[Glenn M. <gle...@vo...>]

I had a tough time getting Doxygen to understand my links even when
using the <a href...> form. It coughed and choke the most on relative
paths.
=20
My solution was to insert something that I'd recognize, post-process the
file, and replace it with what was needed.
=20
I was already post processing the file to add navigation to the top and
copyright info to the bottom, anyway. Looking for my flags and replacing
them with something that worked was a minor extra step.
=20
Because I'm already post-processing, I'd be inclined to not use your
ALIAS definitions but to keep the @mylink and @endmylink delimiters. I'd
let them be the flags for the post-processor.
=20
Not what you were expecting.
=20
I have some open-source tools for post-processing (voyant_nav.pl)
available at www.voyanttech.com/tp_tools.zip (1.8 MB). Unzip and launch
tp_tools/_start_here.zip. Look up the perl programs (voyant_nav.pl).
=20
HTH
=20
Glenn

-----Original Message-----
From: Kevin Williams [mailto:KWi...@vi...]
Sent: Wednesday, March 13, 2002 11:08 AM
To: dox...@li...
Subject: RE: [Doxygen-users] Using @link to reference a file



Alright, I figured out how to make my alias ALMOST work.  Here's what
I've got:=20

  ALIASES  =3D "mylink=3D@htmlonly<a =
href=3D\"../Properties.html#@endhtmlonly"

  ALIASES +=3D "endmylink=3D@htmlonly\">View Properties</a>@endhtmlonly" =


Here's how it would be used:=20

  /**=20
   * A Cat object.=20
   *=20
   * @mylink Cat @endmylink=20
   */=20
  interface Cat=20
  {=20
  }=20

Here's what it produces:=20

  <a href=3D"../Properties.html# Cat">View Properties</a>=20

Note this space --------------^=20

I just need to get rid of that space!  Anyone have any ideas on that
one?=20

-- Kevin Williams=20
   Visionael Corporation=20
   kwi...@vi...=20

Re: [Doxygen-users] Doxygen: metrics utility

[Dimitri v. H. <di...@st...>]

On Wed, Mar 13, 2002 at 09:45:22AM +1000, Martin Bosticky wrote:
> Hi everyone.
>  
> In the change.log file i have found a new feature being a metrics utility.
> However i am having trouble following the instructions to get it. Can anyone
> help me?

Here are some quick instructions (for Unix):

Get the source distribution from CVS. Run configure. Go to the
addon/doxmlparser/src dir and run make. Then go to 
addon/doxmlparser/examples/metrics dir and run make again. If all went well
you have an executable "metrics" in this dir, which you can run with the
name of a directory containing doxygen-generated XML output as the only 
argument.

I hope this helps,

Regards,
  Dimitri

RE: [Doxygen-users] Using @link to reference a file

[Kevin W. <KWi...@vi...>]

Alright, I figured out how to make my alias ALMOST work.  Here's what I've
got:

  ALIASES  = "mylink=@htmlonly<a href=\"../Properties.html#@endhtmlonly"
  ALIASES += "endmylink=@htmlonly\">View Properties</a>@endhtmlonly"

Here's how it would be used:

  /**
   * A Cat object.
   *
   * @mylink Cat @endmylink
   */
  interface Cat
  {
  }

Here's what it produces:

  <a href="../Properties.html# Cat">View Properties</a>

Note this space --------------^

I just need to get rid of that space!  Anyone have any ideas on that one?

-- Kevin Williams
   Visionael Corporation
   kwi...@vi...

Re: [Doxygen-users] Bug in XML output

[Dimitri v. H. <di...@st...>]

On Wed, Mar 13, 2002 at 12:17:08AM +0100, Freudenberg, Thomas wrote:
> Hi.
> 
> There is a bug in the listofallmembers section in the XML output, when documenting a streaming operator. I.e. I have a following class:
> 
> class myclass
> {
> 	// ...
> 
> 	/** blabla */
> 	friend std::istream & operator>>( std::istream & is, myclass & q );
> }
> 
> XML output is something like
> 
> [...]
>       <member refid="classmyclass" prot="public" virt="non-virtual"><scope>myclass</scope><name>operator<<</name></member>
> [...]
> 
> As you see, the name tag is corrupted by the < characters. The detail information is correct, here the '<' are replaced by &lt;

Yes, more strings should have been filtered using convertToXML(). 
I'll fix this in the next release.

Regards,
  Dimitri

[Doxygen-users] Using @link to reference a file

[Kevin W. <KWi...@vi...>]

I'm using Doxygen 1.2.14 to document an IDL file and I want to have it
insert a link to a static HTML file (not generated by Doxygen) in another
directory.  Here's what I've tried:

  /**
   * This is a Thing
   *
   * @link ../ThingInfo.html Go here for information @endlink
   */
   interface Thing
   {
   }

Doxygen complains that I'm linking to an "unknown entity" named ../ThingInfo
and no link is generated.  According to the documentation for @link, I
should be able to  "create a link to an object (a file, class, or member)
with a user specified link-text".  Am I doing this wrong or is Doxygen
broken or what?

P.S. - This works, but is ugly:

  * <a href="../ThingInfo.html">Go here for information</a>

I've also tried writing an alias to output the above HTML with no luck
(seems to be a problem with '=' or '"' characters inside of an alias).

-- Kevin Williams
   Visionael Corporation
   kwi...@vi...

Re: [Doxygen-users] Understanding how Doxygen Documentation is generated

[Hunter M. <hma...@vi...>]

On Mon, Mar 11, 2002 at 10:04:46PM +0100, Dimitri van Heesch wrote:
> On Mon, Mar 11, 2002 at 01:44:15PM -0600, Scot Wilcoxon wrote:
> > That is why Doxygen has no ability to document program flow nor extracting 
> > program flow from the code.  You can't make it generate a text file with your 
> > comments of which functions are called in what sequence, what an "if" statement 
> > is doing, much less emit a GraphViz flowchart.
> 
> Hmm, I get the feeling someone is a little frustrated... Why not help to
> improve doxygen instead of complaining about it not working the way you want?

I think you (Scot W) may wish to look into XSLT processing of the Doxygen
XML output. 

	hunter

[Doxygen-users] Doxygen: metrics utility

[Martin B. <MBo...@op...>]

Hi everyone.
 
In the change.log file i have found a new feature being a metrics utility.
However i am having trouble following the instructions to get it. Can anyone
help me?
 
from Change.log: Added a very simple metrics utility (see
addon/doxmlparser/examples/metrics) which can compute some figures based on
the XML output generated by doxygen.
 
Thanks in advance


Martin Bosticky
Software Engineer

[Doxygen-users] Bug in XML output

[Freudenberg, T. <tho...@cy...>]

Hi.

There is a bug in the listofallmembers section in the XML output, when do=
cumenting a streaming operator. I.e. I have a following class:

class myclass
{
	// ...

	/** blabla */
	friend std::istream & operator>>( std::istream & is, myclass & q );
}

XML output is something like

[...]
      <member refid=3D"classmyclass" prot=3D"public" virt=3D"non-virtual"=
><scope>myclass</scope><name>operator<<</name></member>
[...]

As you see, the name tag is corrupted by the < characters. The detail inf=
ormation is correct, here the '<' are replaced by &lt;

Regards
Thomas

Re: [Doxygen-users] Bug? two classes derive a base class and yet the base class mentions only one of them

[Dimitri v. H. <di...@st...>]

On Tue, Mar 12, 2002 at 07:49:16PM +0000, Evil Kosh wrote:
> Hello,
> 
> I think I may have found a bug, I was wondering if this is known 
> about.  Perhaps someone has an explanation for
> 
> I have a base class IGraphics, it's derived in two versions DG8Graphics and 
> OGLGraphics, all three of the the classes are being included in the 
> documentation, but in the IGraphics documentation, it says that DG8Graphics 
> is the class which reimplements the methods in IGraphics, it makes no 
> mention of OGLGraphics, this is an extract from the documentation
> 
> Anyone know about this? perhaps a reason for it happening?

This is a bug indeed. I'll look into it.

Regards,
  Dimitri

[Doxygen-users] Bug? two classes derive a base class and yet the base class mentions only one of them

[Evil K. <evi...@ya...>]

Hello,

I think I may have found a bug, I was wondering if this is known 
about.  Perhaps someone has an explanation for

I have a base class IGraphics, it's derived in two versions DG8Graphics and 
OGLGraphics, all three of the the classes are being included in the 
documentation, but in the IGraphics documentation, it says that DG8Graphics 
is the class which reimplements the methods in IGraphics, it makes no 
mention of OGLGraphics, this is an extract from the documentation

**** IGraphics Docs ****

virtual void IGraphics::Begin3D  (  void     )  [pure virtual]

    Sets the Camera mode to 3D rendering

Implemented in DG8Graphics.

**** DG8Graphics Docs ****

void DG8Graphics::Begin3D  (  void     )  [virtual]

    Sets the Camera mode to 3D rendering

Implements IGraphics

**** OGLGraphics Docs ****

void OGLGraphics::Begin3D  (  void     )  [virtual]

    Sets the OpenGL system to render in a typical 3D display

This method only needs to be called if Begin2D was called previously. The 
default operation of the OpenGL system is 3D, so this method is called 
automatically to setup a 3D rendering system

Implements IGraphics.

*******************************************

shouldnt it say "Implemented in DG8Graphics, OGLGraphics" ????  Not just 
DG8Graphics

So the documentation for IGraphics is only saying that DG8Graphics 
reimplements the method Begin3D, when it's also being reimplemented in 
OGLGraphics too, so why doesnt it say so?

Anyone know about this? perhaps a reason for it happening?

oh, before anyone says I've got the grouping information wrong, check this out

/** @defgroup	Graphics_Group	Graphics Subsystem */

//==========================================
//	OPENGL PLATFORM
//==========================================
/** @defgroup	OGL_Graphics_Group	OpenGL Platform
  *	@ingroup	Graphics_Group
  */

/**	@defgroup	OGL_Texture_Group	OGL Textures
  *	@ingroup	OGL_Graphics_Group
  */

//==========================================
//	DG8 PLATFORM
//==========================================
/** @defgroup	DG8_Graphics_Group	DirectGraphics8 Platform
  *	@ingroup	Graphics_Group
  */

/**	@defgroup	DG8_Texture_Group	DG8 Textures
  *	@ingroup	DG8_Graphics_Group
  */

thats in a special file I tell doxygen to read before anyother, and then 
each class is prepended with the correct group information, so this is not 
the reason.  It's weird, I dont know what's causing it, perhaps you do =]


Thanks

kosh
  


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com

[Doxygen-users] Expanding macros within comments

[John S. <joh...@se...>]

Greetings,

Is there some documented/undocumented way of getting Doxygen 1.2.14 to
expand macro definitions within Doxygen comment blocks? i.e. assuming
that hours of feverish editting has produced:

#define MYMACRO(_a) _a
MYMACRO(foo)
/**
MYMACRO(bar)
*/


If I run doxyen -d Preprocessor on the above I get:

foo
/**
MYMACRO(bar)
*/

whereas what I would dearly like to get is:

foo
/**
bar
*/


Is there some magic EXPAND_MACROS_WITHIN_COMMENT_BLOCK thang somewhere I
can set?

Cheers,

John Sturton

[Doxygen-users] Email Rejected: Unknown or disallowed extension type

[<ro...@vo...>]

Received: from [198.76.25.3] (HELO nns.voyanttech.com)
  by voyanttech.com (CommuniGate Pro SMTP 3.4b3)
  with SMTP id 2005524 for gle...@vo...; Tue, 12 Mar 2002 02:19:23 -0700
Received: from usw-sf-list1.sourceforge.net (usw-sf-fw2.sourceforge.net [216.136.171.252])
	by nns.voyanttech.com (8.9.3+Sun/8.9.3) with SMTP id DAA04272
	for <gle...@vo...>; Tue, 12 Mar 2002 03:17:43 -0500 (EST)
Received: from localhost ([127.0.0.1] helo=usw-sf-list1.sourceforge.net)
	by usw-sf-list1.sourceforge.net with esmtp (Exim 3.31-VA-mm2 #1 (Debian))
	id 16kiPG-0001d2-00; Tue, 12 Mar 2002 01:17:18 -0800
Received: from smtp02.web.de ([217.72.192.151] helo=smtp.web.de)
	by usw-sf-list1.sourceforge.net with esmtp (Exim 3.31-VA-mm2 #1 (Debian))
	id 16kiOP-0001W3-00
	for <dox...@li...>; Tue, 12 Mar 2002 01:16:26 -0800
Received: from pd952ac19.dip.t-dialin.net ([217.82.172.25] helo=web.de)
	by smtp.web.de with asmtp (WEB.DE(Exim) 4.33 #28)
	id 16kiOH-00016G-00
	for dox...@li...; Tue, 12 Mar 2002 10:16:18 +0100
Message-ID: <3C8...@we...>
From: Thomas Vesper <tho...@we...>
Reply-To: tho...@po...
Organization: Powitec Intelligent Technologies GmbH
X-Mailer: Mozilla 4.74 [de] (X11; U; Linux 2.2.16 i686)
X-Accept-Language: en
MIME-Version: 1.0
To: "dox...@li..." 
 <dox...@li...>
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg=sha1; boundary="------------msB391707B6C41198781496466"
Subject: [Doxygen-users] & in Tagfiles
Sender: dox...@li...
Errors-To: dox...@li...
X-BeenThere: dox...@li...
X-Mailman-Version: 2.0.5
Precedence: bulk
List-Help: <mailto:dox...@li...?subject=help>
List-Post: <mailto:dox...@li...>
List-Subscribe: <https://lists.sourceforge.net/lists/listinfo/doxygen-users>,
	<mailto:dox...@li...?subject=subscribe>
List-Id: <doxygen-users.lists.sourceforge.net>
List-Unsubscribe: <https://lists.sourceforge.net/lists/listinfo/doxygen-users>,
	<mailto:dox...@li...?subject=unsubscribe>
List-Archive: <http://www.geocrawler.com/redir-sf.php3?list=doxygen-users>
X-Original-Date: Tue, 12 Mar 2002 10:16:16 +0100
Date: Tue, 12 Mar 2002 10:16:16 +0100

Dies ist eine kryptografisch unterzeichnete Nachricht im MIME Format.

--------------msB391707B6C41198781496466
Content-Type: multipart/mixed;
 boundary="------------A44896B7294998E791E4D781"

Dies ist eine mehrteilige Nachricht im MIME-Format.
--------------A44896B7294998E791E4D781
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hi there.

I just found a problem with an '&' in a page title like this:
  \page comserver W&T COM-Server
Everything works fine, except when I refer to the generated tag-file.
Then doxygen complains about a fatal error.
Neither '\&' nor '&amp;' works.

The only workaround I see is to abandon the '&'.

Greetings
Thomas
--------------A44896B7294998E791E4D781
Content-Type: text/x-vcard; charset=us-ascii;
 name="thomas.vesper.vcf"
Content-Transfer-Encoding: 7bit
Content-Description: Karte für Thomas Vesper
Content-Disposition: attachment;
 filename="thomas.vesper.vcf"

begin:vcard 
n:Vesper;Thomas
tel;cell:+49 163 3922260
tel;fax:+49 3677 465644
tel;work:+49 3677 465642
x-mozilla-html:FALSE
org:Powitec Intelligent Technologies GmbH
version:2.1
email;internet:tho...@po...
adr;quoted-printable:;;Friedrich-Ebert-Str. 25=0D=0A=0D=0A;Ilmenau;;98693;Deutschland
x-mozilla-cpt:;23872
fn:Thomas Vesper
end:vcard

--------------A44896B7294998E791E4D781--

--------------msB391707B6C41198781496466
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64

FOR ANTI-VIRUS SECURITY, THIS EMAIL HAS BEEN CLEANED.

REASON:
THE ATTACHMENT CONTAINED AN INVALID EXTENSION OF '.p7s'

[Doxygen-users] & in Tagfiles

[Thomas V. <tho...@we...>]

Hi there.

I just found a problem with an '&' in a page title like this:
  \page comserver W&T COM-Server
Everything works fine, except when I refer to the generated tag-file.
Then doxygen complains about a fatal error.
Neither '\&' nor '&' works.

The only workaround I see is to abandon the '&'.

Greetings
Thomas

[Doxygen-users] VB translator

[Alexander L. <li...@we...>]

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
Hi all,
<p>has someone thought of extending doxygen to parse visual basic source
or maybe there are some
<br>dirty hacked input filters out there?
<p>If my spare time will increase in future I am willing to contribute
to help extend doxygen (regarding the
<br>above topic or something which will let one configure the generated
output more dynamically ...)
<p>thank you and bye
<br>Alex
<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>

[Doxygen-users] Web newbie question

[Alexander L. <li...@we...>]

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
Hi all,
<p>since I am not very into html and web authoring topics I would like
to ask you a question:
<br>Is it possible to run the doxygen-search engine inside your browser
- without having the need
<br>to set up a fully featured web-server?
<p>thank you and bye
<br>Alex
<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>

[Doxygen-users] Wrong entries in References List, 1.2.14

[Bernd S. <str...@rh...>]

Hello,

last recently I stumbled across some code written and documented by others 
and I wondered why in the doxygen docs some methods are listed in the 
References list that are totally unrelated to that method. In the changelog 
there are some recent changes and bugfixes to that feature, but obviously 
something is still going wrong.

So far, the only methods involved are static member functions.

I've not subscribed to the mailing list... You can reach me via EMail for 
further information.

Bye,

Bernd Strieder

RE: [Doxygen-users] Understanding how Doxygen Documentation is ge nerated

[Voshell, J. <vo...@me...>]

Well... it's free, and you have the source, so if you don't like it, fix it.
(then post it so we all can benefit).


-----Original Message-----
From: Scot Wilcoxon [mailto:sc...@wi...]
Sent: Monday, March 11, 2002 2:44 PM
To: dox...@li...
Subject: Re: [Doxygen-users] Understanding how Doxygen Documentation is
generated


Quoting: Bob Stafford <do...@bo...>
> I'm trying to use doxygen to generate general documentation, in the same
> way that is appears it is used to generate the doxygen documentation
> itself, but I'm having some problems understanding how this documentation
> is generated.

I'm having similar problems and have concluded that the author of Doxygen
has 
limited its scope to only libraries and variable declarations.  A number of 
reported awkwardness in usage are due to people pushing through Doxygen's
fuzzy 
boundary between a library of functions and applications which reuse common 
functions.

I believe the Doxygen-generated documentation on its web site is produced by
a 
simple technique:  he's cheating.  

Doxygen can not create documentation for a program, only for a library.  So
the 
web site's Doxygen-created documentation is created from files with Doxygen 
commands, but that documenation is not within the Doxygen source code.

That is why the Doxygen source includes a "doc" directory full of
documentation 
files, and Doxyfile is within the doc directory.

That is why doxygen.cpp does not contain an @file Doxygen statement.

That is why doxygen.cpp does not have its own functions documented with
Doxygen.

That is why Doxygen does not have a command to create a link at the top of 
mainpage for Application programs.  No files are known as Programs.  Go to 
http://www.graphviz.org/ and look at the Doxygen documentation: one of the 
tools is called "dot" but try to learn anything about it..yes, its main() 
happens to be in dot.c -- then try to find one of the other utilities
without 
knowing what they are called.

That is why the function usage() prints the command line options, but to 
properly document a program you have to have the command line options three 
times: in the code which emits the usage message, in the Doxygen comments 
(after @file and @brief), and if you want them on the Doxygen-generated main

page again in a section labeled with @mainpage.

That is why the man page is labeled with language suffix such as ".c" in the

name: myutility.c.8 rather than myutility.8 -- and all the man pages get the

same suffix so if you make the main program be myutility.c.1 then all the 
function documentation also gets *.1.

That is why Doxygen has no ability to document program flow nor extracting 
program flow from the code.  You can't make it generate a text file with
your 
comments of which functions are called in what sequence, what an "if"
statement 
is doing, much less emit a GraphViz flowchart.

_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Understanding how Doxygen Documentation is generated

[Dimitri v. H. <di...@st...>]

On Mon, Mar 11, 2002 at 01:44:15PM -0600, Scot Wilcoxon wrote:
> Quoting: Bob Stafford <do...@bo...>
> > I'm trying to use doxygen to generate general documentation, in the same
> > way that is appears it is used to generate the doxygen documentation
> > itself, but I'm having some problems understanding how this documentation
> > is generated.
> 
> I'm having similar problems and have concluded that the author of Doxygen has 
> limited its scope to only libraries and variable declarations.  A number of 
> reported awkwardness in usage are due to people pushing through Doxygen's fuzzy 
> boundary between a library of functions and applications which reuse common 
> functions.
> 
> I believe the Doxygen-generated documentation on its web site is produced by a 
> simple technique:  he's cheating.  

Well, doxygen's documentation is generated by doxygen, so how is that cheating?

> Doxygen can not create documentation for a program, only for a library.  So the 
> web site's Doxygen-created documentation is created from files with Doxygen 
> commands, but that documenation is not within the Doxygen source code.

I guess you mean doxygen is meant for code related reference manuals and not
for user manuals. Well that's right. 

> 
> That is why the Doxygen source includes a "doc" directory full of documentation 
> files, and Doxyfile is within the doc directory.
> 
> That is why doxygen.cpp does not contain an @file Doxygen statement.
> 
> That is why doxygen.cpp does not have its own functions documented with Doxygen.
> 
> That is why Doxygen does not have a command to create a link at the top of 
> mainpage for Application programs.  No files are known as Programs.  Go to 
> http://www.graphviz.org/ and look at the Doxygen documentation: one of the 
> tools is called "dot" but try to learn anything about it..yes, its main() 
> happens to be in dot.c -- then try to find one of the other utilities without 
> knowing what they are called.
> 
> That is why the function usage() prints the command line options, but to 
> properly document a program you have to have the command line options three 
> times: in the code which emits the usage message, in the Doxygen comments 
> (after @file and @brief), and if you want them on the Doxygen-generated main 
> page again in a section labeled with @mainpage.
> 
> That is why the man page is labeled with language suffix such as ".c" in the 
> name: myutility.c.8 rather than myutility.8 -- and all the man pages get the 
> same suffix so if you make the main program be myutility.c.1 then all the 
> function documentation also gets *.1.
> 
> That is why Doxygen has no ability to document program flow nor extracting 
> program flow from the code.  You can't make it generate a text file with your 
> comments of which functions are called in what sequence, what an "if" statement 
> is doing, much less emit a GraphViz flowchart.

Hmm, I get the feeling someone is a little frustrated... Why not help to
improve doxygen instead of complaining about it not working the way you want?

Regards,
   Dimitri

[Doxygen-users] Related <PRE> issue?

[Andrew D. <ad...@ex...>]

I couldn't quite tell from previous posts if others are having this
same problem or just a related one. <PRE> formatting works properly in
HTML output, but in RTF, line breaks are omitted.

Adding <BR> tags after every line in the PRE section makes the RTF
look right, but then the HTML output is double-spaced.

I'm working on a Perl filter hack to fix this, but it would certainly
be more convenient to have it work correctly by itself.

Andrew Duncan
ad...@ex...

Re: [Doxygen-users] Understanding how Doxygen Documentation is generated

[Scot W. <sc...@wi...>]

Quoting: Bob Stafford <do...@bo...>
> I'm trying to use doxygen to generate general documentation, in the same
> way that is appears it is used to generate the doxygen documentation
> itself, but I'm having some problems understanding how this documentation
> is generated.

I'm having similar problems and have concluded that the author of Doxygen has 
limited its scope to only libraries and variable declarations.  A number of 
reported awkwardness in usage are due to people pushing through Doxygen's fuzzy 
boundary between a library of functions and applications which reuse common 
functions.

I believe the Doxygen-generated documentation on its web site is produced by a 
simple technique:  he's cheating.  

Doxygen can not create documentation for a program, only for a library.  So the 
web site's Doxygen-created documentation is created from files with Doxygen 
commands, but that documenation is not within the Doxygen source code.

That is why the Doxygen source includes a "doc" directory full of documentation 
files, and Doxyfile is within the doc directory.

That is why doxygen.cpp does not contain an @file Doxygen statement.

That is why doxygen.cpp does not have its own functions documented with Doxygen.

That is why Doxygen does not have a command to create a link at the top of 
mainpage for Application programs.  No files are known as Programs.  Go to 
http://www.graphviz.org/ and look at the Doxygen documentation: one of the 
tools is called "dot" but try to learn anything about it..yes, its main() 
happens to be in dot.c -- then try to find one of the other utilities without 
knowing what they are called.

That is why the function usage() prints the command line options, but to 
properly document a program you have to have the command line options three 
times: in the code which emits the usage message, in the Doxygen comments 
(after @file and @brief), and if you want them on the Doxygen-generated main 
page again in a section labeled with @mainpage.

That is why the man page is labeled with language suffix such as ".c" in the 
name: myutility.c.8 rather than myutility.8 -- and all the man pages get the 
same suffix so if you make the main program be myutility.c.1 then all the 
function documentation also gets *.1.

That is why Doxygen has no ability to document program flow nor extracting 
program flow from the code.  You can't make it generate a text file with your 
comments of which functions are called in what sequence, what an "if" statement 
is doing, much less emit a GraphViz flowchart.

RE: [Doxygen-users] Understanding how Doxygen Documentation is ge nerated.

[Prikryl,Petr <PRI...@sk...>]

Hi Bob,

Bob Stafford wrote...
> I'm trying to use doxygen to generate general documentation,
> in the same way that is appears it is used to generate the
> doxygen documentation itself, but I'm having some problems
> understanding how this documentation is generated.
> 
> In particular I have the following questions.
> 
> 1. How is the doxygen manual divided into 3 parts. For
>    example Part I starts with the following heading
> 
> Part I
> User Manual
> 
> Greping the doc directory in the doxygen source shows that
> the only place this text occurs is in doxygen_manual.tex (A
> latex file I believe). I've found nothing in the doxygen
> documentation about using latex files as part of the source
> for doxygen. So is this file generated by doxygen? If it is 
> generated by doxygen then where is the source that it used
> to get the "Part I User Manual" text?

The doxygen_manual.tex is not generated from doc sources. It
is (probably) a hand-crafted file that can be found at
doxygen/doc/ subdirectory. When you look inside the
doxygen/doc/Makefile, you can see that the
doxygen_manual.tex is processed by sed (replacing the
version mark by the version information), and the result is
placed into doxygen/latex/ subdirectory. The \part{} is the
LaTeX command that produces the "Part I...".

To summarize, the non-HTML documentation (i.e. DVI, PS, PDF)
is generated via LaTeX sources, and the doxygen_manual.tex
is the external file that defines how the pieces of the
documentation should be put together.

> 2. While trying to regenerate the doxygen documentation from
>    the doc directory, if I type make pdf in the ../latex
>    directory I get the following latex error. Do I need a
>    particular version of Latex.
> 
> [59]
> Underfull \vbox (badness 10000) has occurred while \output is active [60]
> Underfull \hbox (badness 10000) in paragraph at lines 167--167

These are only warnings related to the typographical quality
(basically, the line is shorter than it should be -- from
the typography point of view; just ignore this).

> 
> ) [61] (config.tex
> 
> ! LaTeX Error: Environment multicols undefined.
> 
> See the LaTeX manual or LaTeX Companion for explanation.
> Type  H <return>  for immediate help.
>  ...
> 
> l.25 \begin{multicols}
>                       {2}
> ?

This means that you do not have multicols.sty installed in
your LaTeX instalation.  This package is required.


> The make pdf command does work if I type it before doing the
> doxygen Doxyfile command in the doc directory.

I am not sure here, what Makefile is used in your case.  But
generally, the pdf is produced by ps2pdf from PS result, the
PS is produced by dvips from DVI result, the DVI is
produced by LaTeX from LaTeX sources, and the LaTeX sources
are produced by doxygen from your C/C++/Java source files
plus from your doc files (plus also from the
doxygen_manual.tex).  I guess that there may be some problem
in the Makefile that is used in your case.

(There are also alternative ways how PDF can be produced
from LaTeX.)

> 3. How do you generate different chapters. In my
>    documentation each /page ends up being a different
>    section in one big chapter.
[...]

As far as I know, the doxygen \page commands are transformed
to LaTeX \section commands.  This is fine for generating the 
"article" class of the document, which is used by doxygen
when generating LaTeX output (see the \documentclass LaTeX
command at beginning of the doxygen_manual.tex). The
"article" document class knows nothing about chapters.

The sections do not inject pagebreaks.  If you want to
inject a pagebreak into your LaTeX documentation, you can
use the following sequence in your doxygen doc files:

  \latexonly \pagebreak \endlatexonly
  
But you should know what you are doing from the LaTeX point
of view. (The \latexonly and \endlatexonly are doxygen
commands, the \pagebreak is the LaTeX comand.)

On the other hand, doxygen generates refman.tex for your project
documentation (instead of doxygen_manual.tex).  The chapters are
used for higher structure level than your \page level.  In other
words, the refman.tex uses the "book" document class where the
\chapter{} LaTeX command can be used, but doxygen reserves the
chapter level for other things.

Hope this helps,

  Petr

-- 
Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)

[Doxygen-users] Re: Using <PRE> with Doxygen (got a problem!)

[Asko K. <Ask...@fi...>]

Solving this by customized style sheets sounds like an elegant solution to
me. However, I'd like such modifications to be one-time jobs, not needing
any specialized "override" bat files. Can be flexible here, though... :)

- Asko

> -----Original Message-----
> From:	Zvi Mizrahi [SMTP:zv...@ga...]
> Sent:	11. maaliskuuta 2002 14:41
> To:	Asko Kauppi
> Subject:	Re: [Fwd: [Doxygen-users] Using <PRE> with Doxygen   (got a
> problem!)]
> 
> Asko, 
> I think this can be easily fixed by editing the cascading style sheet file
> 
> doxygen.css after Doxygen is running (in the html directory. 
> I have not tries it but ask the mailing list. Note that this file is 
> regenerated every running, so you need  to maintain a backup , and 
> override doxygen.css each time. 
> 
> Zvika 
> 
> Asko Kauppi wrote: 
> 
> Thanks for the support, Zvi! :) 
> 
> Also, the ability to have a fix-width font (as '<PRE>' does) is important 
> since the comments (at least ours) are indented using white space. 
> 
> Your idea of "do-it-yourself-filtering" crossed my mind but is too
> elaborous 
> for me at the moment. After all, I'm just evaluating Doxygen and don't
> want 
> to spend too much time filling up its holes. 
> 
> Let's see if the all-mighty authors are favorable for us on this. ;) 
> 
> - Asko 
> 
> > -----Original Message----- 
> > From: Zvi Mizrahi [SMTP:zv...@ga...] 
> > Sent: 11. maaliskuuta 2002 14:04 
> > To:   dox...@li... 
> > Cc:   Asko Kauppi 
> > Subject:      [Fwd: [Doxygen-users] Using <PRE> with Doxygen   (got a 
> > problem!)] 
> > 
> > Hi all, 
> > I have raised this issue a while ago. We are working on existing code 
> > and we need to maintains the CR-LF inside the paragraph lines. 
> > <PRE> and </PRE> does not help since it cause doxygen to ignore 
> > all tags between <PRE>   and </PRE>. 
> > 
> > The way we solve it is by writing a perl script that runs on the source 
> > code comments, copy them into temporary directory and add <BR> at 
> > the end of each line between paragraphs. Than we runs Doxygen on 
> > this directory. 
> > 
> > Doxygen is a very powerful tool, however the problem raised by Asko 
> > Kauppi limits the ability of the tool to process existing source code 
> > It would be nice to have a feature that will preserves any CR-LF exists 
> > in comments in between paragraphs. 
> > 
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
> > Zvika Mizrahi 
> > Galileo Technology Ltd - a Marvell Company 
> > Tel : +972-4-9999555 ext. 1177 
> > Fax : +972-4-9999334 
> > zv...@ga... 
> > www.marvell.com 
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
> >    << Message: [Doxygen-users] Using <PRE> with Doxygen   (got a
> problem!) 
> > >> 
> ########################################### 
> 
> This message has been scanned by F-Secure Anti-Virus for Microsoft
> Exchange.
> 
> -- 
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
> Zvika Mizrahi 
> Galileo Technology Ltd - a Marvell Company 
> Tel : +972-4-9999555 ext. 1177 
> Fax : +972-4-9999334 
> zv...@ga... 
> www.marvell.com 
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
> This message may contain confidential, proprietary 
> or legally privileged information. The information 
> is intended only for the use of the individual or 
> entity named above. If the reader of this message 
> is not the intended recipient, you are hereby 
> notified that any dissemination, distribution or 
> copying of this communication is strictly prohibited. 
> If you have received this communication in error, 
> please notify us immediately by telephone, or by 
> e-mail and delete the message from your computer. 
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
>  
###########################################

This message has been scanned by F-Secure Anti-Virus for Microsoft Exchange.

Re: [Doxygen-users] CVS build instruction broken.

[Walter F.J. M. <W.F...@gs...>]

Bob Stafford wrote:
> There seems to be a minor problem with the instructions for downloading and
> building doxygen with CVS. The build seems to fail because libpng is not
> included in the source directory after checking out the CVS repository.

True. Dimitri added a directory some time ago. I was traveling and
thus didn't update the CVS configuration. I caught up with this
this morning and hopefully fixed it.

Do a new CVS update and try to build doxygen again.

                        Cheers, Walter
--
Walter F.J. Mueller   Mail:  W.F...@gs...
GSI,  Abteilung KP3   Phone: +49-6159-71-2766
D-64291 Darmstadt     FAX:   +49-6159-71-2989
WWW:   http://www-kp3.gsi.de/www/kp3/people/mueller.html

[Doxygen-users] Friend and related functions discard the static and inline qualifiers.

[Enea Z. <zaf...@ti...>]

Hi all.

I am not sure if the following is a bug or I am simply overlooking some 
of the basics of doxygen ...

It seems to me that friend functions (or functions that are related to a 
class by using the command \relates) lose their "inline" and "static" 
attributes when they are reported in the "Friends And Related Function 
Documentation" section of the _class_ (note that the attributes of the 
friend function are correctly reported in the "Function Documentation" 
section of the _namespace_).

Apparently, the "friend" (or "related") attribute is overriding the 
other attributes, while in my opinion it should just be added to the 
list of attributes.

I am using doxygen 1.2.14 and a standard configuration file where I set

EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
SOURCE_BROWSER         = YES
INLINE_SOURCES         = YES


Regards,
Enea Zaffanella.

[Doxygen-users] CVS build instruction broken.

[Bob S. <do...@bo...>]

There seems to be a minor problem with the instructions for downloading and 
building doxygen with CVS. The build seems to fail because libpng is not 
included in the source directory after checking out the CVS repository.

Cheers

Bob Stafford