diff options
author | Bruno Haible <bruno@clisp.org> | 2000-08-20 13:14:18 +0000 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2000-08-20 13:14:18 +0000 |
commit | ca7835bc4926c93a9f389fe6bc1239c61593753e (patch) | |
tree | 46438978b93258ddc8eabd63ba084b2dbd359691 | |
parent | b7b6ced2b04de0eb9b27b210f7ed9fa48704ec73 (diff) | |
download | gperf-ca7835bc4926c93a9f389fe6bc1239c61593753e.tar.gz |
Add nice autogenerated manual page.
-rw-r--r-- | ChangeLog | 5 | ||||
-rw-r--r-- | Makefile.devel | 5 | ||||
-rw-r--r-- | doc/gperf.1 | 202 | ||||
-rwxr-xr-x | doc/help2man | 513 |
4 files changed, 705 insertions, 20 deletions
@@ -1,5 +1,10 @@ 2000-08-20 Bruno Haible <bruno@linuix.math.u-bordeaux.fr> + * doc/help2man: New file, help2man version 1.022. + * Makefile.devel (all): Add doc/gperf.1. + (doc/gperf.1): New target. + * doc/gperf.1: Automatically generated. + * mkinstalldirs: New file, from automake-1.4, grep-2.4.1, guile-1.4, libtool-1.3.3, make-3.79.1, tar-1.13. * srcdir/Makefile.in (MKINSTALLDIRS): New variable. diff --git a/Makefile.devel b/Makefile.devel index e145bd8..cd6b628 100644 --- a/Makefile.devel +++ b/Makefile.devel @@ -4,7 +4,7 @@ SHELL = /bin/sh MAKE = make -all : configures src/config.h.in +all : configures src/config.h.in doc/gperf.1 CONFIGURES = configure lib/configure src/configure tests/configure doc/configure @@ -31,5 +31,8 @@ check-configures : $(CONFIGURES) src/config.h.in : src/configure.in aclocal.m4 cd src && autoheader -l .. +doc/gperf.1 : force + prog=`PATH=build/src:src:$$PATH which gperf`; if test -n "$$prog"; then doc/help2man --name='generate a perfect hash function from a key set' --section=1 $$prog > doc/gperf.1; fi + force : diff --git a/doc/gperf.1 b/doc/gperf.1 index 1e4a2aa..aa65ecf 100644 --- a/doc/gperf.1 +++ b/doc/gperf.1 @@ -1,23 +1,187 @@ -.TH GPERF 1 "March 7, 1998 -.UC 4 +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.022. +.TH GPERF "1" "August 2000" "GNU gperf 2.7" FSF .SH NAME gperf \- generate a perfect hash function from a key set .SH SYNOPSIS -.B gperf -[ -.B \-adghijklnoprsStv -] [ -.I keyfile -] +.B gperf +[\fIOPTION\fR]... [\fIINPUT-FILE\fR] .SH DESCRIPTION - -\fIgperf\fP reads a set of ``keys'' from \fIkeyfile\fP (or, by -default, from the standard input) and attempts to find a non-minimal -perfect hashing function that recognizes a member of the key set in -constant, i.e., O(1), time. If such a function is found the program -generates a pair of \fIC\fP source code routines that perform the -hashing and table lookup. All generated code is directed to the -standard output. - -Please refer to the \fIgperf.texi\fP file for more information. -This file is distributed with \fIgperf\fP release. +GNU `gperf' generates perfect hash functions. +.PP +If a long option shows an argument as mandatory, then it is mandatory +for the equivalent short option also. +.SS "Input file interpretation:" +.TP +\fB\-e\fR, \fB\-\-delimiters\fR=\fIDELIMITER\-LIST\fR +Allow user to provide a string containing delimiters +used to separate keywords from their attributes. +Default is ",\en". +.TP +\fB\-t\fR, \fB\-\-struct\-type\fR +Allows the user to include a structured type +declaration for generated code. Any text before %% +is considered part of the type declaration. Key +words and additional fields may follow this, one +group of fields per line. +.SS "Language for the output code:" +.TP +\fB\-L\fR, \fB\-\-language\fR=\fILANGUAGE\-NAME\fR +Generates code in the specified language. Languages +handled are currently C++, ANSI-C, C, and KR-C. The +default is C. +.SS "Details in the output code:" +.TP +\fB\-K\fR, \fB\-\-slot\-name\fR=\fINAME\fR +Select name of the keyword component in the keyword +structure. +.TP +\fB\-F\fR, \fB\-\-initializer\-suffix\fR=\fIINITIALIZERS\fR +Initializers for additional components in the keyword +structure. +.TP +\fB\-H\fR, \fB\-\-hash\-fn\-name\fR=\fINAME\fR +Specify name of generated hash function. Default is +`hash'. +.TP +\fB\-N\fR, \fB\-\-lookup\-fn\-name\fR=\fINAME\fR +Specify name of generated lookup function. Default +name is `in_word_set'. +.TP +\fB\-Z\fR, \fB\-\-class\-name\fR=\fINAME\fR +Specify name of generated C++ class. Default name is +`Perfect_Hash'. +.TP +\fB\-7\fR, \fB\-\-seven\-bit\fR +Assume 7-bit characters. +.TP +\fB\-c\fR, \fB\-\-compare\-strncmp\fR +Generate comparison code using strncmp rather than +strcmp. +.TP +\fB\-C\fR, \fB\-\-readonly\-tables\fR +Make the contents of generated lookup tables +constant, i.e., readonly. +.TP +\fB\-E\fR, \fB\-\-enum\fR +Define constant values using an enum local to the +lookup function rather than with defines. +.TP +\fB\-I\fR, \fB\-\-includes\fR +Include the necessary system include file <string.h> +at the beginning of the code. +.TP +\fB\-G\fR, \fB\-\-global\fR +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). +.TP +\fB\-W\fR, \fB\-\-word\-array\-name\fR=\fINAME\fR +Specify name of word list array. Default name is +`wordlist'. +.TP +\fB\-S\fR, \fB\-\-switch\fR=\fICOUNT\fR +Causes the generated C code to use a switch +statement scheme, rather than an array lookup table. +This can lead to a reduction in both time and space +requirements for some keyfiles. The COUNT argument +determines how many switch statements are generated. +A value of 1 generates 1 switch containing all the +elements, a value of 2 generates 2 tables with 1/2 +the elements in each table, etc. If COUNT is very +large, say 1000000, the generated C code does a +binary search. +.TP +\fB\-T\fR, \fB\-\-omit\-struct\-type\fR +Prevents the transfer of the type declaration to the +output file. Use this option if the type is already +defined elsewhere. +.SS "Algorithm employed by gperf:" +.TP +\fB\-k\fR, \fB\-\-key\-positions\fR=\fIKEYS\fR +Select the key positions used in the hash function. +The allowable choices range between 1-126, inclusive. +The positions are separated by commas, ranges may be +used, and key positions may occur in any order. +Also, the meta-character '*' causes the generated +hash function to consider ALL key positions, and $ +indicates the ``final character'' of a key, e.g., +$,1,2,4,6-10. +.TP +\fB\-l\fR, \fB\-\-compare\-strlen\fR +Compare key lengths before trying a string +comparison. This helps cut down on the number of +string comparisons made during the lookup. +.TP +\fB\-D\fR, \fB\-\-duplicates\fR +Handle keywords that hash to duplicate values. This +is useful for certain highly redundant keyword sets. +.TP +\fB\-f\fR, \fB\-\-fast\fR=\fIITERATIONS\fR +Generate the gen-perf.hash function ``fast''. This +decreases gperf's running time at the cost of +minimizing generated table size. The numeric +argument represents the number of times to iterate +when resolving a collision. `0' means ``iterate by +the number of keywords''. +.TP +\fB\-i\fR, \fB\-\-initial\-asso\fR=\fIN\fR +Provide an initial value for the associate values +array. Default is 0. Setting this value larger helps +inflate the size of the final table. +.TP +\fB\-j\fR, \fB\-\-jump\fR=\fIJUMP\-VALUE\fR +Affects the ``jump value'', i.e., how far to advance +the associated character value upon collisions. Must +be an odd number, default is 5. +.TP +\fB\-n\fR, \fB\-\-no\-strlen\fR +Do not include the length of the keyword when +computing the hash function. +.TP +\fB\-o\fR, \fB\-\-occurrence\-sort\fR +Reorders input keys by frequency of occurrence of +the key sets. This should decrease the search time +dramatically. +.TP +\fB\-r\fR, \fB\-\-random\fR +Utilizes randomness to initialize the associated +values table. +.TP +\fB\-s\fR, \fB\-\-size\-multiple\fR=\fIN\fR +Affects the size of the generated hash table. The +numeric argument N indicates ``how many times larger +or smaller'' the associated value range should be, +in relationship to the number of keys, e.g. a value +of 3 means ``allow the maximum associated value to +be about 3 times larger than the number of input +keys.'' Conversely, a value of \fB\-3\fR means ``make the +maximum associated value about 3 times smaller than +the number of input keys. A larger table should +decrease the time required for an unsuccessful +search, at the expense of extra table space. Default +value is 1. +.SS "Informative output:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print this message. +.TP +\fB\-v\fR, \fB\-\-version\fR +Print the gperf version number. +.TP +\fB\-d\fR, \fB\-\-debug\fR +Enables the debugging option (produces verbose +output to the standard error). +.SH "REPORTING BUGS" +Report bugs to <bug-gnu-utils@gnu.org>. +.SH "SEE ALSO" +The full documentation for +.B gperf +is maintained as a Texinfo manual. If the +.B info +and +.B gperf +programs are properly installed at your site, the command +.IP +.B info gperf +.PP +should give you access to the complete manual. diff --git a/doc/help2man b/doc/help2man new file mode 100755 index 0000000..2c81647 --- /dev/null +++ b/doc/help2man @@ -0,0 +1,513 @@ +#!/usr/bin/perl -w + +# Generate a short man page from --help and --version output. +# Copyright © 1997, 1998, 1999, 2000 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation, +# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# Written by Brendan O'Dea <bod@compusol.com.au> +# Available from ftp://ftp.gnu.org/gnu/help2man/ + +use 5.004; +use strict; +use Getopt::Long; +use Text::Tabs qw(expand); +use POSIX qw(strftime setlocale LC_TIME); + +my $this_program = 'help2man'; +my $this_version = '1.022'; +my $version_info = <<EOT; +GNU $this_program $this_version + +Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc. +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +Written by Brendan O'Dea <bod\@compusol.com.au> +EOT + +my $help_info = <<EOT; +`$this_program' generates a man page out of `--help' and `--version' output. + +Usage: $this_program [OPTION]... EXECUTABLE + + -n, --name=STRING use `STRING' as the description for the NAME paragraph + -s, --section=SECTION use `SECTION' as the section for the man page + -i, --include=FILE include material from `FILE' + -I, --opt-include=FILE include material from `FILE' if it exists + -o, --output=FILE send output to `FILE' + -N, --no-info suppress pointer to Texinfo manual + --help print this help, then exit + --version print version number, then exit + +EXECUTABLE should accept `--help' and `--version' options. + +Report bugs to <bug-help2man\@gnu.org>. +EOT + +my $section = 1; +my ($opt_name, @opt_include, $opt_output, $opt_no_info); + +# Parse options. +Getopt::Long::config('bundling'); +GetOptions ( + 'n|name=s' => \$opt_name, + 's|section=s' => \$section, + 'i|include=s' => sub { push @opt_include, [ pop, 1 ] }, + 'I|opt-include=s' => sub { push @opt_include, [ pop, 0 ] }, + 'o|output=s' => \$opt_output, + 'N|no-info' => \$opt_no_info, + help => sub { print $help_info; exit }, + version => sub { print $version_info; exit }, +) or die $help_info; + +die $help_info unless @ARGV == 1; + +my %include = (); +my %append = (); +my @include = (); # retain order given in include file + +# Provide replacement `quote-regex' operator for pre-5.005. +BEGIN { eval q(sub qr { '' =~ $_[0]; $_[0] }) if $] < 5.005 } + +# Process include file (if given). Format is: +# +# [section name] +# verbatim text +# +# or +# +# /pattern/ +# verbatim text +# + +for (@opt_include) +{ + my ($inc, $required) = @$_; + + next unless -f $inc or $required; + die "$this_program: can't open `$inc' ($!)\n" + unless open INC, $inc; + + my $key; + my $hash = \%include; + + while (<INC>) + { + # [section] + if (/^\[([^]]+)\]/) + { + $key = uc $1; + $key =~ s/^\s+//; + $key =~ s/\s+$//; + $hash = \%include; + push @include, $key unless $include{$key}; + next; + } + + # /pattern/ + if (m!^/(.*)/([ims]*)!) + { + my $pat = $2 ? "(?$2)$1" : $1; + + # Check pattern. + eval { $key = qr($pat) }; + if ($@) + { + $@ =~ s/ at .*? line \d.*//; + die "$inc:$.:$@"; + } + + $hash = \%append; + next; + } + + # Silently ignore anything before the first + # section--allows for comments and revision info. + next unless $key; + + $hash->{$key} ||= ''; + $hash->{$key} .= $_; + } + + close INC; + + die "$this_program: no valid information found in `$inc'\n" + unless $key; +} + +# Compress trailing blank lines. +for my $hash (\(%include, %append)) +{ + for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ } +} + +# Turn off localisation of executable's ouput. +@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3; + +# Turn off localisation of date (for strftime). +setlocale LC_TIME, 'C'; + +# Grab help and version info from executable. +my ($help_text, $version_text) = map { + join '', map { s/ +$//; expand $_ } `$ARGV[0] --$_ 2>/dev/null` + or die "$this_program: can't get `--$_' info from $ARGV[0]\n" +} qw(help version); + +my $date = strftime "%B %Y", localtime; +(my $program = $ARGV[0]) =~ s!.*/!!; +my $package = $program; +my $version; + +if ($opt_output) +{ + unlink $opt_output + or die "$this_program: can't unlink $opt_output ($!)\n" + if -e $opt_output; + + open STDOUT, ">$opt_output" + or die "$this_program: can't create $opt_output ($!)\n"; +} + +# The first line of the --version information is assumed to be in one +# of the following formats: +# +# <version> +# <program> <version> +# {GNU,Free} <program> <version> +# <program> ({GNU,Free} <package>) <version> +# <program> - {GNU,Free} <package> <version> +# +# and seperated from any copyright/author details by a blank line. + +($_, $version_text) = split /\n+/, $version_text, 2; + +if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or + /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/) +{ + $program = $1; + $package = $2; + $version = $3; +} +elsif (/^((?:GNU|Free) +)?(\S+) +(.*)/) +{ + $program = $2; + $package = $1 ? "$1$2" : $2; + $version = $3; +} +else +{ + $version = $_; +} + +$program =~ s!.*/!!; + +# No info for `info' itself. +$opt_no_info = 1 if $program eq 'info'; + +# --name overrides --include contents. +$include{NAME} = "$program \\- $opt_name\n" if $opt_name; + +# Default (useless) NAME paragraph. +$include{NAME} ||= "$program \\- manual page for $program $version\n"; + +# Man pages traditionally have the page title in caps. +my $PROGRAM = uc $program; + +# Extract usage clause(s) [if any] for SYNOPSIS. +if ($help_text =~ s/^Usage:( +(\S+))(.*)((?:\n(?: {6}\1| *or: +\S).*)*)//m) +{ + my @syn = $2 . $3; + + if ($_ = $4) + { + s/^\n//; + for (split /\n/) { s/^ *(or: +)?//; push @syn, $_ } + } + + my $synopsis = ''; + for (@syn) + { + $synopsis .= ".br\n" if $synopsis; + s!^\S*/!!; + s/^(\S+) *//; + $synopsis .= ".B $1\n"; + s/\s+$//; + s/(([][]|\.\.+)+)/\\fR$1\\fI/g; + s/^/\\fI/ unless s/^\\fR//; + $_ .= '\fR'; + s/(\\fI)( *)/$2$1/g; + s/\\fI\\fR//g; + s/^\\fR//; + s/\\fI$//; + s/^\./\\&./; + + $synopsis .= "$_\n"; + } + + $include{SYNOPSIS} ||= $synopsis; +} + +# Process text, initial section is DESCRIPTION. +my $sect = 'DESCRIPTION'; +$_ = "$help_text\n\n$version_text"; + +# Normalise paragraph breaks. +s/^\n+//; +s/\n*$/\n/; +s/\n\n+/\n\n/g; + +# Temporarily exchange leading dots and backslashes for tokens. +s/^\./\x80/mg; +s/\\/\x81/g; + +# Start a new paragraph (if required) for these. +s/([^\n])\n(Report +bugs|Email +bug +reports +to|Written +by)/$1\n\n$2/g; + +sub convert_option; + +while (length) +{ + # Convert some standard paragraph names. + if (s/^(Options|Examples): *\n//) + { + $sect = uc $1; + next; + } + + # Copyright section + if (/^Copyright +[(\xa9]/) + { + $sect = 'COPYRIGHT'; + $include{$sect} ||= ''; + $include{$sect} .= ".PP\n" if $include{$sect}; + + my $copy; + ($copy, $_) = split /\n\n/, $_, 2; + + for ($copy) + { + # Add back newline + s/\n*$/\n/; + + # Convert iso9959-1 copyright symbol or (c) to nroff + # character. + s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg; + + # Insert line breaks before additional copyright messages + # and the disclaimer. + s/(.)\n(Copyright |This +is +free +software)/$1\n.br\n$2/g; + + # Join hyphenated lines. + s/([A-Za-z])-\n */$1/g; + } + + $include{$sect} .= $copy; + $_ ||= ''; + next; + } + + # Catch bug report text. + if (/^(Report +bugs|Email +bug +reports +to) /) + { + $sect = 'REPORTING BUGS'; + } + + # Author section. + elsif (/^Written +by/) + { + $sect = 'AUTHOR'; + } + + # Examples, indicated by an indented leading $, % or > are + # rendered in a constant width font. + if (/^( +)([\$\%>] )\S/) + { + my $indent = $1; + my $prefix = $2; + my $break = '.IP'; + $include{$sect} ||= ''; + while (s/^$indent\Q$prefix\E(\S.*)\n*//) + { + $include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n"; + $break = '.br'; + } + + next; + } + + my $matched = ''; + $include{$sect} ||= ''; + + # Sub-sections have a trailing colon and the second line indented. + if (s/^(\S.*:) *\n / /) + { + $matched .= $& if %append; + $include{$sect} .= qq(.SS "$1"\n); + } + + my $indent = 0; + my $content = ''; + + # Option with description. + if (s/^( {1,10}([+-]\S.*?))(?:( +)|\n( {20,}))(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length ($4 || "$1$3"); + $content = ".TP\n\x82$2\n\x82$5\n"; + unless ($4) + { + # Indent may be different on second line. + $indent = length $& if /^ {20,}/; + } + } + + # Option without description. + elsif (s/^ {1,10}([+-]\S.*)\n//) + { + $matched .= $& if %append; + $content = ".HP\n\x82$1\n"; + $indent = 80; # not continued + } + + # Indented paragraph with tag. + elsif (s/^( +(\S.*?) +)(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length $1; + $content = ".TP\n\x82$2\n\x82$3\n"; + } + + # Indented paragraph. + elsif (s/^( +)(\S.*)\n//) + { + $matched .= $& if %append; + $indent = length $1; + $content = ".IP\n\x82$2\n"; + } + + # Left justified paragraph. + else + { + s/(.*)\n//; + $matched .= $& if %append; + $content = ".PP\n" if $include{$sect}; + $content .= "$1\n"; + } + + # Append continuations. + while (s/^ {$indent}(\S.*)\n//) + { + $matched .= $& if %append; + $content .= "\x82$1\n" + } + + # Move to next paragraph. + s/^\n+//; + + for ($content) + { + # Leading dot protection. + s/\x82\./\x80/g; + s/\x82//g; + + # Convert options. + s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge; + } + + # Check if matched paragraph contains /pat/. + if (%append) + { + for my $pat (keys %append) + { + if ($matched =~ $pat) + { + $content .= ".PP\n" unless $append{$pat} =~ /^\./; + $content .= $append{$pat}; + } + } + } + + $include{$sect} .= $content; +} + +# Refer to the real documentation. +unless ($opt_no_info) +{ + $sect = 'SEE ALSO'; + $include{$sect} ||= ''; + $include{$sect} .= ".PP\n" if $include{$sect}; + $include{$sect} .= <<EOT; +The full documentation for +.B $program +is maintained as a Texinfo manual. If the +.B info +and +.B $program +programs are properly installed at your site, the command +.IP +.B info $program +.PP +should give you access to the complete manual. +EOT +} + +# Output header. +print <<EOT; +.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version. +.TH $PROGRAM "$section" "$date" "$package $version" FSF +EOT + +# Section ordering. +my @pre = qw(NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES); +my @post = ('AUTHOR', 'REPORTING BUGS', 'COPYRIGHT', 'SEE ALSO'); +my $filter = join '|', @pre, @post; + +# Output content. +for (@pre, (grep ! /^($filter)$/o, @include), @post) +{ + if ($include{$_}) + { + my $quote = /\W/ ? '"' : ''; + print ".SH $quote$_$quote\n"; + + for ($include{$_}) + { + # Replace leading dot an backslash tokens. + s/\x80/\\&./g; + s/\x81/\\e/g; + print; + } + } +} + +exit; + +# Convert option dashes to \- to stop nroff from hyphenating 'em, and +# embolden. Option arguments get italicised. +sub convert_option +{ + local $_ = '\fB' . shift; + + s/-/\\-/g; + unless (s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) + { + s/=(.)/\\fR=\\fI$1/; + s/ (.)/ \\fI$1/; + $_ .= '\fR'; + } + + $_; +} |