Ordering the header files in the library's doxygen reference
I use quickbook and doxygen to create the doc for my library. In my jamfile for building the docs I have the header files in my doxygen reference listed in the particular order I would like to see them in the reference when the documentation is built. But for some reason I cannot discern the order of the header files in the reference section of my final HTML documentation is not the same as the order in which I have the header files listed. Does anybody know how I can control the order of the header files listed in the reference section of my library's HTML documentation ?
On 4/13/2016 2:49 PM, Vinnie Falco wrote:
I use quickbook and doxygen to create the doc for my library.
I'm also using quickbook and doxygen, if your library is public would you mind providing a link for perusal? Thanks.
It's the Boost VMD library. It's git repository is at https://github.com/boostorg/vmd.git. If you look at its doc jamfile you can see the order of the header files I want in the reference in the 'doxygen vmd_reference' part of the jamfile. But this is not the order that shows up in the reference when I build the doc or when Boost builds the doc as part of the Boost distribution.
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 13 April 2016 19:41 To: boost@lists.boost.org Subject: [boost] Ordering the header files in the library's doxygen reference
I use quickbook and doxygen to create the doc for my library. In my jamfile for building the docs I have the header files in my doxygen reference listed in the particular order I would like to see them in the reference when the documentation is built. But for some reason I cannot discern the order of the header files in the reference section of my final HTML documentation is not the same as the order in which I have the header files listed.
Does anybody know how I can control the order of the header files listed in the reference section of my library's HTML documentation ?
I am unable to answer your question, but it is helpful to point out that 1 Using Quickbook code links to the header, functions, classes, member... you can make the order less important. 2 using Quickbook links you can lead the reader direct to the header under consideration. 3 Using Autoindex, you can make the order alphabetical, often what the user most wants (once he knows its name of course). But perhaps you know that and are still unsatisfied. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 4/21/2016 10:08 AM, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 13 April 2016 19:41 To: boost@lists.boost.org Subject: [boost] Ordering the header files in the library's doxygen reference
I use quickbook and doxygen to create the doc for my library. In my jamfile for building the docs I have the header files in my doxygen reference listed in the particular order I would like to see them in the reference when the documentation is built. But for some reason I cannot discern the order of the header files in the reference section of my final HTML documentation is not the same as the order in which I have the header files listed.
Does anybody know how I can control the order of the header files listed in the reference section of my library's HTML documentation ?
I am unable to answer your question, but it is helpful to point out that
1 Using Quickbook code links to the header, functions, classes, member... you can make the order less important.
2 using Quickbook links you can lead the reader direct to the header under consideration.
3 Using Autoindex, you can make the order alphabetical, often what the user most wants (once he knows its name of course).
But perhaps you know that and are still unsatisfied.
It's the order of the header files which shows in the reference section to the VMD library documentation which concerns me. The order is garbled from what I specify in my jamfile, which makes it much harder for an end-user to look in the reference section to find a VMD macro. This is occuring despite the fact that I specify the order which I want the header files to be listed in the reference section of the jamfile. I do realize that I am probably negligent in providing all the necessary links in the actual Quickbook documentation which I should do to the reference file documentation. Still I think that when looking in the reference section directly the end-user should be presented with an alphabetical order of files which makes it easy to find something in particular. I don't see the problem I am encountering with doxygen source file order in documentation for my tti library. I think it must have to do with doxygen being told that some of its input files are in sub-directories of a location where other input files are located.
On 2016-04-21 21:17, Edward Diener wrote:
It's the order of the header files which shows in the reference section to the VMD library documentation which concerns me. The order is garbled from what I specify in my jamfile, which makes it much harder for an end-user to look in the reference section to find a VMD macro. This is occuring despite the fact that I specify the order which I want the header files to be listed in the reference section of the jamfile.
The Docbook XML document is generated by Doxygen and, I assume, the order in which the headers are listed in the document is determined by Doxygen and not the Jamfile. In Boost.Log docs I have the ALPHABETICAL_INDEX=YES Doxygen parameter, and in the generated docs the headers are listed alphabetically (within each Reference sub-section). Maybe that's what you're missing?
On 4/21/2016 3:35 PM, Andrey Semashev wrote:
On 2016-04-21 21:17, Edward Diener wrote:
It's the order of the header files which shows in the reference section to the VMD library documentation which concerns me. The order is garbled from what I specify in my jamfile, which makes it much harder for an end-user to look in the reference section to find a VMD macro. This is occuring despite the fact that I specify the order which I want the header files to be listed in the reference section of the jamfile.
The Docbook XML document is generated by Doxygen and, I assume, the order in which the headers are listed in the document is determined by Doxygen and not the Jamfile.
I would assume so also. But I would also assume for the Boost.Build doxygen rule that the order of the 'sources' matches the order of INPUT files in the doxygen configuration file, else how else is the doxygen output being generated without an internal doxygen configuration. I also can see in the output from quickbook that doxygen is parsing the files in the exact order I give of the 'sources' to the doxygen rule. But I can also see in the output from quickbook that doxygen is generating docs for the files in the order that shows up in the final documentation and that the order of generating files is very different from the order it is parsing the files. You can see all this if you just look at the VMD library's doc jamfile and try generating the doc for it yourself. I asked both on the doxygen user's mailing list and on stackoverflow why the order specified for the INPUT files does not match the order of files for which the docs are generated and which appear in the reference section, but there has been no answer to this. My guess is that the doxygen programmer knows why, or perhaps it is a bug in some situation I am encountering, but he is not telling if he knows. I notice quite a few questions on the doxygen users mailing list never get answered.
In Boost.Log docs I have the ALPHABETICAL_INDEX=YES Doxygen parameter, and in the generated docs the headers are listed alphabetically (within each Reference sub-section). Maybe that's what you're missing?
I tried it but it made no difference in the order of the generated files. I did not think it would work, according to the documentation for ALPHABETICAL_INDEX in the dosygen documentation file, and it did not. Thanks anyway !
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 21 April 2016 22:39 To: boost@lists.boost.org Subject: Re: [boost] Ordering the header files in the library's doxygen reference
On 4/21/2016 3:35 PM, Andrey Semashev wrote:
On 2016-04-21 21:17, Edward Diener wrote:
It's the order of the header files which shows in the reference section to the VMD library documentation which concerns me. The order is garbled from what I specify in my jamfile, which makes it much harder for an end-user to look in the reference section to find a VMD macro. This is occuring despite the fact that I specify the order which I want the header files to be listed in the reference section of the jamfile.
The Docbook XML document is generated by Doxygen and, I assume, the order in which the headers are listed in the document is determined by Doxygen and not the Jamfile.
I would assume so also. But I would also assume for the Boost.Build doxygen rule that the order of the 'sources' matches the order of INPUT files in the doxygen configuration file, else how else is the doxygen output being generated without an internal doxygen configuration. I also can see in the output from quickbook that doxygen is parsing the files in the exact order I give of the 'sources' to the doxygen rule. But I can also see in the output from quickbook that doxygen is generating docs for the files in the order that shows up in the final documentation and that the order of generating files is very different from the order it is parsing the files. You can see all this if you just look at the VMD library's doc jamfile and try generating the doc for it yourself.
I asked both on the doxygen user's mailing list and on stackoverflow why the order specified for the INPUT files does not match the order of files for which the docs are generated and which appear in the reference section, but there has been no answer to this. My guess is that the doxygen programmer knows why, or perhaps it is a bug in some situation I am encountering, but he is not telling if he knows. I notice quite a few questions on the doxygen users mailing list never get answered.
In Boost.Log docs I have the ALPHABETICAL_INDEX=YES Doxygen parameter, and in the generated docs the headers are listed alphabetically (within each Reference sub-section). Maybe that's what you're missing?
I tried it but it made no difference in the order of the generated files. I did not think it would work, according to the documentation for ALPHABETICAL_INDEX in the dosygen documentation file, and it did not. Thanks anyway !
Would it help diagnosing the problem to generate Standalone Doxygen and see if the order is what you want there? Or could it work if you use a wild card to select all the files in one jamfile item like [ glob ../../../boost/your_lib/*.hpp ] Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 4/22/2016 8:11 AM, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 21 April 2016 22:39 To: boost@lists.boost.org Subject: Re: [boost] Ordering the header files in the library's doxygen reference
On 4/21/2016 3:35 PM, Andrey Semashev wrote:
On 2016-04-21 21:17, Edward Diener wrote:
It's the order of the header files which shows in the reference section to the VMD library documentation which concerns me. The order is garbled from what I specify in my jamfile, which makes it much harder for an end-user to look in the reference section to find a VMD macro. This is occuring despite the fact that I specify the order which I want the header files to be listed in the reference section of the jamfile.
The Docbook XML document is generated by Doxygen and, I assume, the order in which the headers are listed in the document is determined by Doxygen and not the Jamfile.
I would assume so also. But I would also assume for the Boost.Build doxygen rule that the order of the 'sources' matches the order of INPUT files in the doxygen configuration file, else how else is the doxygen output being generated without an internal doxygen configuration. I also can see in the output from quickbook that doxygen is parsing the files in the exact order I give of the 'sources' to the doxygen rule. But I can also see in the output from quickbook that doxygen is generating docs for the files in the order that shows up in the final documentation and that the order of generating files is very different from the order it is parsing the files. You can see all this if you just look at the VMD library's doc jamfile and try generating the doc for it yourself.
I asked both on the doxygen user's mailing list and on stackoverflow why the order specified for the INPUT files does not match the order of files for which the docs are generated and which appear in the reference section, but there has been no answer to this. My guess is that the doxygen programmer knows why, or perhaps it is a bug in some situation I am encountering, but he is not telling if he knows. I notice quite a few questions on the doxygen users mailing list never get answered.
In Boost.Log docs I have the ALPHABETICAL_INDEX=YES Doxygen parameter, and in the generated docs the headers are listed alphabetically (within each Reference sub-section). Maybe that's what you're missing?
I tried it but it made no difference in the order of the generated files. I did not think it would work, according to the documentation for ALPHABETICAL_INDEX in the dosygen documentation file, and it did not. Thanks anyway !
Would it help diagnosing the problem to generate Standalone Doxygen and see if the order is what you want there?
I tried doing standalone doxygen and the order of header files for which it was generating docs is again different from the order of header files in which parses for its information. The latter matches the order I specify for the doxygen INPUT configuration. Therefore it is essentially processing the files exactly the same whether I use the Boost build jamfile or standalone doxygen. Where things are different is in the final documentation. In the Boost build generated final documentation the reference is a flat list of header files in the generated docs order. In the standalone doxygen final documentation the header files are presented in a tree-like structure off of the include directory so there is no sense of the generated docs order being out of order from how I want an end-user to view them. That is probably why no one using doxygen cares about the generated order being different from the INPUT order. In Boost build the output from doxygen goes into an .xml file which is further processed to produce the reference section. In doxygen standalone the output I generate is HTML using doxygen's own format for generating the HTML output. I could of course tell doxygen standalone to generate xml, but I am sure it will be the same xml file as Boost build generates and then processes in its own way.
Or could it work if you use a wild card to select all the files in one jamfile item like
[ glob ../../../boost/your_lib/*.hpp ]
How can that ever be the right way to get the alphabetical order I want ? After all its the fact that I am purposely specifying the order of INPUT headers I want by listing each file in the doxygen rule in Boost build which should, at least theoretically produce the correct order. using a glob can only make specifying the order more random.
participants (4)
-
Andrey Semashev -
Edward Diener -
Paul A. Bristow -
Vinnie Falco