[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
>