doxygen-users

RE: [Doxygen-users] Re: files order

[Wagner, V. <VW...@se...>]

You didn't mention which output you're using.  In HTML 'order' matters
little.

-----Original Message-----
From: Angela Stazzone [mailto:sta...@sa...]
Sent: Thursday, 2001 May 31 12:33
To: doxygen
Subject: [Doxygen-users] Re: files order


Angela Stazzone wrote:

> Hi all,
>
> I'd like the doxygen documentation of my project to be in "logical"
> order; this means that if a class A derive from another class B, I want
> the documentation of A comes before the documentation of B.
> I tried to set to NO the SORT_MEMBER_DOCS tag, but the result is not
> what I want.
>
> Any suggestion?
>
> Thanks,
>             Angela.

I think I made a "little" mistake!

... if a class A derive from another class B, I want
the documentation of A comes AFTER the documentation of B.

Sorry!

Thanks,
   Angela.




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


This transmission may contain information that is privileged, confidential
and exempt from disclosure under applicable law.
If you are not the intended recipient, you are hereby notified that any
disclosure, copying, distribution, or use of the information contained
herein (including any reliance thereon) is STRICTLY PROHIBITED.
If you received this transmission in error, please immediately contact the
sender and destroy the material in its entirety, whether in electronic or
hard copy format.
Thank you

Re: [Doxygen-users] Re: files order

[Roberto B. <ba...@cs...>]

"Wagner, Victor" wrote:
> 
> You didn't mention which output you're using.  In HTML 'order' matters
> little.
> 
> Angela Stazzone wrote:
> ... if a class A derive from another class B, I want
> the documentation of A comes AFTER the documentation of B.

Hi Victor,

you right, in HTML this is not problematic.  But in, e.g.,
PDF versions that are meant to be printed this is a big problem.
For this kind of documents, I would like to influence Doxygen
about the order in which program elements are described.
As I said, I believe this is important for printed documentation.

Any hints on how we can achieve this?
All the best,

    Roberto

-- 
Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:ba...@cs...

[Doxygen-users] Re: files order

[Stephen G. <ste...@cl...>]

It is true that the HTML output can be accessed in any order, but it can still
be useful to have a 'natural reading order'. It is an advantage of any
hyper-linked document that you can leap around, but you still benefit from being
able to refer back to a structured overview.

To that end, Angela's request just scratches the surface :-)

The documentation for a library - in particular - consists of a lot more than
just the API documentation (which Doxygen excels at). Coming to the docs for the
first time, whether using online (HTML) or printed versions, a user has to be
able to find out what the library is intended to do, have a structured
walk-through from "this is how to use the library in the simplest way" and
introducing the functionality in a 'sensible' order.

Then there are the ancillary details, such as file formats, that the library as
a whole manipulates; if these include, say, an XML-based configuration format
then there is a need for a set of examples to illustrate using that format.

You can patch together something that almost works - for example, using lots of
extra pages and \ref's; the mainpage can be carefully structured to act as a
contents page. Doing this by hand has a number of problems, including:

- it is a lot of work even to do even simply!

- the structure is not reflected in any of the lists that Doxygen generates, so
selecting the 'examples' link from the menu does not present any obvious
starting point. Looking at the 'related pages' list is sometimes not much help
either.


There is a very great advantage to using Doxygen for worked examples: the code
fragments shown in the docs are taken directly from complete  sample programs,
which are available to the reader to compile and run. By putting the examples
into the Makefiles along with the library itself you are guaranteed that the
examples are up to date and do, indeed, compile.

What I'd like to be able to do is something structured like - just to pick the
most recent example I have to hand - a combination of  the O'Reilly "Java in a
Nutshell" and "Java Examples in a Nutshell" books (but for much smaller
libaries, I hasten to add; still an ambitious goal :-)

Perhaps if one thought about what something like a "Tex to HTML" converter does
(in terms of taking an already structured document and making it browseable) and
consider what could be added to Doxygen to let it (at the user's discretion, of
course) add some structure to the discourse portion of program documentation?

Stephen Goudge

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf Of Wagner,
> Victor
> Sent: 04 June 2001 15:25
> To: 'dox...@li...'
> Subject: RE: [Doxygen-users] Re: files order
>
>
> You didn't mention which output you're using.  In HTML 'order' matters
> little.
>
> -----Original Message-----
> From: Angela Stazzone [mailto:sta...@sa...]
> Sent: Thursday, 2001 May 31 12:33
> To: doxygen
> Subject: [Doxygen-users] Re: files order
>
>
> Angela Stazzone wrote:
>
> > Hi all,
> >
> > I'd like the doxygen documentation of my project to be in "logical"
> > order; this means that if a class A derive from another
> class B, I want
> > the documentation of A comes before the documentation of B.
> > I tried to set to NO the SORT_MEMBER_DOCS tag, but the result is not
> > what I want.
> >
> > Any suggestion?
> >
> > Thanks,
> >             Angela.
>
> I think I made a "little" mistake!
>
> ... if a class A derive from another class B, I want
> the documentation of A comes AFTER the documentation of B.
>
> Sorry!
>
> Thanks,
>    Angela.
>
>
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> http://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>
> This transmission may contain information that is privileged,
> confidential
> and exempt from disclosure under applicable law.
> If you are not the intended recipient, you are hereby
> notified that any
> disclosure, copying, distribution, or use of the information contained
> herein (including any reliance thereon) is STRICTLY PROHIBITED.
> If you received this transmission in error, please
> immediately contact the
> sender and destroy the material in its entirety, whether in
> electronic or
> hard copy format.
> Thank you
>
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> http://lists.sourceforge.net/lists/listinfo/doxygen-users
>

RE: [Doxygen-users] Re: files order

[Stephen G. <ste...@cl...>]

Replying to my own message:

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf Of Stephen
> Goudge
> Sent: 05 June 2001 09:43
> To: dox...@li...
> Subject: [Doxygen-users] Re: files order
> 
> 
> It is true that the HTML output can be accessed in any order, 
> but it can still
> be useful to have a 'natural reading order'. It is an advantage of any
> hyper-linked document that you can leap around, but you still 
> benefit from being
> able to refer back to a structured overview.
<snip>

looking through some archived messages, I thought this was worth re-posting:

> -----Original Message-----
> From: Jani Kajala [mailto:jan...@re...]
> Sent: 17 November 2000 09:05
> To: Doxygen Mailing List
> Subject: Structuring documentation
> 
> 
> Hi all,
> 
> How can I define the structure of the documentation with Doxygen?
> 
> So far I've only managed to produce individual pages and link 
> them \refs. This is fine for HTML but not for more book-like 
> output formats (like for example RTF). So what I'm seeking 
> for is a way to write hierarchical (Chapter 1, Chapter 1.1, 
> ...) manual (with class documentation and individual pages 
> 'inserted' to it). But I just can't find a way how to define 
> relative order of pages and the documentation structure in general.
> 
> Hope this example clarifies a bit:
> 
> SDK Documentation
>     +- What's New
>     |   |- Legal Information
>     |   |- Release Notes
>     |   \- About SDK
>     |
>     +- Used Conventions
>     +- Reference Manual
>     |   +- About Reference Manual
>     |   +- Class Reference
>     |        +- Class A
>     |        +- Class B
>     +- ...
> 
> Hope somebody can help. I haven't used Doxygen that much yet, 
> but I've liked many features so far (for example convenient 
> \ref, \b, \c etc. tags are really nice). I do have used a lot 
> of documentation generators before though, Doc++, CCDoc, 
> JavaDoc, Object Outline, ...
> 
> 
> Regards,
> Jani Kajala

Re: [Doxygen-users] Re: files order

[Roberto B. <ba...@cs...>]

Stephen Goudge wrote:
> looking through some archived messages, I thought this was worth re-posting:
> 
> > -----Original Message-----
> > From: Jani Kajala [mailto:jan...@re...]
> > Sent: 17 November 2000 09:05
> > To: Doxygen Mailing List
> > Subject: Structuring documentation
> >
> > Hope this example clarifies a bit:
> >
> > SDK Documentation
> >     +- What's New
> >     |   |- Legal Information
> >     |   |- Release Notes
> >     |   \- About SDK
> >     |
> >     +- Used Conventions
> >     +- Reference Manual
> >     |   +- About Reference Manual
> >     |   +- Class Reference
> >     |        +- Class A
> >     |        +- Class B
> >     +- ...

That is precisely what we want to do.
Anyone has a clue about how this could be achieved easily?
All the best,

    Roberto

-- 
Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:ba...@cs...