My controversial topic for today is libalpm.3 and Doxygen (FS#9237). It is time to completely throw out the idea of generating that page. Who is going to 'man libalpm' and what would they hope to see? The API reference Doxygen produces is useful when it lets you click your way quickly to an answer: lots of narrowly focused pages with lots of links. But if you wanted that would you 'man libalpm'? No. Maybe some user guide stuff? But then Doxygen is not the right tool. A couple of hits might come from people poking around /usr/lib and wondering "WTF is this thing?". That would be rare (I hope), and yet still Doxygen is not the right tool to answer that question. So I just can't figure out a scenario starting with "I want help making a front end to libalpm" that leads to a Doxygen generated libalpm.3. But Doxygen is still useful. It just needs a new purpose. Or at least to be freed from the constraints of its current perceived purpose. Here's what this patch set proposes: Doxygen remains hidden behind a configure --enable (so most people will never notice) but patch 1 completely changes what that --enable does: forget libalpm.3, Doxygen now sees all the pacman code and produces modern HTML. Some of the markup that patch 1 added to Doxygen's INPUT was not current, so patches 2&3 fix those issues. And patch 4 deletes libalpm.3.txt, resolving FS#9237 in the most brutal way possible. See: not controversial at all. :) Happy solstice, everyone! Jeremy Heiner (4): Remove DOXYGEN_MANS. New Doxyfile.in. Add 'make doxygen-*'. Clean up doxygen markup for the libalpm groups. Clean up doxygen @param warnings. Remove all references to libalpm.3 configure.ac | 26 +++- doc/.gitignore | 3 +- doc/Doxyfile | 305 ----------------------------------------------- doc/Doxyfile.in | 43 +++++++ doc/Makefile.am | 36 +++--- doc/index.txt | 1 - doc/libalpm.3.txt | 39 ------ doc/pacman.8.txt | 4 +- doc/pacman.conf.5.txt | 4 +- doc/vercmp.8.txt | 2 +- lib/libalpm/alpm.c | 11 -- lib/libalpm/alpm.h | 34 +++--- lib/libalpm/alpm_list.c | 7 +- lib/libalpm/alpm_list.h | 36 +++++- lib/libalpm/be_local.c | 2 +- lib/libalpm/be_package.c | 3 +- lib/libalpm/be_sync.c | 1 - lib/libalpm/db.c | 6 +- lib/libalpm/delta.c | 7 -- lib/libalpm/deps.c | 4 +- lib/libalpm/dload.c | 3 +- lib/libalpm/log.c | 5 +- lib/libalpm/package.c | 5 +- lib/libalpm/signing.c | 3 + lib/libalpm/sync.c | 2 +- lib/libalpm/trans.c | 5 +- lib/libalpm/util.c | 7 +- src/pacman/conf.c | 1 - src/pacman/package.c | 4 +- src/pacman/util.c | 1 - 30 files changed, 162 insertions(+), 448 deletions(-) delete mode 100644 doc/Doxyfile create mode 100644 doc/Doxyfile.in delete mode 100644 doc/libalpm.3.txt -- 1.8.5.2