From c8e1897c969ce43b551c29d65bc605f175c01263 Mon Sep 17 00:00:00 2001
From: Matthias Andree <matthias.andree@gmx.de>
Date: Thu, 2 Jul 2009 19:48:34 +0000
Subject: Update trio to CVS checkout of 2009-07-02.

svn path=/branches/BRANCH_6-3/; revision=5370
---
 trio/doc/doc_register.h | 45 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 9 deletions(-)

(limited to 'trio/doc/doc_register.h')

diff --git a/trio/doc/doc_register.h b/trio/doc/doc_register.h
index 03610bfa..3ce86c57 100644
--- a/trio/doc/doc_register.h
+++ b/trio/doc/doc_register.h
@@ -1,6 +1,6 @@
 /*************************************************************************
  *
- * $Id: doc_register.h,v 1.2 2002/04/20 13:28:09 breese Exp $
+ * $Id: doc_register.h,v 1.3 2008/10/12 12:09:51 breese Exp $
  *
  * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg.
  *
@@ -35,24 +35,51 @@ This documentation is incomplete.
 
 The user-defined specifier consists of a start character (\074 = '<'), an
 optional namespace string followed by a namespace separator (\072 = ':'),
-a format string, and an end character (\076 = '>').
+a format string, an optional skipping separator (\174 = '|'), and an end
+character (\076 = '>').
 
 The namespace string can consist of alphanumeric characters, and is used to
 define a named reference (see below). The namespace is case-sensitive. If no
 namespace is specified, then we use an unnamed reference (see below).
 
 The format can consist of any character except the end character ('>'), the
-namespace separator (':'), and the nil character (\000).
+namespace separator (':'), the skipping separator ('|'), and the nil character
+(\000).
 
 Any modifier can be used together with the user-defined specifier.
 
+There are two formats for invoking a user-defined specifier. The first format
+is an extension of the normal printf/scanf formatting. It uses the percent
+character (\045 = '%') followed by optional qualifiers and a specifier. For
+example:
+
+@verbatim
+  trio_printf("%<format>\n", my_handle, my_data);
+@endverbatim
+
+Some C compilers can issue a warning if there is a mismatch between specifiers
+and arguments. Unfortunately, these warnings does not work with the first
+format for user-defined specifiers. Therefore the second format has been
+introduced. The second format can only be applied to user-defined specifiers.
+
+The second format starts with a dollar character (\044 = '$') instead of the
+percent character, and is followed by optional qualifiers and the user-defined
+specifier. If the specifier contains a pipe character (\174 = '|'), then
+everything between the pipe character and the end character ('>') is ignored.
+The ignored part can be used to list the normal specifiers that the C compiler
+uses to determine mismatches. For example:
+
+@verbatim
+  trio_printf("$<format|%p%p>\n", my_handle, my_data);
+@endverbatim
+
 @b Registering
 
 A user-defined specifier must be registered before it can be used.
 Unregistered user-defined specifiers are ignored. The @ref trio_register
 function is used to register a user-defined specifier. It takes two argument,
 a callback function and a namespace, and it returns a handle. The handle must
-be used to unregister the specifier later. 
+be used to unregister the specifier later.
 
 The following example registers a user-define specifier with the "my_namespace"
 namespace:
@@ -79,7 +106,7 @@ If the namespace is used, then a user-defined pointer must be passed as an
 argument:
 
 @verbatim
-  trio_printf("<my_namespace:format>\n", my_data);
+  trio_printf("%<my_namespace:format>\n", my_data);
 @endverbatim
 
 If the handle is used, then the user-defined specifier must not contain a
@@ -87,7 +114,7 @@ namespace. Instead the handle must be passed as an argument, followed by a
 user-defined pointer:
 
 @verbatim
-  trio_printf("<format>\n", my_handle, my_data);
+  trio_printf("%<format>\n", my_handle, my_data);
 @endverbatim
 
 The two examples above are equivalent.
@@ -107,7 +134,7 @@ No namespace can be specified.
 
 @verbatim
   anon_handle = trio_register(callback, NULL);
-  trio_printf("<format>\n", anon_handle, my_data);
+  trio_printf("%<format>\n", anon_handle, my_data);
 @endverbatim
 
 @b Restrictions
@@ -166,7 +193,7 @@ equivalents.
 
 @verbatim
   trio_print_ref(ref, "There are %d towels\n", 42);
-  trio_print_ref(ref, "%<recursive>\n", recursive_writer, trio_get_argument());
+  trio_print_ref(ref, "%<recursive>\n", recursive_writer, trio_get_argument(ref));
 @endverbatim
 
 @b GETTER @b AND @b SETTER @b FUNCTIONS
@@ -218,7 +245,7 @@ Print the time in the format "HOUR:MINUTE:SECOND" if "time" is specified inside
 the user-defined specifier.
 
 @verbatim
-  static int time_writer(void *ref)
+  static int time_print(void *ref)
   {
     const char *format;
     time_t *data;
-- 
cgit v1.2.3