doc: documentation restructuring

- changes the modules hierarchy to better represent the set of libaries
- list the header file that needs to be included
- remove examples/doc from api ref that is included in the guide
- add references to the guide
- fix doxygen api linking for version 1.8.0
- readd doxygen mainpage to config file
- fix a couple of doxygen doc bugs

8 files changed, 37 insertions, 48 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 8bb4fd5d..d515db21 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -181,11 +181,11 @@ TAB_SIZE               = 8
 
 ALIASES                = arg=\param
 
-ALIASES += ref_asciidoc{3}="<a href=\"../\1.html#\2\">\3</a>"
-ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Library)}"
-ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Routing Family Library)}"
-ALIASES += core_doc{2}="\par Related Documentation:\n\ref_core{\1,\2}"
-ALIASES += route_doc{2}="\par Related Documentation:\n\ref_route{\1,\2}"
+ALIASES += ref_asciidoc{3}="<a href=\"../\1.html#\2\"><b>\3</b></a>"
+ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Core Library Development Guide)}"
+ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Netlink Routing Development Guide)}"
+ALIASES += core_doc{2}="\ref_core{\1,\2}"
+ALIASES += route_doc{2}="\ref_route{\1,\2}"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.
@@ -590,7 +590,8 @@ WARN_LOGFILE           =
 INPUT                  = @top_srcdir@/lib \
                          @top_srcdir@/src/lib \
                          @top_srcdir@/include/netlink \
-                         @top_srcdir@/src
+                         @top_srcdir@/src \
+                         @top_srcdir@/doc/src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 142dc31b..ffa22459 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -20,7 +20,6 @@ EXTRA_DIST = \
 	doxygen-link.py \
 	gen-tags.sh \
 	resolve-asciidoc-refs.py \
-	tags2dict.sh \
 	stylesheets/asciidoc.css \
 	stylesheets/asciidoc-manpage.css \
 	stylesheets/docbook-xsl.css \
@@ -78,28 +77,26 @@ EXTRA_DIST = \
 	images/icons/callouts/14.png \
 	images/icons/callouts/15.png
 
-%.html: %.txt
+link_doc:
 if LINK_DOC
+	./gen-tags.sh > libnl.dict
+else
+	@echo "Warning: Linking to API reference is disabled, check configure output"
+endif
+	
+
+%.html: %.txt link_doc
 	./resolve-asciidoc-refs.py $< > asciidoc.tmp
 	asciidoc $(ASCIIDOCOPTS) -o $@ asciidoc.tmp
+if LINK_DOC
 	./doxygen-link.py libnl.dict $@ > asciidoc.tmp
 	mv asciidoc.tmp $@
-else
-	asciidoc $(ASCIIDOCOPTS) -o $@ $<
 endif
 
 asciidoc: core.html route.html index.html
 
-link_doc:
-if LINK_DOC
-	./gen-tags.sh | ./tags2dict.sh > libnl.dict
-else
-	@echo "Warning: Linking to API reference is disabled, check configure output"
-endif
-
 api_ref:
 	doxygen Doxyfile;
-	$(MAKE) link_doc
 
 gendoc:
 if GENERATE_DOC
diff --git a/doc/README b/doc/README
index 0c230a2c..0784e13b 100644
--- a/doc/README
+++ b/doc/README
@@ -6,5 +6,5 @@ mscgen
 mscgen-filter-1.2
   http://code.google.com/p/asciidoc-mscgen-filter/
 
-asciidoc 8.6.x
-doxygen
+asciidoc > 8.6.x
+doxygen > 1.8.0
diff --git a/doc/api/.gitignore b/doc/api/.gitignore
index 821cf658..e57ca889 100644
--- a/doc/api/.gitignore
+++ b/doc/api/.gitignore
@@ -3,5 +3,6 @@
 *.css
 *.map
 *.md5
+*.js
 formula.repository
 jquery.js
diff --git a/doc/core.txt b/doc/core.txt
index 7f26e051..8a26dbad 100644
--- a/doc/core.txt
+++ b/doc/core.txt
@@ -2811,6 +2811,17 @@ is stored in +*result+.
 NOTE: Make sure to return the reference to an address using
       `nl_addr_put()` after usage to allow memory being freed.
 
+.Example: Transform character string to abstract address
+[source,c]
+-----
+struct nl_addr *a = nl_addr_parse("::1", AF_UNSPEC);
+printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a)));
+nl_addr_put(a);
+a = nl_addr_parse("11:22:33:44:55:66", AF_UNSPEC);
+printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a)));
+nl_addr_put(a);
+-----
+
 .Address References
 
 Abstract addresses use reference counting to account for all users of
diff --git a/doc/gen-tags.sh b/doc/gen-tags.sh
index aba66720..862ec090 100755
--- a/doc/gen-tags.sh
+++ b/doc/gen-tags.sh
@@ -5,16 +5,10 @@
 # written by Carsten Haitzler <ras...@rasterman.com>
 #
 
-echo '<libnltags>'
 for f in api/group__*.html
 do
 	bf=$(basename $f)
 
-	grep -oE '<!-- doxytag.* -->' $f |
-		sed 's/<!-- doxytag:/<libnltag/' |
-		sed "s/-->/file=\"$bf\" \/>/" |
-		sed "s/ ref=\"/ href=\"$bf#/" |
-		sed 's/ member="\([^:]*::\)\([^"]*\)"/ member="\2"/' |
-		sed 's/ member="\([^"]*\)"/ short="\1"/'
+	grep -oE "href=\"$bf#[a-z0-9]+\">[^<]+</a>" $f |
+		sed 's/href="\([^"]*\)">\([^<]*\)<\/a>/\2=api\/\1/'
 done
-echo '</libnltags>'
diff --git a/doc/src/toc.c b/doc/src/toc.c
index ba7e07a4..570c1dfe 100644
--- a/doc/src/toc.c
+++ b/doc/src/toc.c
@@ -9,11 +9,11 @@
 
 libnl is a set of libraries to deal with the netlink protocol and some
 of the high level protocols implemented on top of it. The goal is to
-provide APIs on different levels of abstraction. The core library libnl.so
+provide APIs on different levels of abstraction. The core library libnl
 provides a fundamental set of functions to deal with sockets, construct
 messages, and send/receive those messages. Additional high level interfaces
 for several individual netlink protocols are provided in separate
-libraries (e.g. "nl-route.so", "nl-genl.so", ...).
+libraries (e.g. "nl-route", "nl-genl", ...).
 
 The library is designed to ensure that all components are optional, i.e.
 even though the core library provides a caching system which allows to
@@ -33,16 +33,9 @@ version is used with a considerably older kernel.
 \subsection tree_dev Development Tree
 
 @code
-git://git.kernel.org/pub/scm/libs/netlink/libnl.git
+git://git.infradead.org/users/tgr/libnl.git
 @endcode
-- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl.git
-
-\subsection tree_stable Stable Tree
-
-@code
-git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git
-@endcode
-- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl-stable.git
+- Web: http://git.infradead.org/users/tgr/libnl.git
 
 \section main_website Website
 
@@ -50,7 +43,7 @@ git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git
 
 \section main_mailinglist Mailinglist
 
-Please post question and patches to the libnl mailinglist:
+Please post questions and patches to the libnl mailinglist:
 
 @code
 libnl@lists.infradead.org
diff --git a/doc/tags2dict.sh b/doc/tags2dict.sh
deleted file mode 100755
index 76407af2..00000000
--- a/doc/tags2dict.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/bin/bash
-xmlstarlet sel	-t \
-		-m "/libnltags/libnltag[@href]" \
-		-v "@short" \
-		-o "=api/" \
-		-v "@href" \
-		-n
-