How to get man page output for the main page?

Question

Doxygen lets you produce man page output, but as far as I can tell it only generates man pages for the actual code (functions, classes, etc). I have a great deal of information, such as examples, in a doxygen @mainpage comment that is not showing up anywhere in the man page output. I'd like to have it in that format so that I'll also have a man page that serves as an overall introduction. Is there a way of doing this with doxygen?

So far I have not found a way and the alternatives that I've explored don't work very well with the index.html file that doxygen creates for me. For example, I tried several different html2man scripts on the index.html file without success.

Answer 1

I came up with this work-around, which puts the pseudo-mainpage text in the man page, and puts a nice link to it from the HTML mainpage:

/**
 * @mainpage
 * Summary of my simple project.  Please see @ref foo.h for more details.
 *
 * @file foo.h
 * @brief Summary of my simple project.
 * 
 * Here is the much more detailed description of my project,
 * originally intended for the main page.  Since I value the quality
 * of man page output the most, this will end up on the individual
 * file man page, and will be linked to from the HTML main page.
 * I can rattle on with other things like...
 * @todo find a better solution to the mainpage problem.
 */

Answer 2

As far as I can tell, this is not possible. HTML output covers the entire project, whereas man page output covers a single @file. The @mainpage applies to an entire project, not any particular @file. Therefore doxygen doesn't output the @mainpage for man output.

I downloaded the source, and browsed src/layout.cpp. Search (for example) for BriefDesc, and you will see how each "layout handler" is put together. I don't yet understand what @mainpage maps to, but clearly it's not something that's added in the "file layout handlers" section.

I tried adding @mainpage or @page, and using @ref to reference it, to see if I could create 2 man pages and manually tie them together and yet still have a nice HTML front page. For example, I tried to get 2 man pages, foo and foo-intro. To do this, I needed @page. But for HTML output, the intro shows up under "Related Pages", not "Main Page". And yet @mainpage can't seem to trigger a separate man page. Not ideal.

Answer 3

Have you included a @file <filename> comment in the file that holds the @main documentation and does <filename> definitely match the actual file name?

Doxygen will not include documentation from a file that does not have at least this.`

http://www.doxygen.nl/manual/commands.html#cmdfile