include a manpage for doxy2man

diff --git a/README.md b/README.md
index 14291f7cfbf20ee1b0a13974520168ee11d244ab..49a7f2ffe6a37c4f95f4af24df4ba14664689816 100644 (file)
--- 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 (file)
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 <mail@georg.so>
+
+Don't hesitate to mail questions, comments or other feedback.
+
+LICENSE
+-------
+
+GPLv3+
+
+
+

diff --git a/main.pro b/main.pro
index 42e5e900d3436c67d21027532262e840032a587a..77790bb81ea114e7b4bfd0bbbe3e1a107bc938a4 100644 (file)
--- 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