Re: [Boost-build] Doxygen rule change ?

Subject: Re: [Boost-build] Doxygen rule change ?
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-04-26 14:40:35

On 4/26/2016 11:44 AM, Steven Watanabe wrote:
> AMDG
>
> On 04/26/2016 09:23 AM, Edward Diener wrote:
>> On 4/26/2016 8:09 AM, PJB wrote:
>>> Wouldn't this be something better implemented by a post-build script,
>>> rather than boost-build?
>>
>> No, because the doxygen rule is part of a larger Boost Build process
>> which builds boostbook output as HTML and/or PDF files.
>>
>
>   If we need any post-processing, the right place to
> handle it is boostbook/xsl/doxygen/doxygen2boostbook.xsl.
> Of course, it would be much better if there were
> some way to convince doxygen to preserve the input
> order.  I'm assuming that this is in fact a problem
> in doxygen, not Boost.Build, since Boost.Build always
> sorts things alphabetically when it adjusts the order.
>

I have also sent two posts to the doxygen mailing list in order to be 
more specific about the problem. So far no answers. Similarly a 
stackoverflow problem I created has received no answers. If the doxygen 
programmers do not want to answer it probably is because they see no 
problem generating file docs in a different order than the input order.

Most of the time it does appear to preserve the input order but when it 
does not do so I have little idea why that happens. I am guessing it has 
something to do with input files in different directories. Of course it 
is unreasonable to expect a library developer to change the placement of 
his files just to accomodate doxygen.

I agree that most of the time changing xml should be done with xsl. But 
perhaps when it comes to moving around the different file information in 
the xml, since the file information is probably top-level in the 
hierarchy, it wouldn't just be easier reading in the entire xml and then 
writing it back out in a corrected order.

I don't know what you mean when you say that Boost Build sorts things 
alphabetically. It seems to me that the the doxygen generated reference, 
which shows in the HTML documentation for a library using the 
quickbook-doxygen-boostbook toolsets, always show the files in the order 
in which doxygen generates the files information and writes the output 
to xml. They are definitely not transformed into any sort of 
alphabetical order as far as the actual file paths are concerned. Try 
creating the VMD doc and you will see that.

>>>
>>> On 26 April 2016 at 12:54, Edward Diener <eldiener_at_[hidden]
>>> <mailto:eldiener_at_[hidden]>> wrote:
>>>
>>>     It turns out that there is no guarantee when using doxygen that the
>>>     order of the files generated in the XML doc is the same as the order
>>>     of the sources which an end-user specifies for doxygen to scan.
>>>     Although it often works out that the two orders are the same, it is
>>>     possible they are not. The VMD documentation shows an instance where
>>>     they are not the same, nor have I found out from doxygen anything
>>>     about why the orders might be different.
>>>
>>>     <snip>
>>>
>>>     Can something be done in Boost Build to change the xml file
>>>     generated by doxygen so that the file entries are either in the
>>>     order specified as input sources or in some sort of alphabetic order
>>>     ? <snip>