Problems, old & new

Table of Contents

• Doxygen superscript problem solved
• Doygen TREEVIEW resists re-sizing
• Related Pages excludes days in current month
• Interesting web pages

Wednesday 5^th July, 2017

Doxygen superscript problem solved

Until now I've had a choice of either using superscripts in date headers or using a page-level table of contents. The two features were mutually exclusive. I'd implemented date superscripts via the HTML "^..." mechanism. This works fine, with table of Contents disabled. To use both together I had to paste the UTF-8 characters into the page. Entities didn't work. The final result isn't perfect, but it's a good-enough compromise.

I used Tiny Text Generator to create the superscript text.

Doygen TREEVIEW resists re-sizing

I like Doxygen's tree-view, but it's far too wide. By default it's 250 pixels. The documentation claims this is adjustable in configuration:

TREEVIEW_WIDTH

If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used to set the initial width (in pixels) of the frame in which the tree is shown.

Minimum value: 0, maximum value: 1500, default value: 250.

That doesn't work, for me. I changed the value to 150, with no effect. To be revisited.

Related Pages excludes days in current month

I have a Doxygen web site with two top-level pages: 2017-06 and 2017-07. Daily sub-pages are beneath each top-level page. I'd expect to see all pages listed on Related Pages. But I only see June's pages, not July's.

The clue is in the page name "related pages". In this case the main page is 2017-07. So that page, and all its sub-pages, are excluded from the related page.

I needed a quick work-around, that didn't involve major re-writes, broken links and structural changes. My first attempt was to:

1. Move the About Me page contents into an include file, that's on the EXAMPLE_PATH.
2. About Me page now included the new file, via @includedoc.
3. Changed the old main page 2017-07 to be a normal page.
4. Make the existing month pages sub-pages of the new mainpage
5. Create a new mainpage.md that includes the same file as About Me.

Like this:

• MainPage.md

  @mainpage Developer's Diary
  @subpage 2017-07
  @subpage 2017-06
  @includedoc AboutMe_Include.md

• AboutMe.md

  # About Me {#AboutMe}
  @includedoc AboutMe_Include.md

This broke a couple of links on the included about page. These were reference links to pages that aren't yet on the site. Using broken reference links from a non-included page causes a warning and the link is converted into plain text. e.g. [example](@ref example) is rendered as the plain text "example", with the URL removed. But if that same markdown link is in an include file, it's rendered as is, i.e. this is displayed in the browser: [example](@ref example). @includedoc is supposed to honour the included markdown... with some restrictions, and they're not all documented.

From the documentation:

\includedoc <file-name> This command works the same way as \include, but it will include the content of the file as if it were at the place where this command is called. The result is that the content is parsed by doxygen and placed in the documentation.

Note

Some commands like \cond and \if don't work with this command due to the moment of parsing.

The included documentation should not have comment signs in it as the will appear in the documentation as well.

So \includedoc is like the parson's egg: good, in parts.

At this point the includedoc feature could cost me more time than it saves.

I'll revisit this possibly with a pre-build step to assemble the files.

Maybe something similar to this pseudo code:

includeInFile.each { mdFileToCreate ->
    ant.with {
        concat destfile: "${input}/${mdFileToCreate}" {
            header  file: headerFile
            fileset file: includeFile
            footer  file: footerFile
        }
    }
}

Interesting web pages

• Tiny Text Generator – LingoJam, 2017
• Ant Concat Task – Ant Manual, Apache Software Foundation.

---

4^th July 👈 Top of page 👉 6^th July © 2017 Terry Ebdon.

Find me coding on GitHub, networking on LinkedIn, answering questions on Stack Exchange and hanging out on twitter.