Inquiry: Does DoxyPress correctly support nested ouptut in the PDF output?

[eddyp]

Doxygen has aproblem with generating nested chapter/subchapter structure for the PDF output, making the @ingroup functionality have a very limited use for PDF output (HTML is OK).

This is a long standing issue of Doxygen: https://stackoverflow.com/questions/21037598/latex-output-generated-using-doxygen-does-not-support-nested-groups-defgroup-wi/59955116

Does DoxyPress fix this issue?

(Note: I tried generating the same document in DoxyPress as I am with Doxygen to no avail; I am still to create a minimal example test case without IP issues.)

[bgeller]

Please send us a test case and we will take a look at it. Thanks for letting us know about this issue.

[bgeller]

Just following up to see if you were able to reproduce this issue with the current version of DoxyPress. A small sample would be great.

[eddyp]

Hello, I have been postponing on getting a sample as the code is some proprietary C code, and I implemented some workarounds on top of Doxygen's LaTeX output for PDF generation with some custom styles.

When I initially tried the exact same config I had working with Doxygen, Doxypress simply failed to generate any content, so I got stuck into that problem.

Is there any C test sample that you already have that generates a PDF? Maybe the route in that direction is easier to reproduce.

I'll try to assemble some test sample by stripping away from the doxygen setup next week as there are 2 non-working days. If I can't squeeze it in next week, I'll be able to get back to this only around Christmas.

Please ping me if you have any questions regarding the details of the config, if you decide to try to test/create some sample input.

[eddyp]

I think I actually managed to do it from scratch:

HTML is nice and nested:

While PDF is flat:

The project sample is this:

doxypress-doc-gen.zip

[agserm]

We are currently reworking latex, thanks for letting us know there were issues with the PDF generation. We will take a look at this as part of making other improvements.

[agserm]

We did some further investigation and noticed you had the "LaTeX Hide Indices" tag enabled. This disables the page called "Module Index" which is where these groups are displayed with indentation corresponding to their hierarchy. The screen shot you provided above shows the main index of the LaTeX output, which is a flat and linear list of all the items in the document regardless of hierarchy.

You may want to disable this tag so you can see the indentation present on the module index. Let us know what you think.

[eddyp]

We did some further investigation and noticed you had the "LaTeX Hide Indices" tag enabled. This disables the page called "Module Index" which is where these groups are displayed with indentation corresponding to their hierarchy. The screen shot you provided above shows the main index of the LaTeX output, which is a flat and linear list of all the items in the document regardless of hierarchy.

You may want to disable this tag so you can see the indentation present on the module index. Let us know what you think.

The reason I disabled that was because it generates a File Index, which is something we decided against in my work project as it leads to confusing output.

Even with that disabled, I still see no relevant change as the groups are not indented into each other.

[agserm]

We are in the process of updating DoxyPress and focusing quite heavily on both HTML and Latex.

Since you turned off the indexes you will not see the output in a hierarchy. Can you let us know exactly which page you think should have a hierarchical layout? In your screen shot above, it looks like the module index would have been on Page 1, but you are displaying Page 3.

[eddyp]

Since you turned off the indexes you will not see the output in a hierarchy.

Hello, I am confused.

You initially said because I had "LaTeX Hide Indices" enabled I should not expect any hierarchical arrangement of "The Third Group", "The Fourth Group" and "The Fifth Group" with Fifth inside Fourth inside Third, as is visible in the HTML output.

In the last attempt I disabled that option to check if the hierarchical group placement is done in the PDF.

Now are you saying that I have to enable it back?

Can you let us know exactly which page you think should have a hierarchical layout? In your screen shot above, it looks like the module index would have been on Page 1, but you are displaying Page 3.

I was hoping the the Module Documentation chapter would have a layout like:

• The Third Group
  • The Fourth Group
    • The Fifth Group

As I said before, we find the Module and File Index chapters confusing and not at all helping as they are leading to a lot of repetitive output.

Long story short, this structure would be the desired layout (ignore the chapter numbering start from 3, I just moved things around to help making the point):

For short, we'd want the module documentation to actually reflect the fact Fifth is inside Fourth which is inside Third from within the module documentation chapter, not by some other extra chapter which is presenting repetitive info.

[agserm]

There are two places the index appears. One is controlled by the "LaTeX Hide Indices" tag, and the other is always present as part of the automatically generated table of contents.

The sidebar you show in your last post is being generated based on the structure of the document. Each module is placed in its own section, at the same level at every other module. As much as we would like to, this is not something we can change since LaTeX does not support deeply nested sections.

[eddyp]

As much as we would like to, this is not something we can change since LaTeX does not support deeply nested sections.

I'm confused by this. Are you saying vanilla LaTeX does not support nested sections and you don't want to add some custom extensions so it does? I'm multiply confused by this as there exist in the output and the syle template the following types allowing nesting:

• \chapter
• \doxysection
• '\doxysubsection
• \doxysubsubsection

See here: https://github.com/doxygen/doxygen/blob/master/templates/latex/doxygen.sty#L550

Also in our template we have definitions for corresponding \section, \subsection. \subsubsection title formatting.

I'm asking because until now with Doxygen generated .tex files, in order to obtain the desired effect, we have a post-processing step where we clean up the resulting .tex to get the right results.

What we do is basically:

# 1. open refman.tex
# 2. pass on for fixing and getting classes and subgroups
# 3. open each 'class'.tex and "pull it up" one level to be a chapter;
#    instead of list items, \input the subgroups' pages
# 3.0. replace '\doxysection' with '\chapter'
# 3.1. remove '\doxysubsection*{Modules}' and list formatting items
# 3.2. identify <subgroup>s: \mbox{\hyperlink{(group[^}]*)}{[^}]*}}
# 3.3. replace "\mbox ... {<subgroup>} ..." with "\input{<subgroup>}"

"Classes" are some arbitrary groups we defined so we workaround the fact \ingroup/@ingroup does not generate the proper .tex output and to workaround the issue. These "classes" are defined ad used like this:

classes.dox:
/** @defgroup class_admin_services Administration Services
 *
 * Services to install, configure and test the system
 */

/** @defgroup class_common_types Common Types and Definitions */

Then used like this:

basic_common_types.h:

/**
 *   @file    basic_common_types.h
 *
 *   @brief   Basic types used by all components 
 *   @details This file contains the basic types used by all components
 *
 *   @addtogroup basic_common_types Basic Common Types
 *   @ingroup class_common_types
 *   @{
 */

config_types.h:

/**
 *   @file    config_types.h
 *
 *   @brief   Configuration dependent types
 *   @details This file contains configuration dependent type definitions
 *
 *   @addtogroup config_types Types whose size and definition depends on the configuration
 *   @ingroup class_common_types
 *   @{
 */

And the expectation is that basic_common_types and config_types are in inside class_common_types on a lower level.

[agserm]

Thanks for your patience while we were in release mode for CopperSpice and DoxyPress.

I believe your fundamental question is about the structure of our latex output. By definition, latex does not support nesting sections more than four levels deep. This means the structure of the document cannot be based on the inheritance hierarchy of your code because there would be no way to represent a great grand child class. We agree that four levels is a small number, but our output must adhere to the latex rules.

There is another reason the output cannot be based on the class hierarchy. There is no way in a tree structure to represent multiple inheritance.

As you have observed, you have the ability to postprocess the DoxyPress output for any project specific customization you want to make. It would not make sense to alter our latex output for specific use cases as this would produce invalid latex in the general case.

If there is something you are having issues with in postprocessing, please let us know and maybe we can help you streamline the process.

[agserm]

According to the latex documentation, what you are looking for is outside the scope of what is provided in the language. If you wish to modify your output, postprocessing is the correct way to handle project specific changes you feel are necessary.

Please open a new ticket if there is something else you believe we can address. We are happy to improve other areas of latex which conform to the supported syntax.

[eddyp]

I understand your points and partly agree with them.

The part I see as addressable:

1. mapping ingroup usage to document "subchaptering" wouldn't be unreasonable since that is a manual organization and people don't typically use so many levels in documentation
2. C language doesn't have classes anyway, but I guess for uniformity it wouldn't make sense to handle C differently than C++ or other languages, still, giving a warning if the ingroup leveling is at limit and error if is above would be acceptable for the vast majority of cases.

Does this make sense from your PoV?