Doxygen currently uses the PROJECT_NAME for many different things, inserting it in all kinds of places. Unfortunately, this makes it slightly difficult to adjust the look & feel of the Doxygen output in certain cases.

In this particular case, we would like to change the title of our Doxygen pages from the form
  PROJECT_NAME: ACTUAL PAGE TITLE
to some other form including our project name and the page title. To give a concrete example, we would like to to replace
  ScummVM: ADParams Struct Reference
by
  ScummVM :: Doxygen :: ADParams Struct Reference
in order to match the HTML titles of some of our other sites.

Unfortunately, if PROJECT_NAME is set, then Doxygen's HtmlGenerator::startFile currently always adds a "PROJECT_NAME: " prefix to the page title (the "dispTitle" variable) before passing it to substituteKeywords. This makes it impossible for us to perform this customization.

Well, that is, of course we could try to run a perl / sed script as post-processor, but that seems like a very ugly hack for something that looks to me like an historically grown misfeature in Doxygen ;-), no offense intended (I love Doxygen :).

Now I realize that just changing this might be quite bad for existing templates. So, one shouldn't just change this lightly. I wouldn't dare to be the one to make the call on this, anyway :)

I propose two possible solutions for this (and am willing to get my hands dirty and try to provide a patch, if you tell me which you prefer):

1) Ignore backwards compatibility and just don't prepend PROJECT_NAME to the display title. After all, it's available via the $projectname substitution variable, so it's easy to adapt templates by changing  "$title" to  "$projectname: $title". Still, this would force lots of people to adjust their template.

2) Stay backward compatible and don't touch $title. Instead, introduce a new variable, say, $plain_title, which contains only the actual title. This way new templates can perform customizations like the one we desire.


Maybe you also have other & better ideas, these are just two suggestions from the top of my head, and of course I don't know the Doxygen source code very well.


BTW, some people suggested to me that I should just use an empty PROJECT_NAME (which would solve the issue above as in that case Doxygen doesn't prepend anything), but IMHO that would be a rather bad hack, and also would break other things that normally insert the project name; like the HTML navigation tree view thingy, which uses the project name as root for the navigation tree. Plus it's not a viable solution for other projects which want to share a single template for multiple (sub)projects.

By the way, there are more places where the indiscriminate use of PROJECT_NAME for all and everything bites us. E.g. FTVHelp::generateTreeView in ftvhelp.cpp insists on using PROJECT_NAME for the <title> page of the master index.html it generates, without any option to override this. Hence we currently run a brief perl script over this to change "<title>ScummVM</title>" to the title we really want. Since this is only a single small file, I can live with that. Although it certainly would be nice to be able to change this "cleanly" :).