Add some libgcrypt dox

6 files changed, 467 insertions, 77 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 39fabf9b..04ad0a4c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,31 +1,33 @@
 ## Process this file with automake to create Makefile.in
 
-##SUBDIRS = gph
-
 EXTRA_DIST = DETAILS gpg.sgml gpg.1 FAQ HACKING OpenPGP
 
 man_MANS = gpg.1
 
 
+gcryptref.dvi : gcryptref.sgml
+
+gcryptref.texi : gcryptref.sgml
+gcryptref.xml  : gcryptref.sgml
+
+
+%.ps: %.dvi
+	dvips -o $@ $<
+
+
+if MAINTAINER_MODE
+
 %.1 : %.sgml
-if HAVE_DOCBOOK_TO_MAN
 	docbook-to-man $<  >$@
-else
-	: Warning: missing docbook-to-man, cannot make $@
-	echo ".TH $< 1"   >$@
-	echo "No man page due to missing docbook-to-man" >>$@
-endif
 
+%.texi : %.xml
+	docbook2texi $< >$@
 
-gcryptref.dvi : gcryptref.sgml
+%.xml  : %.sgml
+	sgml2xml -x lower $< >$@
 
-%.dvi: %.sgml
-	db2dvi $<
+endif
 
-%.ps: %.dvi
-	dvips -o $@ $<
 
-%/%.html: %.sgml
-	-db2html $<
 
 
diff --git a/doc/cipher-ref.sgml b/doc/cipher-ref.sgml
index 1253b38f..379de5a7 100644
--- a/doc/cipher-ref.sgml
+++ b/doc/cipher-ref.sgml
@@ -18,6 +18,9 @@
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 -->
 
+<!--**********************************************
+***********  cipher open, close  *****************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_open</refname>
@@ -48,6 +51,8 @@
   <para>
   <indexterm><primary>cipher functions</primary>
 	     <secondary>gcry_cipher_open</secondary>
+	     </indexterm>
+  <indexterm><primary>cipher functions</primary>
 	     <secondary>gcry_cipher_close</secondary>
 	     </indexterm>
   <function>gcry_cipher_open</function> creates the context required for
@@ -56,6 +61,9 @@
 </refentry>
 
 
+<!--**********************************************
+***********  cipher control  *********************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_ctl</refname>
@@ -98,6 +106,9 @@
 </refentry>
 
 
+<!--**********************************************
+***********  cipher info   ***********************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_info</refname>
@@ -130,6 +141,9 @@
 </refentry>
 
 
+<!--**********************************************
+***********  cipher algo name	******************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_algo_name</refname>
@@ -161,6 +175,9 @@
   </para>
 </refentry>
 
+<!--**********************************************
+***********  cipher map name  ********************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_map_name</refname>
@@ -191,7 +208,9 @@
   </para>
 </refentry>
 
-
+<!--**********************************************
+***********  cipher en/decryptlose  **************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_cipher_encrypt</refname>
@@ -228,6 +247,8 @@
   <para>
   <indexterm><primary>cipher functions</primary>
 	     <secondary>gcry_cipher_encrypt</secondary>
+	     </indexterm>
+  <indexterm><primary>cipher functions</primary>
 	     <secondary>gcry_cipher_decrypt</secondary>
 	     </indexterm>
   <function>gcry_cipher_encrypt</function> is used to encrypt the data.
diff --git a/doc/digest-ref.sgml b/doc/digest-ref.sgml
index 63a345a7..f0d5efff 100644
--- a/doc/digest-ref.sgml
+++ b/doc/digest-ref.sgml
@@ -18,6 +18,9 @@
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 -->
 
+<!--**********************************************
+***********  md_open, close, enable  ************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_md_open</refname>
@@ -53,7 +56,11 @@
   <para>
   <indexterm><primary>hash functions</primary>
 	     <secondary>gcry_md_open</secondary>
+	     </indexterm>
+  <indexterm><primary>hash functions</primary>
 	     <secondary>gcry_md_enable</secondary>
+	     </indexterm>
+  <indexterm><primary>hash functions</primary>
 	     <secondary>gcry_md_close</secondary>
 	     </indexterm>
   <function>gcry_md_open</function> creates the context required for
@@ -69,6 +76,9 @@
   </para>
 </refentry>
 
+<!--**********************************************
+***********  md_copy *****************************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_md_copy</refname>
@@ -99,6 +109,9 @@
   </para>
 </refentry>
 
+<!--**********************************************
+***********  md_reset  ***************************
+***********************************************-->
 <refentry>
   <refnamediv>
     <refname>gcry_md_reset</refname>
@@ -129,8 +142,13 @@
 </refentry>
 
 
+<!--**********************************************
+***********  md_ctl  *****************************
+***********************************************-->
+<refentry>
   <refnamediv>
     <refname>gcry_md_ctl</refname>
+    <refname>gcry_md_final</refname>
     <refpurpose>perform special operations on a digest context</refpurpose>
   </refnamediv>
 
@@ -159,33 +177,292 @@
   to control the behaviour of all gcry_md functions or one instance
   of it.
   </para>
+  <para>
+  Currently defined values for <parameter>cmd</> are:
+    <literal>GCRYCTL_FINALIZE</> and the conevnience macro
+    <function>gcry_md_final(a)</>
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_write, putc  *********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_write</refname>
+    <refname>gcry_md_putc</refname>
+    <refpurpose>calculate the message digest of a buffer</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_write</function></funcdef>
+	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+	<paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
+	<paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_putc</function></funcdef>
+	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+	<paramdef>int <parameter>c</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_write</secondary></indexterm>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_putc</secondary></indexterm>
+  <function>gcry_md_write</function> is used to actually calulate the message
+  digest of a buffer.  This function updates the internal state of the message
+  digest.
+  </para>
+  <para>
+  <function>gcry_md_putc</function> is a macro which is used to update
+  the message digest by one byte.  this is the preferred way to calculate
+  a digest if only a few bytes at a time are available.
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_read *****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_read</refname>
+    <refpurpose>read out the message digest</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
+	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+	<paramdef>int <parameter>algo</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_read</secondary>
+	     </indexterm>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_putc</secondary>
+	     </indexterm>
+  <function>gcry_md_read</function> returns the message digest after finalizing
+  the calculation.  This function may be used as often as required but it
+  will alwas return the same value for one handle.  The returned message
+  digest is allocated within the message context and therefore valid until
+  the conext is released.  <parameter>algo</> may be given as 0 to return the
+  only enbaled message digest or it may specify one of the enabled algorithms.
+  The function will return NULL if the algorithm has not been enabled.
+  </para>
 </refentry>
 
 
-void gcry_md_write( GCRY_MD_HD hd, const byte *buffer, size_t length);
-byte *gcry_md_read( GCRY_MD_HD hd, int algo );
-void gcry_md_hash_buffer( int algo, char *digest,
-			  const char *buffer, size_t length);
-int gcry_md_get_algo( GCRY_MD_HD hd );
-unsigned int gcry_md_get_algo_dlen( int algo );
-int gcry_md_info( GCRY_MD_HD h, int what, void *buffer, size_t *nbytes);
-int gcry_md_algo_info( int algo, int what, void *buffer, size_t *nbytes);
-const char *gcry_md_algo_name( int algo );
-int gcry_md_map_name( const char* name );
-
-#define gcry_md_putc(h,c)  \
-	    do {					\
-		if( (h)->bufpos == (h)->bufsize )	\
-		    gcry_md_write( (h), NULL, 0 );	\
-		(h)->buf[(h)->bufpos++] = (c) & 0xff;	\
-	    } while(0)
-
-#define gcry_md_final(a) \
-	    gcry_md_ctl( (a), GCRYCTL_FINALIZE, NULL, 0 )
-
-#define gcry_md_is_secure(a) \
-	    gcry_md_info( (a), GCRYCTL_IS_SECURE, NULL, NULL )
-
-#define gcry_md_test_algo(a) \
-	    gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
+<!--**********************************************
+***********  md_info  ****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_info</refname>
+    <refpurpose>get information about a handle</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_info</function></funcdef>
+	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+	<paramdef>int	     <parameter>what</parameter></paramdef>
+	<paramdef>void * <parameter>buffer</parameter></paramdef>
+	<paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_info</secondary>
+	     </indexterm>
+  <function>gcry_md_info</function> returns some information about the
+  handle or an global parameter.
+  </para>
+  <para>
+  The only defined value for <parameter>what</> is
+  <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
+  has been allocated in secure memory.	Buffer and buflen are not needed
+  in this cases.  The convenience macro <function>gcry_md_is_secure(a)</>
+  may be also used for this purpose.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_algo_info  ***********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_algo_info</refname>
+    <refname>gcry_md_test_algo</refname>
+    <refname>gcry_md_get_algo_dlen</refname>
+    <refpurpose>get information about an algorithm</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_algo_info</function></funcdef>
+	<paramdef>int	     <parameter>algo</parameter></paramdef>
+	<paramdef>int	     <parameter>what</parameter></paramdef>
+	<paramdef>void * <parameter>buffer</parameter></paramdef>
+	<paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+	<funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
+	<paramdef>int <parameter>algo</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_algo_info</secondary>
+	     </indexterm>
+  <function>gcry_md_algo_info</function> returns some information about an
+  algorithm.  On error the value -1 is return and a more detailed error
+  description is available with <function>gcry_errno</>.
+  </para>
+  <para>
+  The defined values for <parameter>what</> are
+  <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
+  is supported. Buffer and buflen are not needed
+  in this cases.  The convenience macro <function>gcry_md_test_algo(a)</>
+  may be used for this purpose.
+  </para>
+  <para>
+  <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
+  object identifier.  IF buffer is specified as NULL, only the required
+  length for the buffer is returned.
+  </para>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_get_algo_dlen</secondary>
+	     </indexterm>
+  <function>gcry_md_get_algo_dlen</function> returns the length of the
+  digest for a given algorithm in bytes.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_algo_name, map_name  *************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_algo_name</refname>
+    <refname>gcry_md_map_name</refname>
+    <refpurpose>map algorithm to string</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
+	<paramdef>int	     <parameter>algo</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_map_name</function></funcdef>
+	<paramdef>const char*<parameter>name</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_algo_name</secondary>
+	     </indexterm>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_map_name</secondary>
+	     </indexterm>
+  These both functions are used to map a string with the algorithm name to
+  the internal algorithm identifier value and vice versa.
+  </para>
+  <para>
+  <function>gcry_md_algo_name</> never returns NULL even in cases where the
+  algorithm string is not available.  Instead a string consisting of a
+  single question mark is returned.  Do not use this function to test
+  for the existence of an algorithm.
+  </para>
+  <para>
+  <function>gcry_md_map_name</> returns 0 if the algorithm is not known
+  to &libgcrypt;.
+  </para>
+</refentry>
+
+
+
+<!--**********************************************
+***********  md_hash_buffer  *********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_hash_buffer</refname>
+    <refpurpose>fast message calculation</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
+	<paramdef>int  <parameter>algo</parameter></paramdef>
+	<paramdef>char * <parameter>digest</parameter></paramdef>
+	<paramdef>const char * <parameter>buffer</parameter></paramdef>
+	<paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+	     <secondary>gcry_md_hash_buffer</secondary>
+	     </indexterm>
+  <function>gcry_md_hash_buffer</function> is a shortcut function
+  to calculate a message digest of a buffer.  This function does not require
+  a context and immediatley returns the message digest.
+  <parameter>digest</> must be string large enough to hold the digest
+  given by algo.  This length may be obtained by using the function
+  <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
+  allocated buffer.
+  </para>
+</refentry>
 
diff --git a/doc/misc-ref.sgml b/doc/misc-ref.sgml
index 88193186..31032d64 100644
--- a/doc/misc-ref.sgml
+++ b/doc/misc-ref.sgml
@@ -18,3 +18,50 @@
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 -->
 
+<!--
+const char *gcry_check_version( const char *req_version );
+
+int gcry_errno(void);
+const char *gcry_strerror( int ec );
+int gcry_control( enum gcry_ctl_cmds, ... );
+
+
+
+
+void gcry_set_allocation_handler( void *(*new_alloc_func)(size_t n),
+				  void *(*new_alloc_secure_func)(size_t n),
+				  int (*new_is_secure_func)(const void*),
+				  void *(*new_realloc_func)(void *p, size_t n),
+				  void (*new_free_func)(void*) );
+void gcry_set_outofcore_handler( int (*h)( void*, size_t, unsigned int ),
+								void *opaque );
+void gcry_set_fatalerror_handler( void (*fnc)(void*,int, const char*),
+								void *opaque );
+void gcry_set_gettext_handler( const char *(*f)(const char*) );
+void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
+							     void *opaque );
+
+void *gcry_malloc( size_t n );
+void *gcry_calloc( size_t n, size_t m );
+void *gcry_malloc_secure( size_t n );
+void *gcry_calloc_secure( size_t n, size_t m );
+void *gcry_realloc( void *a, size_t n );
+void *gcry_xmalloc( size_t n );
+void *gcry_xcalloc( size_t n, size_t m );
+void *gcry_xmalloc_secure( size_t n );
+void *gcry_xcalloc_secure( size_t n, size_t m );
+void *gcry_xrealloc( void *a, size_t n );
+char *gcry_xstrdup( const char * a);
+void  gcry_free( void *a );
+int   gcry_is_secure( const void *a );
+
+
+void gcry_randomize( byte *buffer, size_t length,
+		     enum gcry_random_level level );
+void *gcry_random_bytes( size_t nbytes, enum gcry_random_level level );
+void *gcry_random_bytes_secure( size_t nbytes, enum gcry_random_level level );
+
+
+
+    -->
+
diff --git a/doc/pubkey-ref.sgml b/doc/pubkey-ref.sgml
index 88193186..a1a97dc9 100644
--- a/doc/pubkey-ref.sgml
+++ b/doc/pubkey-ref.sgml
@@ -18,3 +18,75 @@
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 -->
 
+
+<!--**********************************************
+***********  pk_encrypt  *************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_pk_encrypt</refname>
+    <refpurpose>do a public key encryption</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+	<funcdef>int <function>gcry_pk_encrypt</function></funcdef>
+	<paramdef>GCRY_SEXP *<parameter>result</parameter></paramdef>
+	<paramdef>GCRY_SEXP  <parameter>data</parameter></paramdef>
+	<paramdef>GCRY_SEXP  <parameter>pkey</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>public key functions</primary>
+	     <secondary>gcry_pk_encrypt</secondary>
+	     </indexterm>
+  <function>gcry_pk_encrypt</function> performs public key encryption
+  operations.  The caller has to provide a public key as the &sexp;
+  <parameter>pkey</> and <parameter>data</> as a &sexp;
+  with just one MPI in it.  The function returns a &sexp; which may
+  be passed tp to pk_decrypt.
+  Later versions of this functions may take more complex input data.
+
+  Returns: 0 or an errorcode.
+  </para>
+  <literallayout>
+  s_data = (<replaceable/mpi/)
+  s_pkey = <replaceable/key-as-defined-in-sexp_to_key/
+  r_ciph = (enc-val
+	     (<replaceable/algo/
+	       (<replaceable/param_name1/ <replaceable/mpi/)
+	       ...
+	       (<replaceable/param_namen/ <replaceable/mpi/)
+	     ))
+  </literallayout>
+</refentry>
+
+
+<!--
+int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
+
+
+
+int gcry_pk_sign(    GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
+int gcry_pk_verify(  GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
+int gcry_pk_testkey( GCRY_SEXP key );
+int gcry_pk_genkey(  GCRY_SEXP *r_key, GCRY_SEXP s_parms );
+
+int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
+int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
+#define gcry_pk_test_algo(a) \
+	    gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
+
+const char *gcry_pk_algo_name( int algo );
+int gcry_pk_map_name( const char* name );
+unsigned int gcry_pk_get_nbits( GCRY_SEXP key );
+    -->
+
diff --git a/doc/reference.sgml b/doc/reference.sgml
index 6161e861..abc3efb2 100644
--- a/doc/reference.sgml
+++ b/doc/reference.sgml
@@ -20,56 +20,27 @@
 
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
 <!entity libgcrypt "Libgcrypt">
+<!entity sexp	   "S-Exp">
 <!entity cipherref system "gcryptref-cipher.sgml">
 <!entity digestref system "gcryptref-digest.sgml">
 <!entity pubkeyref system "gcryptref-pubkey.sgml">
 <!entity miscref   system "gcryptref-misc.sgml">
 ]>
 
-<!--
-<refentry>
-  <refnamediv>
-    <refname>XXX</refname>
-    <refpurpose>xxx</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <funcsynopsis>
-      <funcsynopsisinfo>
-      #include &lt;gcrypt.h&gt;
-      </funcsynopsisinfo>
-      <funcprototype>
-	<funcdef>int <function>XXX</function></funcdef>
-	<paramdef>int <parameter>algo</parameter></paramdef>
-      </funcprototype>
-  </refsynopsisdiv>
-
-
-  <refsect1><title>Description</title>
-  <para>
-  <indexterm><primary>cipher functions</primary>
-	     <secondary>XXX</secondary>
-	     </indexterm>
-  <function>XXX</function> xxx
-
-  </para>
-</refentry>
--->
 
 <reference>
 <title>&libgcrypt; Reference Pages</title>
-
-<subtitle>Symmetric Cipher Functions</subtitle>
+<!--FIXME: How can we subdivide a reference (Part?)
+    Symmetric Cipher Functions -->
 &cipherref;
 
-<subtitle>Hash Functions</subtitle>
+<!-- Hash Functions -->
 &digestref;
 
-<subtitle>Public Key Functions</subtitle>
+<!-- ublic Key Functions -->
 &pubkeyref;
 
-
-<subtitle>Miscellaneous Functions</subtitle>
+<!-- Miscellaneous Functions  -->
 &miscref;
 
 </reference>