Improve option --pic. New options --string-pool-name, --null-strings.

1 files changed, 58 insertions, 9 deletions

diff --git a/doc/gperf.texi b/doc/gperf.texi
index 56676ce..0ebfd5d 100644
--- a/doc/gperf.texi
+++ b/doc/gperf.texi
@@ -7,7 +7,7 @@
 
 @c some day we should @include version.texi instead of defining
 @c these values at hand.
-@set UPDATED 8 December 2002
+@set UPDATED 1 January 2003
 @set EDITION 2.7.2
 @set VERSION 2.7.2
 @c ---------------------
@@ -28,7 +28,7 @@
 This file documents the features of the GNU Perfect Hash Function
 Generator @value{VERSION}.
 
-Copyright @copyright{} 1989-2002 Free Software Foundation, Inc.
+Copyright @copyright{} 1989-2003 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are
@@ -65,7 +65,7 @@ Software Foundation instead of in the original English.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1989-2002 Free Software Foundation, Inc.
+Copyright @copyright{} 1989-2003 Free Software Foundation, Inc.
 
 
 Permission is granted to make and distribute verbatim copies of
@@ -365,10 +365,12 @@ act like command-line options, as well as for providing a user-supplied
 If the @samp{-t} option (or, equivalently, the @samp{%struct-type} declaration)
 @emph{is} enabled, you @emph{must} provide a C @code{struct} as the last
 component in the declaration section from the input file.  The first
-field in this struct must be a @code{char *} or @code{const char *}
-identifier called @samp{name}, although it is possible to modify this
-field's name with the @samp{-K} option (or, equivalently, the
-@samp{%define slot-name}) described below.
+field in this struct must be of type @code{char *} or @code{const char *}
+if the @samp{-P} option is not given, or of type @code{int} if the option
+@samp{-P} (or, equivalently, the @samp{%pic} declaration) is enabled.
+This first field must be called @samp{name}, although it is possible to modify
+its name with the @samp{-K} option (or, equivalently, the
+@samp{%define slot-name} declaration) described below.
 
 Here is a simple example, using months of the year and their attributes as
 input:
@@ -544,6 +546,34 @@ Generate the static table of keywords as a static global variable,
 rather than hiding it inside of the lookup function (which is the
 default behavior).
 
+@item %pic
+@cindex @samp{%pic}
+Optimize the generated table for inclusion in shared libraries.  This
+reduces the startup time of programs using a shared library containing
+the generated code.  If the @samp{%struct-type} declaration (or,
+equivalently, the option @samp{-t}) is also given, the first field of the
+user-defined struct must be of type @samp{int}, not @samp{char *}, because
+it will contain offsets into the string pool instead of actual strings.
+To convert such an offset to a string, you can use the expression
+@samp{stringpool + @var{o}}, where @var{o} is the offset.  The string pool
+name can be changed through the @samp{%define string-pool-name} declaration.
+
+@item %define string-pool-name @var{name}
+@cindex @samp{%define string-pool-name}
+Allows you to specify the name of the generated string pool created by
+the declaration @samp{%pic} (or, equivalently, the option @samp{-P}).
+The default name is @samp{stringpool}. This declaration permits the use of
+two hash tables in the same file, with @samp{%pic} and even when the
+@samp{%global-table} declaration (or, equivalently, the option @samp{-G})
+is given.
+
+@item %null-strings
+@cindex @samp{%null-strings}
+Use NULL strings instead of empty strings for empty keyword table entries.
+This reduces the startup time of programs using a shared library containing
+the generated code (but not as much as the declaration @samp{%pic}), at the
+expense of one more test-and-branch instruction at run time.
+
 @item %define word-array-name @var{name}
 @cindex @samp{%define word-array-name}
 Allows you to specify the name for the generated array containing the
@@ -952,8 +982,27 @@ default behavior).
 @itemx --pic
 Optimize the generated table for inclusion in shared libraries.  This
 reduces the startup time of programs using a shared library containing
-the generated code, at the expense of one more test-and-branch instruction
-at run time.
+the generated code.  If the option @samp{-t} (or, equivalently, the
+@samp{%struct-type} declaration) is also given, the first field of the
+user-defined struct must be of type @samp{int}, not @samp{char *}, because
+it will contain offsets into the string pool instead of actual strings.
+To convert such an offset to a string, you can use the expression
+@samp{stringpool + @var{o}}, where @var{o} is the offset.  The string pool
+name can be changed through the option @samp{--string-pool-name}.
+
+@item -Q @var{string-pool-name}
+@itemx --string-pool-name=@var{string-pool-name}
+Allows you to specify the name of the generated string pool created by
+option @samp{-P}.  The default name is @samp{stringpool}. This option
+permits the use of two hash tables in the same file, with @samp{-P} and
+even when the option @samp{-G} (or, equivalently, the @samp{%global-table}
+declaration) is given.
+
+@item --null-strings
+Use NULL strings instead of empty strings for empty keyword table entries.
+This reduces the startup time of programs using a shared library containing
+the generated code (but not as much as option @samp{-P}), at the expense
+of one more test-and-branch instruction at run time.
 
 @item -W @var{hash-table-array-name}
 @itemx --word-array-name=@var{hash-table-array-name}