using a dedicated folder for documentation in each subproject

git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@587 96b47cad-a561-4643-ad3b-153ac7d7599c

npa/Makefile.am

@@ -1,7 +1,7 @@
 ACLOCAL_AMFLAGS = -I m4
-SUBDIRS = src m4
+SUBDIRS = src m4 doc
 
-EXTRA_DIST = README.dox libnpa.pc.in Doxyfile.in apdus
+EXTRA_DIST = libnpa.pc.in apdus
 
 do_subst = sed \
 	   -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
@@ -24,8 +24,7 @@ win:
 if DOC_ENABLED
 .PHONY: doc
 doc :
-	$(do_subst) < $(srcdir)/Doxyfile.in > Doxyfile
-	$(DOXYGEN) Doxyfile
+	$(MAKE) doc -C doc
 endif
 
 pkgconfigdir = $(libdir)/pkgconfig
@@ -34,4 +33,4 @@ libnpa.pc:
 	$(do_subst) < $(srcdir)/libnpa.pc.in > libnpa.pc
 
 clean-local:
-	rm -rf doc Doxyfile libnpa.pc
+	rm -f libnpa.pc

npa/README

@@ -1 +1 @@
-README.dox
+doc/README.rst

npa/configure.ac

@@ -111,5 +111,6 @@ AC_CONFIG_FILES([
                  Makefile
                  m4/Makefile
                  src/Makefile
+                 doc/Makefile
                  ])
 AC_OUTPUT

npa/doc/Doxyfile.in

@@ -1,11 +1,11 @@
 FILE_PATTERNS          = *.h
 GENERATE_HTML          = YES
 GENERATE_LATEX         = NO
-GENERATE_TAGFILE       = @builddir@/doc/@PACKAGE_NAME@.tag
+GENERATE_TAGFILE       = @builddir@/@PACKAGE_NAME@.tag
 GENERATE_XML           = YES
 INPUT                  = @top_srcdir@/src/npa
 OPTIMIZE_OUTPUT_FOR_C  = YES
-OUTPUT_DIRECTORY       = @builddir@/doc
+OUTPUT_DIRECTORY       = @builddir@
 PROJECT_NAME           = @PACKAGE_NAME@
 PROJECT_NUMBER         = @PACKAGE_VERSION@
 STRIP_FROM_PATH        = @top_srcdir@/src

npa/doc/Makefile.am

@@ -0,0 +1,25 @@
+ACLOCAL_AMFLAGS = -I m4
+
+do_subst = sed \
+	   -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
+	   -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' \
+	   -e 's,[@]builddir[@],$(builddir),g' \
+	   -e 's,[@]prefix[@],$(prefix),g' \
+	   -e 's,[@]exec_prefix[@],$(exec_prefix),g' \
+	   -e 's,[@]libdir[@],$(libdir),g' \
+	   -e 's,[@]includedir[@],$(includedir),g' \
+	   -e 's,[@]VERSION[@],$(VERSION),g' \
+	   -e 's,[@]OPENSC_LIBS[@],$(OPENSC_LIBS),g' \
+	   -e 's,[@]top_srcdir[@],$(top_srcdir),g'
+
+EXTRA_DIST = README.rst Doxyfile.in example.c
+
+if DOC_ENABLED
+.PHONY: doc
+doc :
+	$(do_subst) < Doxyfile.in > Doxyfile
+	$(DOXYGEN) Doxyfile
+endif
+
+clean-local:
+	rm -f Doxyfile

npa/doc/api.rst

@@ -0,0 +1,82 @@
+.. highlight:: c
+
+********************************
+Programming with the nPA Library
+********************************
+
+The nPA library includes a generic implementation for Secure Messaging (SM),
+which might also be used in conjunction with other cards. It is implemented to
+be close to ISO 7816-8 focusing only on encoding rather than implementing
+everything that is needed to get a secure channel. All cryptographic work is
+done by call back functions, which should be appropriatly set for the specific
+card.
+
+Using the German identity card (neuer Personalausweis, nPA) requires user
+authentication via entry of the PIN. Transmitting the PIN in plaintext is
+risky, since it would be transmitted over the air and could be snooped. That's
+why the PACE keyagreement is used to verify the PIN and establish an SM channel
+to the nPA. :npa:`EstablishPACEChannel` does exactly that and if everything
+went fine, it initializes :npa:`sm_ctx` for use of the SM channel. Now
+:npa:`sm_transmit_apdu` can be used to securely transmit arbitrary APDUs to the
+card. You could for example change your PIN or even continue the Extended
+Access Control (EAC) with Terminal Authentication (TA) and Chit Authenitcation
+(CA).
+
+Please consider the following overview to the API as incomplete. The `Doxygen
+documentation <_static/doxygen-npa/modules.html>`_ should be used as programmer's
+reference since it is more detailed.
+
+=====================
+Secure Messaging (SM)
+=====================
+
+The complete documentation can be found `here
+<_static/doxygen-npa/group__sm.html>`_.
+
+-----
+Types
+-----
+.. doxygenstruct:: sm_ctx
+
+---------
+Functions
+---------
+.. doxygenfunction:: sm_transmit_apdu
+.. doxygenfunction:: sm_ctx_clear_free
+
+==============================================================
+Interface to German identity card (neuer Personalausweis, nPA)
+==============================================================
+
+The complete documentation can be found `here
+<_static/doxygen-npa/group__npa.html>`_.
+
+-----
+Types
+-----
+.. doxygenstruct:: establish_pace_channel_input
+.. doxygenstruct:: establish_pace_channel_output
+
+---------
+Functions
+---------
+.. doxygenfunction:: EstablishPACEChannel
+.. doxygenfunction:: npa_reset_retry_counter
+
+-------
+Defines
+-------
+.. doxygendefine:: npa_change_pin
+.. doxygendefine:: npa_unblock_pin
+
+=======
+Example
+=======
+
+In order to compile and execute this example you need to correctly :ref:`set up
+your environment <npa-usage>`.
+
+.. literalinclude:: example.c
+    :lines: 20-
+
+.. @author Frank Morgner <morgner@informatik.hu-berlin.de>

npa/doc/example.c

@@ -0,0 +1 @@
+../src/example.c