XML output for dot file uses relative path in 1.9.3

[2bndy5]

Describe the bug
A recent change in v1.9.3 causes the dot file to be copied to the XML output folder. The dot file's path in XML now uses a relative path, where it used to be an absolute path.

This path change is breaking breathe's ability (the sphinx extension) to find the dot file and in turn pass it to the dot tool.

Expected behavior
Please switch back to using an absolute path. I don't care if it points to the copied dot file in the XML folder or the originally specified dot file.

To Reproduce
dot_graphs.zip

Version
1.9.3 (c0b9eaf)

• Ubuntu 64-bit. Installed from archived binary distribution on SourceForge

  Distributor ID:	Ubuntu
  Description:	Ubuntu 21.10
  Release:	21.10
  Codename:	impish
  

• Windows 64-bit. Installed from doxygen website (https://www.doxygen.nl/download.html)

Additional context
I'm currently looking to workaround this problem in the sphinx extension, breathe - paths used for sphinx vs paths used for doxygen might be impossible to resolve effectively. Since this is a version change specific to doxygen, I figured I'd raise the issue here.

[albert-github]

In principle it is very bad to use absolute paths as when moving / copying files the absolute path reference might get lost.
The previous implementation in doxygen was for this reason not the best choice and in the 1.9.3. version this has been corrected (see pull request #8852).

Furthermore the original file might not be present anymore or might have changed between the time of the doxygen run en the post processing. By copying the file to the XML directory the situation as defined during the the doxygen run is saved.

I think the problem is in breathe, breathe should support relative paths and absolute paths.

[2bndy5]

Thanx for clarifying the behavior. I wasn't sure if the change to relative paths was intended.

One last question:
Is the relative path relative to the XML file that names the dot file?
Or is it relative to the path designated as the XML_OUTPUT?

Given your response, I assume it is relative to the XML file (not the XML_OUTPUT). I want to be sure in case doxygen decides to offer the ability to use sub-directories in the XML output path (maybe it does already & I'm unaware).

[albert-github]

Good question:

Is the relative path relative to the XML file that names the dot file?
Or is it relative to the path designated as the XML_OUTPUT?

especially in relation to the CREATE_SUBDIR=YES situation.

• with CREATE_SUBDIR=NO

   dot_graphs_1_9_3/xml/dotgraphs.xml:<para><dotfile name="dotfile.dot">Captions go here</dotfile>
  

• with CREATE_SUBDIR=YES

   dot_graphs_1_9_3_subdir/xml/df/df6/dotgraphs.xml:<para><dotfile name="dotfile.dot">Captions go here</dotfile>
  

so this is relative to XML_OUTPUT (like it is also for the HTML_OUTPUT etc.).

[albert-github]

I was just thinking that the position of the "dotfile" should actually be documented, though where?

Some thoughts:
The most logical places are:

• in the compound.xsd in the XML_OUTPUT directory
  In this file we see:

  ....
    <xsd:element name="heading" type="docHeadingType" />
    <xsd:element name="dotfile" type="docImageFileType" />
    <xsd:element name="mscfile" type="docImageFileType" />
  ...
  

  Here there are the following places that come to my mind
  • before the "dotfile" element like:

     <!-- the file will be located in the directory as specified by XML_OUTPUT  -->
     <xsd:element name="dotfile" type="docImageFileType" />
    

  • as an attribute like:

     <xsd:element name="dotfile" type="docImageFileType" documentation="the file will be located in the directory as specified by XML_OUTPUT"/>
    

  • after the "dotfile" element like:

     <xsd:element name="dotfile" type="docImageFileType" /> <!-- the file will be located in the directory as specified by XML_OUTPUT  -->
    

• in the doxygen manual:
  Sounds as the most logical place. This means that the source (description / definition of the xml file, i.e. xsd file) and the result (documentation) might be in separate files or that some special scripts are required to process the input (like is done already for the config.xml with the doxygen settings).
  Furthermore this will be quite a substantial amount of information for a limited number of people who also will, probably, need it only once.

My preference in this case would be to place it in the compound.xsd file as comment before the element and not placing the information in the doxygen manual.

@doxygen what do you think?

[2bndy5]

Well, I didn't mean to spark another discussion. @albert-github Thanks for the answer. I'll stay subscribed, but I won't close this myself. Please close this issue when you feel the documented location of the dotfile is resolved (or it could be a separate thread).

[albert-github]

In my comment #9171 (comment) I wrote some ideas by head, later on I was thinking there should be some more structured way and it looks like there is by means of xsd:annotation / xsd:documentation, see e.g. https://www.w3.org/TR/xmlschema-0/#CommVers (see for an initial overview: https://en.wikipedia.org/wiki/XML_Schema_(W3C))

So our construct would look like:

      <xsd:element name="dotfile" type="docImageFileType" >
        <xsd:annotation>
          <xsd:documentation>The file will be located in the directory as specified by XML_OUTPUT</xsd:documentation>
        </xsd:annotation>
      </xsd:element>

So I think my previous comment is a bit outdated and we should have a look at this standard possiblity.

[albert-github]

I've just pushed a proposed patch, pull request #9178, not with the element but with the definition of the type (docImageFileType).

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

It is possible that more places need some explanation, suggestions are welcome.

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.4.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).