From 3ba244b94500d6bde92582efb1ce205e163690bc Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Tue, 9 Jun 2015 10:49:30 +0200 Subject: [PATCH] include a manpage for doxy2man --- README.md | 4 +++ doxy2man.8.txt | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ main.pro | 3 ++ 3 files changed, 106 insertions(+) create mode 100644 doxy2man.8.txt diff --git a/README.md b/README.md index 14291f7..49a7f2f 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ Or: $ qmake-qt5 $ make +To build the manpage use: + + $ make doxy2man.8 + ## Usage Create a small Doxygen configuration file. To enable XML output use something like this: diff --git a/doxy2man.8.txt b/doxy2man.8.txt new file mode 100644 index 0000000..3ced392 --- /dev/null +++ b/doxy2man.8.txt @@ -0,0 +1,99 @@ +doxy2man(8) +=========== +:doctype: manpage +:man source: doxy2man + + +NAME +---- +doxy2man - Create man pages from doxygen XML output. + +SYNOPSIS +-------- +*doxy2man* ['OPTIONS'] + +DESCRIPTION +----------- +Doxygen is great for generating HTML based API documentation. But the man +page output mode of doxygen (`GENERATE_MAN = YES`) is not that awesome. Doxygen +generates for a header file a man page with all functions, enums etc. For each +structure it generates a man page listing all its (public) attributes. For C +based projects this is not very useful, because one usually expects things like one man +page for each function and referenced structs documented where used. + +Doxy2man takes the XML generated by Doxygen as input and creates several man +pages from that. It creates a summary man page for a header and for each function a detailed +man page. The output is optimized for C projects. It supports the most common +doxygen features, e.g. implicit and explicit see also tags, copyright, author +information, brief and detailed descriptions, etc. + +USAGE +----- +Create a small Doxygen configuration file. To enable XML output use something like this: + + GENERATE_XML = YES + XML_OUTPUT = xml + XML_PROGRAMLISTING = NO + +Call doxygen: + + $ doxygen + +The `xml` subdirectory should contain some XML files now. + +Call doxy2man: + + $ ./doxy2man xml/myheader_8h.xml + +View the man pages: + + $ ls out + ... + $ man -l out/my_header.h.3 + $ man -l out/my_func_a.3 + $ man -l out/my_func_b.3 + ... + + +OPTIONS +------- + +Doxy2man implements several useful defaults but is also customizable: + + $ ./doxy2man --help + Generates man pages from doxygen XML output + + call: ./doxy2man OPTIONS DOXYGEN_XML_HEADER_FILE + + where + + -h, --help this screen + --nowarn suppress warnings + --nosummary don't generate summare man page + --nocopyright don't generate copyright section + --nofollow don't parse referenced xml files + --novalidate don't validate xml files against compound.xsd + --noseealsoall don't add all functions under see also + --nosort don't sort functions under see also + --nostructs don't print structs in function man pages + -o DIR, --out DIR output directory + -s STR, --section STR man page section + --short-pkg STR short man page header/footer string, e.g. 'Linux' + --pkg STR man page header/footer string, e.g. 'Linux Programmer's Manual' + -i STR, --include STR include path prefix + + +AUTHOR +------ + +Written by Georg Sauthoff + +Don't hesitate to mail questions, comments or other feedback. + +LICENSE +------- + +GPLv3+ + + + diff --git a/main.pro b/main.pro index 42e5e90..77790bb 100644 --- a/main.pro +++ b/main.pro @@ -10,3 +10,6 @@ QMAKE_CXXFLAGS_DEBUG = -g -Wall -Wno-unused-parameter -Wno-switch HEADERS += main.h SOURCES += main.cc +doc.target = doxy2man.8 +doc.commands = asciidoc.py -v -d manpage -b docbook doxy2man.8.txt && xsltproc --nonet -o doxy2man.8 /usr/share/asciidoc/docbook-xsl/manpage.xsl doxy2man.8.xml +QMAKE_EXTRA_TARGETS += doc -- 1.8.3.1