URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
Compare Revisions
- This comparison shows the changes necessary to convert path
/or1k/tags/start/gdb-5.0/readline/doc
- from Rev 579 to Rev 1765
- ↔ Reverse comparison
Rev 579 → Rev 1765
/texi2html
0,0 → 1,2081
#!/usr/local/bin/perl |
'di '; |
'ig 00 '; |
#+############################################################################## |
# # |
# File: texi2html # |
# # |
# Description: Program to transform most Texinfo documents to HTML # |
# # |
#-############################################################################## |
|
# @(#)texi2html 1.52 01/05/98 Written (mainly) by Lionel Cons, Lionel.Cons@cern.ch |
|
# The man page for this program is included at the end of this file and can be |
# viewed using the command 'nroff -man texi2html'. |
# Please read the copyright at the end of the man page. |
|
#+++############################################################################ |
# # |
# Constants # |
# # |
#---############################################################################ |
|
$DEBUG_TOC = 1; |
$DEBUG_INDEX = 2; |
$DEBUG_BIB = 4; |
$DEBUG_GLOSS = 8; |
$DEBUG_DEF = 16; |
$DEBUG_HTML = 32; |
$DEBUG_USER = 64; |
|
$BIBRE = '\[[\w\/-]+\]'; # RE for a bibliography reference |
$FILERE = '[\/\w.+-]+'; # RE for a file name |
$VARRE = '[^\s\{\}]+'; # RE for a variable name |
$NODERE = '[^@{}:\'`",]+'; # RE for a node name |
$NODESRE = '[^@{}:\'`"]+'; # RE for a list of node names |
$XREFRE = '[^@{}]+'; # RE for a xref (should use NODERE) |
|
$ERROR = "***"; # prefix for errors and warnings |
$THISPROG = "texi2html 1.52"; # program name and version |
$HOMEPAGE = "http://wwwinfo.cern.ch/dis/texi2html/"; # program home page |
$TODAY = &pretty_date; # like "20 September 1993" |
$SPLITTAG = "<!-- SPLIT HERE -->\n"; # tag to know where to split |
$PROTECTTAG = "_ThisIsProtected_"; # tag to recognize protected sections |
$html2_doctype = '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0 Strict Level 2//EN">'; |
|
# |
# language dependent constants |
# |
#$LDC_SEE = 'see'; |
#$LDC_SECTION = 'section'; |
#$LDC_IN = 'in'; |
#$LDC_TOC = 'Table of Contents'; |
#$LDC_GOTO = 'Go to the'; |
#$LDC_FOOT = 'Footnotes'; |
# TODO: @def* shortcuts |
|
# |
# pre-defined indices |
# |
%predefined_index = ( |
'cp', 'c', |
'fn', 'f', |
'vr', 'v', |
'ky', 'k', |
'pg', 'p', |
'tp', 't', |
); |
|
# |
# valid indices |
# |
%valid_index = ( |
'c', 1, |
'f', 1, |
'v', 1, |
'k', 1, |
'p', 1, |
't', 1, |
); |
|
# |
# texinfo section names to level |
# |
%sec2level = ( |
'top', 0, |
'chapter', 1, |
'unnumbered', 1, |
'majorheading', 1, |
'chapheading', 1, |
'appendix', 1, |
'section', 2, |
'unnumberedsec', 2, |
'heading', 2, |
'appendixsec', 2, |
'appendixsection', 2, |
'subsection', 3, |
'unnumberedsubsec', 3, |
'subheading', 3, |
'appendixsubsec', 3, |
'subsubsection', 4, |
'unnumberedsubsubsec', 4, |
'subsubheading', 4, |
'appendixsubsubsec', 4, |
); |
|
# |
# accent map, TeX command to ISO name |
# |
%accent_map = ( |
'"', 'uml', |
'~', 'tilde', |
'^', 'circ', |
'`', 'grave', |
'\'', 'acute', |
); |
|
# |
# texinfo "simple things" (@foo) to HTML ones |
# |
%simple_map = ( |
# cf. makeinfo.c |
"*", "<BR>", # HTML+ |
" ", " ", |
"\n", "\n", |
"|", "", |
# spacing commands |
":", "", |
"!", "!", |
"?", "?", |
".", ".", |
"-", "", |
); |
|
# |
# texinfo "things" (@foo{}) to HTML ones |
# |
%things_map = ( |
'TeX', 'TeX', |
'br', '<P>', # paragraph break |
'bullet', '*', |
'copyright', '(C)', |
'dots', '...', |
'equiv', '==', |
'error', 'error-->', |
'expansion', '==>', |
'minus', '-', |
'point', '-!-', |
'print', '-|', |
'result', '=>', |
'today', $TODAY, |
); |
|
# |
# texinfo styles (@foo{bar}) to HTML ones |
# |
%style_map = ( |
'asis', '', |
'b', 'B', |
'cite', 'CITE', |
'code', 'CODE', |
'ctrl', '&do_ctrl', # special case |
'dfn', 'EM', # DFN tag is illegal in the standard |
'dmn', '', # useless |
'email', '&do_email', # insert a clickable email address |
'emph', 'EM', |
'file', '"TT', # will put quotes, cf. &apply_style |
'i', 'I', |
'kbd', 'KBD', |
'key', 'KBD', |
'math', 'EM', |
'r', '', # unsupported |
'samp', '"SAMP', # will put quotes, cf. &apply_style |
'sc', '&do_sc', # special case |
'strong', 'STRONG', |
't', 'TT', |
'titlefont', '', # useless |
'uref', '&do_uref', # insert a clickable URL |
'url', '&do_url', # insert a clickable URL |
'var', 'VAR', |
'w', '', # unsupported |
); |
|
# |
# texinfo format (@foo/@end foo) to HTML ones |
# |
%format_map = ( |
'display', 'PRE', |
'example', 'PRE', |
'format', 'PRE', |
'lisp', 'PRE', |
'quotation', 'BLOCKQUOTE', |
'smallexample', 'PRE', |
'smalllisp', 'PRE', |
# lists |
'itemize', 'UL', |
'enumerate', 'OL', |
# poorly supported |
'flushleft', 'PRE', |
'flushright', 'PRE', |
); |
|
# |
# texinfo definition shortcuts to real ones |
# |
%def_map = ( |
# basic commands |
'deffn', 0, |
'defvr', 0, |
'deftypefn', 0, |
'deftypevr', 0, |
'defcv', 0, |
'defop', 0, |
'deftp', 0, |
# basic x commands |
'deffnx', 0, |
'defvrx', 0, |
'deftypefnx', 0, |
'deftypevrx', 0, |
'defcvx', 0, |
'defopx', 0, |
'deftpx', 0, |
# shortcuts |
'defun', 'deffn Function', |
'defmac', 'deffn Macro', |
'defspec', 'deffn {Special Form}', |
'defvar', 'defvr Variable', |
'defopt', 'defvr {User Option}', |
'deftypefun', 'deftypefn Function', |
'deftypevar', 'deftypevr Variable', |
'defivar', 'defcv {Instance Variable}', |
'defmethod', 'defop Method', |
# x shortcuts |
'defunx', 'deffnx Function', |
'defmacx', 'deffnx Macro', |
'defspecx', 'deffnx {Special Form}', |
'defvarx', 'defvrx Variable', |
'defoptx', 'defvrx {User Option}', |
'deftypefunx', 'deftypefnx Function', |
'deftypevarx', 'deftypevrx Variable', |
'defivarx', 'defcvx {Instance Variable}', |
'defmethodx', 'defopx Method', |
); |
|
# |
# things to skip |
# |
%to_skip = ( |
# comments |
'c', 1, |
'comment', 1, |
# useless |
'contents', 1, |
'shortcontents', 1, |
'summarycontents', 1, |
'footnotestyle', 1, |
'end ifclear', 1, |
'end ifset', 1, |
'titlepage', 1, |
'end titlepage', 1, |
# unsupported commands (formatting) |
'afourpaper', 1, |
'cropmarks', 1, |
'finalout', 1, |
'headings', 1, |
'need', 1, |
'page', 1, |
'setchapternewpage', 1, |
'everyheading', 1, |
'everyfooting', 1, |
'evenheading', 1, |
'evenfooting', 1, |
'oddheading', 1, |
'oddfooting', 1, |
'smallbook', 1, |
'vskip', 1, |
'filbreak', 1, |
'paragraphindent', 1, |
# unsupported formats |
'cartouche', 1, |
'end cartouche', 1, |
'group', 1, |
'end group', 1, |
); |
|
#+++############################################################################ |
# # |
# Argument parsing, initialisation # |
# # |
#---############################################################################ |
|
%value = (); # hold texinfo variables, see also -D |
|
$use_bibliography = 1; |
$use_acc = 0; |
$debug = 0; |
$doctype = ''; |
$check = 0; |
$expandinfo = 0; |
$use_glossary = 0; |
$invisible_mark = ''; |
$use_iso = 0; |
@include_dirs = (); |
$show_menu = 0; |
$number_sections = 0; |
$split_node = 0; |
$split_chapter = 0; |
$monolithic = 0; |
$verbose = 0; |
$usage = <<EOT; |
This is $THISPROG |
To convert a Texinfo file to HMTL: $0 [options] file |
where options can be: |
-expandinfo : use \@ifinfo sections, not \@iftex |
-glossary : handle a glossary |
-invisible name: use 'name' as an invisible anchor |
-Dname : define name like with \@set |
-I dir : search also for files in 'dir' |
-menu : handle menus |
-monolithic : output only one file including ToC |
-number : number sections |
-split_chapter : split on main sections |
-split_node : split on nodes |
-usage : print usage instructions |
-verbose : verbose output |
To check converted files: $0 -check [-verbose] files |
EOT |
|
while (@ARGV && $ARGV[0] =~ /^-/) { |
$_ = shift(@ARGV); |
if (/^-acc$/) { $use_acc = 1; next; } |
if (/^-d(ebug)?(\d+)?$/) { $debug = $2 || shift(@ARGV); next; } |
if (/^-doctype$/) { $doctype = shift(@ARGV); next; } |
if (/^-c(heck)?$/) { $check = 1; next; } |
if (/^-e(xpandinfo)?$/) { $expandinfo = 1; next; } |
if (/^-g(lossary)?$/) { $use_glossary = 1; next; } |
if (/^-i(nvisible)?$/) { $invisible_mark = shift(@ARGV); next; } |
if (/^-iso$/) { $use_iso = 1; next; } |
if (/^-D(.+)?$/) { $value{$1 || shift(@ARGV)} = 1; next; } |
if (/^-I(.+)?$/) { push(@include_dirs, $1 || shift(@ARGV)); next; } |
if (/^-m(enu)?$/) { $show_menu = 1; next; } |
if (/^-mono(lithic)?$/) { $monolithic = 1; next; } |
if (/^-n(umber)?$/) { $number_sections = 1; next; } |
if (/^-s(plit)?_?(n(ode)?|c(hapter)?)?$/) { |
if ($2 =~ /^n/) { |
$split_node = 1; |
} else { |
$split_chapter = 1; |
} |
next; |
} |
if (/^-v(erbose)?$/) { $verbose = 1; next; } |
die $usage; |
} |
if ($check) { |
die $usage unless @ARGV > 0; |
✓ |
exit; |
} |
|
if (($split_node || $split_chapter) && $monolithic) { |
warn "Can't use -monolithic with -split, -monolithic ignored.\n"; |
$monolithic = 0; |
} |
if ($expandinfo) { |
$to_skip{'ifinfo'}++; |
$to_skip{'end ifinfo'}++; |
} else { |
$to_skip{'iftex'}++; |
$to_skip{'end iftex'}++; |
} |
$invisible_mark = '<IMG SRC="invisible.xbm">' if $invisible_mark eq 'xbm'; |
die $usage unless @ARGV == 1; |
$docu = shift(@ARGV); |
if ($docu =~ /.*\//) { |
chop($docu_dir = $&); |
$docu_name = $'; |
} else { |
$docu_dir = '.'; |
$docu_name = $docu; |
} |
unshift(@include_dirs, $docu_dir); |
$docu_name =~ s/\.te?x(i|info)?$//; # basename of the document |
|
$docu_doc = "$docu_name.html"; # document's contents |
if ($monolithic) { |
$docu_toc = $docu_foot = $docu_doc; |
} else { |
$docu_toc = "${docu_name}_toc.html"; # document's table of contents |
$docu_foot = "${docu_name}_foot.html"; # document's footnotes |
} |
|
# |
# variables |
# |
$value{'html'} = 1; # predefine html (the output format) |
$value{'texi2html'} = '1.52'; # predefine texi2html (the translator) |
# _foo: internal to track @foo |
foreach ('_author', '_title', '_subtitle', |
'_settitle', '_setfilename') { |
$value{$_} = ''; # prevent -w warnings |
} |
%node2sec = (); # node to section name |
%node2href = (); # node to HREF |
%bib2href = (); # bibliography reference to HREF |
%gloss2href = (); # glossary term to HREF |
@sections = (); # list of sections |
%tag2pro = (); # protected sections |
|
# |
# initial indexes |
# |
$bib_num = 0; |
$foot_num = 0; |
$gloss_num = 0; |
$idx_num = 0; |
$sec_num = 0; |
$doc_num = 0; |
$html_num = 0; |
|
# |
# can I use ISO8879 characters? (HTML+) |
# |
if ($use_iso) { |
$things_map{'bullet'} = "•"; |
$things_map{'copyright'} = "©"; |
$things_map{'dots'} = "…"; |
$things_map{'equiv'} = "≡"; |
$things_map{'expansion'} = "→"; |
$things_map{'point'} = "∗"; |
$things_map{'result'} = "⇒"; |
} |
|
# |
# read texi2html extensions (if any) |
# |
$extensions = 'texi2html.ext'; # extensions in working directory |
if (-f $extensions) { |
print "# reading extensions from $extensions\n" if $verbose; |
require($extensions); |
} |
($progdir = $0) =~ s/[^\/]+$//; |
if ($progdir && ($progdir ne './')) { |
$extensions = "${progdir}texi2html.ext"; # extensions in texi2html directory |
if (-f $extensions) { |
print "# reading extensions from $extensions\n" if $verbose; |
require($extensions); |
} |
} |
|
print "# reading from $docu\n" if $verbose; |
|
#+++############################################################################ |
# # |
# Pass 1: read source, handle command, variable, simple substitution # |
# # |
#---############################################################################ |
|
@lines = (); # whole document |
@toc_lines = (); # table of contents |
$toplevel = 0; # top level seen in hierarchy |
$curlevel = 0; # current level in TOC |
$node = ''; # current node name |
$in_table = 0; # am I inside a table |
$table_type = ''; # type of table ('', 'f', 'v', 'multi') |
@tables = (); # nested table support |
$in_bibliography = 0; # am I inside a bibliography |
$in_glossary = 0; # am I inside a glossary |
$in_top = 0; # am I inside the top node |
$in_pre = 0; # am I inside a preformatted section |
$in_list = 0; # am I inside a list |
$in_html = 0; # am I inside an HTML section |
$first_line = 1; # is it the first line |
$dont_html = 0; # don't protect HTML on this line |
$split_num = 0; # split index |
$deferred_ref = ''; # deferred reference for indexes |
@html_stack = (); # HTML elements stack |
$html_element = ''; # current HTML element |
&html_reset; |
|
# build code for simple substitutions |
# the maps used (%simple_map and %things_map) MUST be aware of this |
# watch out for regexps, / and escaped characters! |
$subst_code = ''; |
foreach (keys(%simple_map)) { |
($re = $_) =~ s/(\W)/\\$1/g; # protect regexp chars |
$subst_code .= "s/\\\@$re/$simple_map{$_}/g;\n"; |
} |
foreach (keys(%things_map)) { |
$subst_code .= "s/\\\@$_\\{\\}/$things_map{$_}/g;\n"; |
} |
if ($use_acc) { |
# accentuated characters |
foreach (keys(%accent_map)) { |
if ($_ eq "`") { |
$subst_code .= "s/$;3"; |
} elsif ($_ eq "'") { |
$subst_code .= "s/$;4"; |
} else { |
$subst_code .= "s/\\\@\\$_"; |
} |
$subst_code .= "([aeiou])/&\${1}$accent_map{$_};/gi;\n"; |
} |
} |
eval("sub simple_substitutions { $subst_code }"); |
|
&init_input; |
while ($_ = &next_line) { |
# |
# remove \input on the first lines only |
# |
if ($first_line) { |
next if /^\\input/; |
$first_line = 0; |
} |
# |
# parse texinfo tags |
# |
$tag = ''; |
$end_tag = ''; |
if (/^\@end\s+(\w+)\b/) { |
$end_tag = $1; |
} elsif (/^\@(\w+)\b/) { |
$tag = $1; |
} |
# |
# handle @ifhtml / @end ifhtml |
# |
if ($in_html) { |
if ($end_tag eq 'ifhtml') { |
$in_html = 0; |
} else { |
$tag2pro{$in_html} .= $_; |
} |
next; |
} elsif ($tag eq 'ifhtml') { |
$in_html = $PROTECTTAG . ++$html_num; |
push(@lines, $in_html); |
next; |
} |
# |
# try to skip the line |
# |
if ($end_tag) { |
next if $to_skip{"end $end_tag"}; |
} elsif ($tag) { |
next if $to_skip{$tag}; |
last if $tag eq 'bye'; |
} |
if ($in_top) { |
# parsing the top node |
if ($tag eq 'node' || $tag eq 'include' || $sec2level{$tag}) { |
# no more in top |
$in_top = 0; |
} else { |
# skip it |
next; |
} |
} |
# |
# try to remove inlined comments |
# syntax from tex-mode.el comment-start-skip |
# |
s/((^|[^\@])(\@\@)*)\@c(omment)? .*/$1/; |
# non-@ substitutions cf. texinfmt.el |
unless ($in_pre) { |
s/``/\"/g; |
s/''/\"/g; |
s/([\w ])---([\w ])/$1--$2/g; |
} |
# |
# analyze the tag |
# |
if ($tag) { |
# skip lines |
&skip_until($tag), next if $tag eq 'ignore'; |
if ($expandinfo) { |
&skip_until($tag), next if $tag eq 'iftex'; |
} else { |
&skip_until($tag), next if $tag eq 'ifinfo'; |
} |
&skip_until($tag), next if $tag eq 'tex'; |
# handle special tables |
if ($tag =~ /^(|f|v|multi)table$/) { |
$table_type = $1; |
$tag = 'table'; |
} |
# special cases |
if ($tag eq 'top' || ($tag eq 'node' && /^\@node\s+top\s*,/i)) { |
$in_top = 1; |
@lines = (); # ignore all lines before top (title page garbage) |
next; |
} elsif ($tag eq 'node') { |
$in_top = 0; |
warn "$ERROR Bad node line: $_" unless $_ =~ /^\@node\s$NODESRE$/o; |
$_ = &protect_html($_); # if node contains '&' for instance |
s/^\@node\s+//; |
($node) = split(/,/); |
&normalise_node($node); |
if ($split_node) { |
&next_doc; |
push(@lines, $SPLITTAG) if $split_num++; |
push(@sections, $node); |
} |
next; |
} elsif ($tag eq 'include') { |
if (/^\@include\s+($FILERE)\s*$/o) { |
$file = $1; |
unless (-e $file) { |
foreach $dir (@include_dirs) { |
$file = "$dir/$1"; |
last if -e $file; |
} |
} |
if (-e $file) { |
&open($file); |
print "# including $file\n" if $verbose; |
} else { |
warn "$ERROR Can't find $file, skipping"; |
} |
} else { |
warn "$ERROR Bad include line: $_"; |
} |
next; |
} elsif ($tag eq 'ifclear') { |
if (/^\@ifclear\s+($VARRE)\s*$/o) { |
next unless defined($value{$1}); |
&skip_until($tag); |
} else { |
warn "$ERROR Bad ifclear line: $_"; |
} |
next; |
} elsif ($tag eq 'ifset') { |
if (/^\@ifset\s+($VARRE)\s*$/o) { |
next if defined($value{$1}); |
&skip_until($tag); |
} else { |
warn "$ERROR Bad ifset line: $_"; |
} |
next; |
} elsif ($tag eq 'menu') { |
unless ($show_menu) { |
&skip_until($tag); |
next; |
} |
&html_push_if($tag); |
push(@lines, &html_debug("\n", __LINE__)); |
} elsif ($format_map{$tag}) { |
$in_pre = 1 if $format_map{$tag} eq 'PRE'; |
&html_push_if($format_map{$tag}); |
push(@lines, &html_debug("\n", __LINE__)); |
$in_list++ if $format_map{$tag} eq 'UL' || $format_map{$tag} eq 'OL' ; |
push(@lines, &debug("<$format_map{$tag}>\n", __LINE__)); |
next; |
} elsif ($tag eq 'table') { |
if (/^\@(|f|v|multi)table\s+\@(\w+)/) { |
$in_table = $2; |
unshift(@tables, join($;, $table_type, $in_table)); |
if ($table_type eq "multi") { |
push(@lines, &debug("<TABLE BORDER>\n", __LINE__)); |
&html_push_if('TABLE'); |
} else { |
push(@lines, &debug("<DL COMPACT>\n", __LINE__)); |
&html_push_if('DL'); |
} |
push(@lines, &html_debug("\n", __LINE__)); |
} else { |
warn "$ERROR Bad table line: $_"; |
} |
next; |
} elsif ($tag eq 'synindex' || $tag eq 'syncodeindex') { |
if (/^\@$tag\s+(\w)\w\s+(\w)\w\s*$/) { |
eval("*${1}index = *${2}index"); |
} else { |
warn "$ERROR Bad syn*index line: $_"; |
} |
next; |
} elsif ($tag eq 'sp') { |
push(@lines, &debug("<P>\n", __LINE__)); |
next; |
} elsif ($tag eq 'setref') { |
&protect_html; # if setref contains '&' for instance |
if (/^\@$tag\s*{($NODERE)}\s*$/) { |
$setref = $1; |
$setref =~ s/\s+/ /g; # normalize |
$setref =~ s/ $//; |
$node2sec{$setref} = $name; |
$node2href{$setref} = "$docu_doc#$docid"; |
} else { |
warn "$ERROR Bad setref line: $_"; |
} |
next; |
} elsif ($tag eq 'defindex' || $tag eq 'defcodeindex') { |
if (/^\@$tag\s+(\w\w)\s*$/) { |
$valid_index{$1} = 1; |
} else { |
warn "$ERROR Bad defindex line: $_"; |
} |
next; |
} elsif (defined($def_map{$tag})) { |
if ($def_map{$tag}) { |
s/^\@$tag\s+//; |
$tag = $def_map{$tag}; |
$_ = "\@$tag $_"; |
$tag =~ s/\s.*//; |
} |
} elsif (defined($user_sub{$tag})) { |
s/^\@$tag\s+//; |
$sub = $user_sub{$tag}; |
print "# user $tag = $sub, arg: $_" if $debug & $DEBUG_USER; |
if (defined(&$sub)) { |
chop($_); |
&$sub($_); |
} else { |
warn "$ERROR Bad user sub for $tag: $sub\n"; |
} |
next; |
} |
if (defined($def_map{$tag})) { |
s/^\@$tag\s+//; |
if ($tag =~ /x$/) { |
# extra definition line |
$tag = $`; |
$is_extra = 1; |
} else { |
$is_extra = 0; |
} |
while (/\{([^\{\}]*)\}/) { |
# this is a {} construct |
($before, $contents, $after) = ($`, $1, $'); |
# protect spaces |
$contents =~ s/\s+/$;9/g; |
# restore $_ protecting {} |
$_ = "$before$;7$contents$;8$after"; |
} |
@args = split(/\s+/, &protect_html($_)); |
foreach (@args) { |
s/$;9/ /g; # unprotect spaces |
s/$;7/\{/g; # ... { |
s/$;8/\}/g; # ... } |
} |
$type = shift(@args); |
$type =~ s/^\{(.*)\}$/$1/; |
print "# def ($tag): {$type} ", join(', ', @args), "\n" |
if $debug & $DEBUG_DEF; |
$type .= ':'; # it's nicer like this |
$name = shift(@args); |
$name =~ s/^\{(.*)\}$/$1/; |
if ($is_extra) { |
$_ = &debug("<DT>", __LINE__); |
} else { |
$_ = &debug("<DL>\n<DT>", __LINE__); |
} |
if ($tag eq 'deffn' || $tag eq 'defvr' || $tag eq 'deftp') { |
$_ .= "<U>$type</U> <B>$name</B>"; |
$_ .= " <I>@args</I>" if @args; |
} elsif ($tag eq 'deftypefn' || $tag eq 'deftypevr' |
|| $tag eq 'defcv' || $tag eq 'defop') { |
$ftype = $name; |
$name = shift(@args); |
$name =~ s/^\{(.*)\}$/$1/; |
$_ .= "<U>$type</U> $ftype <B>$name</B>"; |
$_ .= " <I>@args</I>" if @args; |
} else { |
warn "$ERROR Unknown definition type: $tag\n"; |
$_ .= "<U>$type</U> <B>$name</B>"; |
$_ .= " <I>@args</I>" if @args; |
} |
$_ .= &debug("\n<DD>", __LINE__); |
$name = &unprotect_html($name); |
if ($tag eq 'deffn' || $tag eq 'deftypefn') { |
unshift(@input_spool, "\@findex $name\n"); |
} elsif ($tag eq 'defop') { |
unshift(@input_spool, "\@findex $name on $ftype\n"); |
} elsif ($tag eq 'defvr' || $tag eq 'deftypevr' || $tag eq 'defcv') { |
unshift(@input_spool, "\@vindex $name\n"); |
} else { |
unshift(@input_spool, "\@tindex $name\n"); |
} |
$dont_html = 1; |
} |
} elsif ($end_tag) { |
if ($format_map{$end_tag}) { |
$in_pre = 0 if $format_map{$end_tag} eq 'PRE'; |
$in_list-- if $format_map{$end_tag} eq 'UL' || $format_map{$end_tag} eq 'OL' ; |
&html_pop_if('LI', 'P'); |
&html_pop_if(); |
push(@lines, &debug("</$format_map{$end_tag}>\n", __LINE__)); |
push(@lines, &html_debug("\n", __LINE__)); |
} elsif ($end_tag =~ /^(|f|v|multi)table$/) { |
unless (@tables) { |
warn "$ERROR \@end $end_tag without \@*table\n"; |
next; |
} |
($table_type, $in_table) = split($;, shift(@tables)); |
unless ($1 eq $table_type) { |
warn "$ERROR \@end $end_tag without matching \@$end_tag\n"; |
next; |
} |
if ($table_type eq "multi") { |
push(@lines, "</TR></TABLE>\n"); |
&html_pop_if('TR'); |
} else { |
push(@lines, "</DL>\n"); |
&html_pop_if('DD'); |
} |
&html_pop_if(); |
if (@tables) { |
($table_type, $in_table) = split($;, $tables[0]); |
} else { |
$in_table = 0; |
} |
} elsif (defined($def_map{$end_tag})) { |
push(@lines, &debug("</DL>\n", __LINE__)); |
} elsif ($end_tag eq 'menu') { |
&html_pop_if(); |
push(@lines, $_); # must keep it for pass 2 |
} |
next; |
} |
# |
# misc things |
# |
# protect texi and HTML things |
&protect_texi; |
$_ = &protect_html($_) unless $dont_html; |
$dont_html = 0; |
# substitution (unsupported things) |
s/^\@center\s+//g; |
s/^\@exdent\s+//g; |
s/\@noindent\s+//g; |
s/\@refill\s+//g; |
# other substitutions |
&simple_substitutions; |
s/\@value{($VARRE)}/$value{$1}/eg; |
s/\@footnote\{/\@footnote$docu_doc\{/g; # mark footnotes, cf. pass 4 |
# |
# analyze the tag again |
# |
if ($tag) { |
if (defined($sec2level{$tag}) && $sec2level{$tag} > 0) { |
if (/^\@$tag\s+(.+)$/) { |
$name = $1; |
$name =~ s/\s+$//; |
$level = $sec2level{$tag}; |
$name = &update_sec_num($tag, $level) . " $name" |
if $number_sections && $tag !~ /^unnumbered/; |
if ($tag =~ /heading$/) { |
push(@lines, &html_debug("\n", __LINE__)); |
if ($html_element ne 'body') { |
# We are in a nice pickle here. We are trying to get a H? heading |
# even though we are not in the body level. So, we convert it to a |
# nice, bold, line by itself. |
$_ = &debug("\n\n<P><STRONG>$name</STRONG></P>\n\n", __LINE__); |
} else { |
$_ = &debug("<H$level>$name</H$level>\n", __LINE__); |
&html_push_if('body'); |
} |
print "# heading, section $name, level $level\n" |
if $debug & $DEBUG_TOC; |
} else { |
if ($split_chapter) { |
unless ($toplevel) { |
# first time we see a "section" |
unless ($level == 1) { |
warn "$ERROR The first section found is not of level 1: $_"; |
warn "$ERROR I'll split on sections of level $level...\n"; |
} |
$toplevel = $level; |
} |
if ($level == $toplevel) { |
&next_doc; |
push(@lines, $SPLITTAG) if $split_num++; |
push(@sections, $name); |
} |
} |
$sec_num++; |
$docid = "SEC$sec_num"; |
$tocid = "TOC$sec_num"; |
# check biblio and glossary |
$in_bibliography = ($name =~ /^([A-Z]|\d+)?(\.\d+)*\s*bibliography$/i); |
$in_glossary = ($name =~ /^([A-Z]|\d+)?(\.\d+)*\s*glossary$/i); |
# check node |
if ($node) { |
if ($node2sec{$node}) { |
warn "$ERROR Duplicate node found: $node\n"; |
} else { |
$node2sec{$node} = $name; |
$node2href{$node} = "$docu_doc#$docid"; |
print "# node $node, section $name, level $level\n" |
if $debug & $DEBUG_TOC; |
} |
$node = ''; |
} else { |
print "# no node, section $name, level $level\n" |
if $debug & $DEBUG_TOC; |
} |
# update TOC |
while ($level > $curlevel) { |
$curlevel++; |
push(@toc_lines, "<UL>\n"); |
} |
while ($level < $curlevel) { |
$curlevel--; |
push(@toc_lines, "</UL>\n"); |
} |
$_ = "<LI>" . &anchor($tocid, "$docu_doc#$docid", $name, 1); |
push(@toc_lines, &substitute_style($_)); |
# update DOC |
push(@lines, &html_debug("\n", __LINE__)); |
&html_reset; |
$_ = "<H$level>".&anchor($docid, "$docu_toc#$tocid", $name)."</H$level>\n"; |
$_ = &debug($_, __LINE__); |
push(@lines, &html_debug("\n", __LINE__)); |
} |
# update DOC |
foreach $line (split(/\n+/, $_)) { |
push(@lines, "$line\n"); |
} |
next; |
} else { |
warn "$ERROR Bad section line: $_"; |
} |
} else { |
# track variables |
$value{$1} = $2, next if /^\@set\s+($VARRE)\s+(.*)$/o; |
delete $value{$1}, next if /^\@clear\s+($VARRE)\s*$/o; |
# store things |
$value{'_setfilename'} = $1, next if /^\@setfilename\s+(.*)$/; |
$value{'_settitle'} = $1, next if /^\@settitle\s+(.*)$/; |
$value{'_author'} .= "$1\n", next if /^\@author\s+(.*)$/; |
$value{'_subtitle'} .= "$1\n", next if /^\@subtitle\s+(.*)$/; |
$value{'_title'} .= "$1\n", next if /^\@title\s+(.*)$/; |
# index |
if (/^\@(..?)index\s+/) { |
unless ($valid_index{$1}) { |
warn "$ERROR Undefined index command: $_"; |
next; |
} |
$id = 'IDX' . ++$idx_num; |
$index = $1 . 'index'; |
$what = &substitute_style($'); |
$what =~ s/\s+$//; |
print "# found $index for '$what' id $id\n" |
if $debug & $DEBUG_INDEX; |
eval(<<EOC); |
if (defined(\$$index\{\$what\})) { |
\$$index\{\$what\} .= "$;$docu_doc#$id"; |
} else { |
\$$index\{\$what\} = "$docu_doc#$id"; |
} |
EOC |
# |
# dirty hack to see if I can put an invisible anchor... |
# |
if ($html_element eq 'P' || |
$html_element eq 'LI' || |
$html_element eq 'DT' || |
$html_element eq 'DD' || |
$html_element eq 'ADDRESS' || |
$html_element eq 'B' || |
$html_element eq 'BLOCKQUOTE' || |
$html_element eq 'PRE' || |
$html_element eq 'SAMP') { |
push(@lines, &anchor($id, '', $invisible_mark, !$in_pre)); |
} elsif ($html_element eq 'body') { |
push(@lines, &debug("<P>\n", __LINE__)); |
push(@lines, &anchor($id, '', $invisible_mark, !$in_pre)); |
&html_push('P'); |
} elsif ($html_element eq 'DL' || |
$html_element eq 'UL' || |
$html_element eq 'OL' ) { |
$deferred_ref .= &anchor($id, '', $invisible_mark, !$in_pre) . " "; |
} |
next; |
} |
# list item |
if (/^\@itemx?\s+/) { |
$what = $'; |
$what =~ s/\s+$//; |
if ($in_bibliography && $use_bibliography) { |
if ($what =~ /^$BIBRE$/o) { |
$id = 'BIB' . ++$bib_num; |
$bib2href{$what} = "$docu_doc#$id"; |
print "# found bibliography for '$what' id $id\n" |
if $debug & $DEBUG_BIB; |
$what = &anchor($id, '', $what); |
} |
} elsif ($in_glossary && $use_glossary) { |
$id = 'GLOSS' . ++$gloss_num; |
$entry = $what; |
$entry =~ tr/A-Z/a-z/ unless $entry =~ /^[A-Z\s]+$/; |
$gloss2href{$entry} = "$docu_doc#$id"; |
print "# found glossary for '$entry' id $id\n" |
if $debug & $DEBUG_GLOSS; |
$what = &anchor($id, '', $what); |
} |
&html_pop_if('P'); |
if ($html_element eq 'DL' || $html_element eq 'DD') { |
if ($things_map{$in_table} && !$what) { |
# special case to allow @table @bullet for instance |
push(@lines, &debug("<DT>$things_map{$in_table}\n", __LINE__)); |
} else { |
push(@lines, &debug("<DT>\@$in_table\{$what\}\n", __LINE__)); |
} |
push(@lines, "<DD>"); |
&html_push('DD') unless $html_element eq 'DD'; |
if ($table_type) { # add also an index |
unshift(@input_spool, "\@${table_type}index $what\n"); |
} |
} elsif ($html_element eq 'TABLE') { |
push(@lines, &debug("<TR><TD>$what</TD>\n", __LINE__)); |
&html_push('TR'); |
} elsif ($html_element eq 'TR') { |
push(@lines, &debug("</TR>\n", __LINE__)); |
push(@lines, &debug("<TR><TD>$what</TD>\n", __LINE__)); |
} else { |
push(@lines, &debug("<LI>$what\n", __LINE__)); |
&html_push('LI') unless $html_element eq 'LI'; |
} |
push(@lines, &html_debug("\n", __LINE__)); |
if ($deferred_ref) { |
push(@lines, &debug("$deferred_ref\n", __LINE__)); |
$deferred_ref = ''; |
} |
next; |
} elsif (/^\@tab\s+(.*)$/) { |
push(@lines, "<TD>$1</TD>\n"); |
next; |
} |
} |
} |
# paragraph separator |
if ($_ eq "\n") { |
next if $#lines >= 0 && $lines[$#lines] eq "\n"; |
if ($html_element eq 'P') { |
push(@lines, "\n"); |
$_ = &debug("</P>\n", __LINE__); |
&html_pop; |
} |
} elsif ($html_element eq 'body' || $html_element eq 'BLOCKQUOTE') { |
push(@lines, "<P>\n"); |
&html_push('P'); |
$_ = &debug($_, __LINE__); |
} |
# otherwise |
push(@lines, $_); |
} |
|
# finish TOC |
$level = 0; |
while ($level < $curlevel) { |
$curlevel--; |
push(@toc_lines, "</UL>\n"); |
} |
|
print "# end of pass 1\n" if $verbose; |
|
#+++############################################################################ |
# # |
# Pass 2/3: handle style, menu, index, cross-reference # |
# # |
#---############################################################################ |
|
@lines2 = (); # whole document (2nd pass) |
@lines3 = (); # whole document (3rd pass) |
$in_menu = 0; # am I inside a menu |
|
while (@lines) { |
$_ = shift(@lines); |
# |
# special case (protected sections) |
# |
if (/^$PROTECTTAG/o) { |
push(@lines2, $_); |
next; |
} |
# |
# menu |
# |
$in_menu = 1, push(@lines2, &debug("<UL>\n", __LINE__)), next if /^\@menu\b/; |
$in_menu = 0, push(@lines2, &debug("</UL>\n", __LINE__)), next if /^\@end\s+menu\b/; |
if ($in_menu) { |
if (/^\*\s+($NODERE)::/o) { |
$descr = $'; |
chop($descr); |
&menu_entry($1, $1, $descr); |
} elsif (/^\*\s+(.+):\s+([^\t,\.\n]+)[\t,\.\n]/) { |
$descr = $'; |
chop($descr); |
&menu_entry($1, $2, $descr); |
} elsif (/^\*/) { |
warn "$ERROR Bad menu line: $_"; |
} else { # description continued? |
push(@lines2, $_); |
} |
next; |
} |
# |
# printindex |
# |
if (/^\@printindex\s+(\w\w)\b/) { |
local($index, *ary, @keys, $key, $letter, $last_letter, @refs); |
if ($predefined_index{$1}) { |
$index = $predefined_index{$1} . 'index'; |
} else { |
$index = $1 . 'index'; |
} |
eval("*ary = *$index"); |
@keys = keys(%ary); |
foreach $key (@keys) { |
$_ = $key; |
1 while s/<(\w+)>\`(.*)\'<\/\1>/$2/; # remove HTML tags with quotes |
1 while s/<(\w+)>(.*)<\/\1>/$2/; # remove HTML tags |
$_ = &unprotect_html($_); |
&unprotect_texi; |
tr/A-Z/a-z/; # lowercase |
$key2alpha{$key} = $_; |
print "# index $key sorted as $_\n" |
if $key ne $_ && $debug & $DEBUG_INDEX; |
} |
push(@lines2, "Jump to:\n"); |
$last_letter = undef; |
foreach $key (sort byalpha @keys) { |
$letter = substr($key2alpha{$key}, 0, 1); |
$letter = substr($key2alpha{$key}, 0, 2) if $letter eq $;; |
if (!defined($last_letter) || $letter ne $last_letter) { |
push(@lines2, "-\n") if defined($last_letter); |
push(@lines2, "<A HREF=\"#$index\_$letter\">" . &protect_html($letter) . "</A>\n"); |
$last_letter = $letter; |
} |
} |
push(@lines2, "<P>\n"); |
$last_letter = undef; |
foreach $key (sort byalpha @keys) { |
$letter = substr($key2alpha{$key}, 0, 1); |
$letter = substr($key2alpha{$key}, 0, 2) if $letter eq $;; |
if (!defined($last_letter) || $letter ne $last_letter) { |
push(@lines2, "</DIR>\n") if defined($last_letter); |
push(@lines2, "<H2><A NAME=\"$index\_$letter\">" . &protect_html($letter) . "</A></H2>\n"); |
push(@lines2, "<DIR>\n"); |
$last_letter = $letter; |
} |
@refs = (); |
foreach (split(/$;/, $ary{$key})) { |
push(@refs, &anchor('', $_, $key, 0)); |
} |
push(@lines2, "<LI>" . join(", ", @refs) . "\n"); |
} |
push(@lines2, "</DIR>\n") if defined($last_letter); |
next; |
} |
# |
# simple style substitutions |
# |
$_ = &substitute_style($_); |
# |
# xref |
# |
while (/\@(x|px|info|)ref{($XREFRE)(}?)/o) { |
# note: Texinfo may accept other characters |
($type, $nodes, $full) = ($1, $2, $3); |
($before, $after) = ($`, $'); |
if (! $full && $after) { |
warn "$ERROR Bad xref (no ending } on line): $_"; |
$_ = "$before$;0${type}ref\{$nodes$after"; |
next; # while xref |
} |
if ($type eq 'x') { |
$type = 'See '; |
} elsif ($type eq 'px') { |
$type = 'see '; |
} elsif ($type eq 'info') { |
$type = 'See Info'; |
} else { |
$type = ''; |
} |
unless ($full) { |
$next = shift(@lines); |
$next = &substitute_style($next); |
chop($nodes); # remove final newline |
if ($next =~ /\}/) { # split on 2 lines |
$nodes .= " $`"; |
$after = $'; |
} else { |
$nodes .= " $next"; |
$next = shift(@lines); |
$next = &substitute_style($next); |
chop($nodes); |
if ($next =~ /\}/) { # split on 3 lines |
$nodes .= " $`"; |
$after = $'; |
} else { |
warn "$ERROR Bad xref (no ending }): $_"; |
$_ = "$before$;0xref\{$nodes$after"; |
unshift(@lines, $next); |
next; # while xref |
} |
} |
} |
$nodes =~ s/\s+/ /g; # remove useless spaces |
@args = split(/\s*,\s*/, $nodes); |
$node = $args[0]; # the node is always the first arg |
&normalise_node($node); |
$sec = $node2sec{$node}; |
if (@args == 5) { # reference to another manual |
$sec = $args[2] || $node; |
$man = $args[4] || $args[3]; |
$_ = "${before}${type}section `$sec' in \@cite{$man}$after"; |
} elsif ($type =~ /Info/) { # inforef |
warn "$ERROR Wrong number of arguments: $_" unless @args == 3; |
($nn, $_, $in) = @args; |
$_ = "${before}${type} file `$in', node `$nn'$after"; |
} elsif ($sec) { |
$href = $node2href{$node}; |
$_ = "${before}${type}section " . &anchor('', $href, $sec) . $after; |
} else { |
warn "$ERROR Undefined node ($node): $_"; |
$_ = "$before$;0xref{$nodes}$after"; |
} |
} |
# |
# try to guess bibliography references or glossary terms |
# |
unless (/^<H\d><A NAME=\"SEC\d/) { |
if ($use_bibliography) { |
$done = ''; |
while (/$BIBRE/o) { |
($pre, $what, $post) = ($`, $&, $'); |
$href = $bib2href{$what}; |
if (defined($href) && $post !~ /^[^<]*<\/A>/) { |
$done .= $pre . &anchor('', $href, $what); |
} else { |
$done .= "$pre$what"; |
} |
$_ = $post; |
} |
$_ = $done . $_; |
} |
if ($use_glossary) { |
$done = ''; |
while (/\b\w+\b/) { |
($pre, $what, $post) = ($`, $&, $'); |
$entry = $what; |
$entry =~ tr/A-Z/a-z/ unless $entry =~ /^[A-Z\s]+$/; |
$href = $gloss2href{$entry}; |
if (defined($href) && $post !~ /^[^<]*<\/A>/) { |
$done .= $pre . &anchor('', $href, $what); |
} else { |
$done .= "$pre$what"; |
} |
$_ = $post; |
} |
$_ = $done . $_; |
} |
} |
# otherwise |
push(@lines2, $_); |
} |
print "# end of pass 2\n" if $verbose; |
|
# |
# split style substitutions |
# |
while (@lines2) { |
$_ = shift(@lines2); |
# |
# special case (protected sections) |
# |
if (/^$PROTECTTAG/o) { |
push(@lines3, $_); |
next; |
} |
# |
# split style substitutions |
# |
$old = ''; |
while ($old ne $_) { |
$old = $_; |
if (/\@(\w+)\{/) { |
($before, $style, $after) = ($`, $1, $'); |
if (defined($style_map{$style})) { |
$_ = $after; |
$text = ''; |
$after = ''; |
$failed = 1; |
while (@lines2) { |
if (/\}/) { |
$text .= $`; |
$after = $'; |
$failed = 0; |
last; |
} else { |
$text .= $_; |
$_ = shift(@lines2); |
} |
} |
if ($failed) { |
die "* Bad syntax (\@$style) after: $before\n"; |
} else { |
$text = &apply_style($style, $text); |
$_ = "$before$text$after"; |
} |
} |
} |
} |
# otherwise |
push(@lines3, $_); |
} |
print "# end of pass 3\n" if $verbose; |
|
#+++############################################################################ |
# # |
# Pass 4: foot notes, final cleanup # |
# # |
#---############################################################################ |
|
@foot_lines = (); # footnotes |
@doc_lines = (); # final document |
$end_of_para = 0; # true if last line is <P> |
|
while (@lines3) { |
$_ = shift(@lines3); |
# |
# special case (protected sections) |
# |
if (/^$PROTECTTAG/o) { |
push(@doc_lines, $_); |
$end_of_para = 0; |
next; |
} |
# |
# footnotes |
# |
while (/\@footnote([^\{\s]+)\{/) { |
($before, $d, $after) = ($`, $1, $'); |
$_ = $after; |
$text = ''; |
$after = ''; |
$failed = 1; |
while (@lines3) { |
if (/\}/) { |
$text .= $`; |
$after = $'; |
$failed = 0; |
last; |
} else { |
$text .= $_; |
$_ = shift(@lines3); |
} |
} |
if ($failed) { |
die "* Bad syntax (\@footnote) after: $before\n"; |
} else { |
$foot_num++; |
$docid = "DOCF$foot_num"; |
$footid = "FOOT$foot_num"; |
$foot = "($foot_num)"; |
push(@foot_lines, "<H3>" . &anchor($footid, "$d#$docid", $foot) . "</H3>\n"); |
$text = "<P>$text" unless $text =~ /^\s*<P>/; |
push(@foot_lines, "$text\n"); |
$_ = $before . &anchor($docid, "$docu_foot#$footid", $foot) . $after; |
} |
} |
# |
# remove unnecessary <P> |
# |
if (/^\s*<P>\s*$/) { |
next if $end_of_para++; |
} else { |
$end_of_para = 0; |
} |
# otherwise |
push(@doc_lines, $_); |
} |
print "# end of pass 4\n" if $verbose; |
|
#+++############################################################################ |
# # |
# Pass 5: print things # |
# # |
#---############################################################################ |
|
$header = <<EOT; |
<!-- This HTML file has been created by $THISPROG |
from $docu on $TODAY --> |
EOT |
|
$full_title = $value{'_title'} || $value{'_settitle'} || "Untitled Document"; |
$title = $value{'_settitle'} || $full_title; |
$_ = &substitute_style($full_title); |
&unprotect_texi; |
s/\n$//; # rmv last \n (if any) |
$full_title = "<H1>" . join("</H1>\n<H1>", split(/\n/, $_)) . "</H1>\n"; |
|
# |
# print ToC |
# |
if (!$monolithic && @toc_lines) { |
if (open(FILE, "> $docu_toc")) { |
print "# creating $docu_toc...\n" if $verbose; |
&print_toplevel_header("$title - Table of Contents"); |
&print_ruler; |
&print(*toc_lines, FILE); |
&print_toplevel_footer; |
close(FILE); |
} else { |
warn "$ERROR Can't write to $docu_toc: $!\n"; |
} |
} |
|
# |
# print footnotes |
# |
if (!$monolithic && @foot_lines) { |
if (open(FILE, "> $docu_foot")) { |
print "# creating $docu_foot...\n" if $verbose; |
&print_toplevel_header("$title - Footnotes"); |
&print_ruler; |
&print(*foot_lines, FILE); |
&print_toplevel_footer; |
close(FILE); |
} else { |
warn "$ERROR Can't write to $docu_foot: $!\n"; |
} |
} |
|
# |
# print document |
# |
if ($split_chapter || $split_node) { # split |
$doc_num = 0; |
$last_num = scalar(@sections); |
$first_doc = &doc_name(1); |
$last_doc = &doc_name($last_num); |
while (@sections) { |
$section = shift(@sections); |
&next_doc; |
if (open(FILE, "> $docu_doc")) { |
print "# creating $docu_doc...\n" if $verbose; |
&print_header("$title - $section"); |
$prev_doc = ($doc_num == 1 ? undef : &doc_name($doc_num - 1)); |
$next_doc = ($doc_num == $last_num ? undef : &doc_name($doc_num + 1)); |
$navigation = "Go to the "; |
$navigation .= ($prev_doc ? &anchor('', $first_doc, "first") : "first"); |
$navigation .= ", "; |
$navigation .= ($prev_doc ? &anchor('', $prev_doc, "previous") : "previous"); |
$navigation .= ", "; |
$navigation .= ($next_doc ? &anchor('', $next_doc, "next") : "next"); |
$navigation .= ", "; |
$navigation .= ($next_doc ? &anchor('', $last_doc, "last") : "last"); |
$navigation .= " section, " . &anchor('', $docu_toc, "table of contents") . ".\n"; |
print FILE $navigation; |
&print_ruler; |
# find corresponding lines |
@tmp_lines = (); |
while (@doc_lines) { |
$_ = shift(@doc_lines); |
last if ($_ eq $SPLITTAG); |
push(@tmp_lines, $_); |
} |
&print(*tmp_lines, FILE); |
&print_ruler; |
print FILE $navigation; |
&print_footer; |
close(FILE); |
} else { |
warn "$ERROR Can't write to $docu_doc: $!\n"; |
} |
} |
} else { # not split |
if (open(FILE, "> $docu_doc")) { |
print "# creating $docu_doc...\n" if $verbose; |
if ($monolithic || !@toc_lines) { |
&print_toplevel_header($title); |
} else { |
&print_header($title); |
print FILE $full_title; |
} |
if ($monolithic && @toc_lines) { |
&print_ruler; |
print FILE "<H1>Table of Contents</H1>\n"; |
&print(*toc_lines, FILE); |
} |
&print_ruler; |
&print(*doc_lines, FILE); |
if ($monolithic && @foot_lines) { |
&print_ruler; |
print FILE "<H1>Footnotes</H1>\n"; |
&print(*foot_lines, FILE); |
} |
if ($monolithic || !@toc_lines) { |
&print_toplevel_footer; |
} else { |
&print_footer; |
} |
close(FILE); |
} else { |
warn "$ERROR Can't write to $docu_doc: $!\n"; |
} |
} |
|
print "# that's all folks\n" if $verbose; |
|
#+++############################################################################ |
# # |
# Low level functions # |
# # |
#---############################################################################ |
|
sub update_sec_num { |
local($name, $level) = @_; |
|
$level--; # here we start at 0 |
if ($name =~ /^appendix/) { |
# appendix style |
if (defined(@appendix_sec_num)) { |
&incr_sec_num($level, @appendix_sec_num); |
} else { |
@appendix_sec_num = ('A', 0, 0, 0); |
} |
return(join('.', @appendix_sec_num[0..$level])); |
} else { |
# normal style |
if (defined(@normal_sec_num)) { |
&incr_sec_num($level, @normal_sec_num); |
} else { |
@normal_sec_num = (1, 0, 0, 0); |
} |
return(join('.', @normal_sec_num[0..$level])); |
} |
} |
|
sub incr_sec_num { |
local($level, $l); |
$level = shift(@_); |
$_[$level]++; |
foreach $l ($level+1 .. 3) { |
$_[$l] = 0; |
} |
} |
|
sub check { |
local($_, %seen, %context, $before, $match, $after); |
|
while (<>) { |
if (/\@(\*|\.|\:|\@|\{|\})/) { |
$seen{$&}++; |
$context{$&} .= "> $_" if $verbose; |
$_ = "$`XX$'"; |
redo; |
} |
if (/\@(\w+)/) { |
($before, $match, $after) = ($`, $&, $'); |
if ($before =~ /\b[\w-]+$/ && $after =~ /^[\w-.]*\b/) { # e-mail address |
$seen{'e-mail address'}++; |
$context{'e-mail address'} .= "> $_" if $verbose; |
} else { |
$seen{$match}++; |
$context{$match} .= "> $_" if $verbose; |
} |
$match =~ s/^\@/X/; |
$_ = "$before$match$after"; |
redo; |
} |
} |
|
foreach (sort(keys(%seen))) { |
if ($verbose) { |
print "$_\n"; |
print $context{$_}; |
} else { |
print "$_ ($seen{$_})\n"; |
} |
} |
} |
|
sub open { |
local($name) = @_; |
|
++$fh_name; |
if (open($fh_name, $name)) { |
unshift(@fhs, $fh_name); |
} else { |
warn "$ERROR Can't read file $name: $!\n"; |
} |
} |
|
sub init_input { |
@fhs = (); # hold the file handles to read |
@input_spool = (); # spooled lines to read |
$fh_name = 'FH000'; |
&open($docu); |
} |
|
sub next_line { |
local($fh, $line); |
|
if (@input_spool) { |
$line = shift(@input_spool); |
return($line); |
} |
while (@fhs) { |
$fh = $fhs[0]; |
$line = <$fh>; |
return($line) if $line; |
close($fh); |
shift(@fhs); |
} |
return(undef); |
} |
|
# used in pass 1, use &next_line |
sub skip_until { |
local($tag) = @_; |
local($_); |
|
while ($_ = &next_line) { |
return if /^\@end\s+$tag\s*$/; |
} |
die "* Failed to find '$tag' after: " . $lines[$#lines]; |
} |
|
# |
# HTML stacking to have a better HTML output |
# |
|
sub html_reset { |
@html_stack = ('html'); |
$html_element = 'body'; |
} |
|
sub html_push { |
local($what) = @_; |
push(@html_stack, $html_element); |
$html_element = $what; |
} |
|
sub html_push_if { |
local($what) = @_; |
push(@html_stack, $html_element) |
if ($html_element && $html_element ne 'P'); |
$html_element = $what; |
} |
|
sub html_pop { |
$html_element = pop(@html_stack); |
} |
|
sub html_pop_if { |
local($elt); |
|
if (@_) { |
foreach $elt (@_) { |
if ($elt eq $html_element) { |
$html_element = pop(@html_stack) if @html_stack; |
last; |
} |
} |
} else { |
$html_element = pop(@html_stack) if @html_stack; |
} |
} |
|
sub html_debug { |
local($what, $line) = @_; |
return("<!-- $line @html_stack, $html_element -->$what") |
if $debug & $DEBUG_HTML; |
return($what); |
} |
|
# to debug the output... |
sub debug { |
local($what, $line) = @_; |
return("<!-- $line -->$what") |
if $debug & $DEBUG_HTML; |
return($what); |
} |
|
sub normalise_node { |
$_[0] =~ s/\s+/ /g; |
$_[0] =~ s/ $//; |
$_[0] =~ s/^ //; |
} |
|
sub menu_entry { |
local($entry, $node, $descr) = @_; |
local($href); |
|
&normalise_node($node); |
$href = $node2href{$node}; |
if ($href) { |
$descr =~ s/^\s+//; |
$descr = ": $descr" if $descr; |
push(@lines2, "<LI>" . &anchor('', $href, $entry) . "$descr\n"); |
} else { |
warn "$ERROR Undefined node ($node): $_"; |
} |
} |
|
sub do_ctrl { "^$_[0]" } |
|
sub do_email { |
local($addr, $text) = split(/,\s*/, $_[0]); |
|
$text = $addr unless $text; |
&anchor('', "mailto:$addr", $text); |
} |
|
sub do_sc { "\U$_[0]\E" } |
|
sub do_uref { |
local($url, $text) = split(/,\s*/, $_[0]); |
|
$text = $url unless $text; |
&anchor('', $url, $text); |
} |
|
sub do_url { &anchor('', $_[0], $_[0]) } |
|
sub apply_style { |
local($texi_style, $text) = @_; |
local($style); |
|
$style = $style_map{$texi_style}; |
if (defined($style)) { # known style |
if ($style =~ /^\"/) { # add quotes |
$style = $'; |
$text = "\`$text\'"; |
} |
if ($style =~ /^\&/) { # custom |
$style = $'; |
$text = &$style($text); |
} elsif ($style) { # good style |
$text = "<$style>$text</$style>"; |
} else { # no style |
} |
} else { # unknown style |
$text = undef; |
} |
return($text); |
} |
|
# remove Texinfo styles |
sub remove_style { |
local($_) = @_; |
s/\@\w+{([^\{\}]+)}/$1/g; |
return($_); |
} |
|
sub substitute_style { |
local($_) = @_; |
local($changed, $done, $style, $text); |
|
$changed = 1; |
while ($changed) { |
$changed = 0; |
$done = ''; |
while (/\@(\w+){([^\{\}]+)}/) { |
$text = &apply_style($1, $2); |
if ($text) { |
$_ = "$`$text$'"; |
$changed = 1; |
} else { |
$done .= "$`\@$1"; |
$_ = "{$2}$'"; |
} |
} |
$_ = $done . $_; |
} |
return($_); |
} |
|
sub anchor { |
local($name, $href, $text, $newline) = @_; |
local($result); |
|
$result = "<A"; |
$result .= " NAME=\"$name\"" if $name; |
$result .= " HREF=\"$href\"" if $href; |
$result .= ">$text</A>"; |
$result .= "\n" if $newline; |
return($result); |
} |
|
sub pretty_date { |
local(@MoY, $sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst); |
|
@MoY = ('January', 'Febuary', 'March', 'April', 'May', 'June', |
'July', 'August', 'September', 'October', 'November', 'December'); |
($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time); |
$year += ($year < 70) ? 2000 : 1900; |
return("$mday $MoY[$mon] $year"); |
} |
|
sub doc_name { |
local($num) = @_; |
|
return("${docu_name}_$num.html"); |
} |
|
sub next_doc { |
$docu_doc = &doc_name(++$doc_num); |
} |
|
sub print { |
local(*lines, $fh) = @_; |
local($_); |
|
while (@lines) { |
$_ = shift(@lines); |
if (/^$PROTECTTAG/o) { |
$_ = $tag2pro{$_}; |
} else { |
&unprotect_texi; |
} |
print $fh $_; |
} |
} |
|
sub print_ruler { |
print FILE "<P><HR><P>\n"; |
} |
|
sub print_header { |
local($_); |
|
# clean the title |
$_ = &remove_style($_[0]); |
&unprotect_texi; |
# print the header |
if ($doctype eq 'html2') { |
print FILE $html2_doctype; |
} elsif ($doctype) { |
print FILE $doctype; |
} |
print FILE <<EOT; |
<HTML> |
<HEAD> |
$header |
<TITLE>$_</TITLE> |
</HEAD> |
<BODY> |
EOT |
} |
|
sub print_toplevel_header { |
local($_); |
|
&print_header; # pass given arg... |
print FILE $full_title; |
if ($value{'_subtitle'}) { |
$value{'_subtitle'} =~ s/\n+$//; |
foreach (split(/\n/, $value{'_subtitle'})) { |
$_ = &substitute_style($_); |
&unprotect_texi; |
print FILE "<H2>$_</H2>\n"; |
} |
} |
if ($value{'_author'}) { |
$value{'_author'} =~ s/\n+$//; |
foreach (split(/\n/, $value{'_author'})) { |
$_ = &substitute_style($_); |
&unprotect_texi; |
s/[\w.-]+\@[\w.-]+/<A HREF="mailto:$&">$&<\/A>/g; |
print FILE "<ADDRESS>$_</ADDRESS>\n"; |
} |
} |
print FILE "<P>\n"; |
} |
|
sub print_footer { |
print FILE <<EOT; |
</BODY> |
</HTML> |
EOT |
} |
|
sub print_toplevel_footer { |
&print_ruler; |
print FILE <<EOT; |
This document was generated on $TODAY using the |
<A HREF=\"$HOMEPAGE\">texi2html</A> |
translator version 1.52.</P> |
EOT |
&print_footer; |
} |
|
sub protect_texi { |
# protect @ { } ` ' |
s/\@\@/$;0/go; |
s/\@\{/$;1/go; |
s/\@\}/$;2/go; |
s/\@\`/$;3/go; |
s/\@\'/$;4/go; |
} |
|
sub protect_html { |
local($what) = @_; |
# protect & < > |
$what =~ s/\&/\&\#38;/g; |
$what =~ s/\</\&\#60;/g; |
$what =~ s/\>/\&\#62;/g; |
# but recognize some HTML things |
$what =~ s/\&\#60;\/A\&\#62;/<\/A>/g; # </A> |
$what =~ s/\&\#60;A ([^\&]+)\&\#62;/<A $1>/g; # <A [^&]+> |
$what =~ s/\&\#60;IMG ([^\&]+)\&\#62;/<IMG $1>/g; # <IMG [^&]+> |
return($what); |
} |
|
sub unprotect_texi { |
s/$;0/\@/go; |
s/$;1/\{/go; |
s/$;2/\}/go; |
s/$;3/\`/go; |
s/$;4/\'/go; |
} |
|
sub unprotect_html { |
local($what) = @_; |
$what =~ s/\&\#38;/\&/g; |
$what =~ s/\&\#60;/\</g; |
$what =~ s/\&\#62;/\>/g; |
return($what); |
} |
|
sub byalpha { |
$key2alpha{$a} cmp $key2alpha{$b}; |
} |
|
############################################################################## |
|
# These next few lines are legal in both Perl and nroff. |
|
.00 ; # finish .ig |
|
'di \" finish diversion--previous line must be blank |
.nr nl 0-1 \" fake up transition to first page again |
.nr % 0 \" start at page 1 |
'; __END__ ############# From here on it's a standard manual page ############ |
.TH TEXI2HTML 1 "01/05/98" |
.AT 3 |
.SH NAME |
texi2html \- a Texinfo to HTML converter |
.SH SYNOPSIS |
.B texi2html [options] file |
.PP |
.B texi2html -check [-verbose] files |
.SH DESCRIPTION |
.I Texi2html |
converts the given Texinfo file to a set of HTML files. It tries to handle |
most of the Texinfo commands. It creates hypertext links for cross-references, |
footnotes... |
.PP |
It also tries to add links from a reference to its corresponding entry in the |
bibliography (if any). It may also handle a glossary (see the |
.B \-glossary |
option). |
.PP |
.I Texi2html |
creates several files depending on the contents of the Texinfo file and on |
the chosen options (see FILES). |
.PP |
The HTML files created by |
.I texi2html |
are closer to TeX than to Info, that's why |
.I texi2html |
converts @iftex sections and not @ifinfo ones by default. You can reverse |
this with the \-expandinfo option. |
.SH OPTIONS |
.TP 12 |
.B \-check |
Check the given file and give the list of all things that may be Texinfo commands. |
This may be used to check the output of |
.I texi2html |
to find the Texinfo commands that have been left in the HTML file. |
.TP |
.B \-expandinfo |
Expand @ifinfo sections, not @iftex ones. |
.TP |
.B \-glossary |
Use the section named 'Glossary' to build a list of terms and put links in the HTML |
document from each term toward its definition. |
.TP |
.B \-invisible \fIname\fP |
Use \fIname\fP to create invisible destination anchors for index links |
(you can for instance use the invisible.xbm file shipped with this program). |
This is a workaround for a known bug of many WWW browsers, including netscape. |
.TP |
.B \-I \fIdir\fP |
Look also in \fIdir\fP to find included files. |
.TP |
.B \-menu |
Show the Texinfo menus; by default they are ignored. |
.TP |
.B \-monolithic |
Output only one file, including the table of contents and footnotes. |
.TP |
.B \-number |
Number the sections. |
.TP |
.B \-split_chapter |
Split the output into several HTML files (one per main section: |
chapter, appendix...). |
.TP |
.B \-split_node |
Split the output into several HTML files (one per node). |
.TP |
.B \-usage |
Print usage instructions, listing the current available command-line options. |
.TP |
.B \-verbose |
Give a verbose output. Can be used with the |
.B \-check |
option. |
.PP |
.SH FILES |
By default |
.I texi2html |
creates the following files (foo being the name of the Texinfo file): |
.TP 16 |
.B foo_toc.html |
The table of contents. |
.TP |
.B foo.html |
The document's contents. |
.TP |
.B foo_foot.html |
The footnotes (if any). |
.PP |
When used with the |
.B \-split |
option, it creates several files (one per chapter or node), named |
.B foo_n.html |
(n being the indice of the chapter or node), instead of the single |
.B foo.html |
file. |
.PP |
When used with the |
.B \-monolithic |
option, it creates only one file: |
.B foo.html |
.SH VARIABLES |
.I texi2html |
predefines the following variables: \fBhtml\fP, \fBtexi2html\fP. |
.SH ADDITIONAL COMMANDS |
.I texi2html |
implements the following non-Texinfo commands (maybe they are in Texinfo now...): |
.TP 16 |
.B @ifhtml |
This indicates the start of an HTML section, this section will passed through |
without any modification. |
.TP |
.B @end ifhtml |
This indicates the end of an HTML section. |
.SH VERSION |
This is \fItexi2html\fP version 1.52, 01/05/98. |
.PP |
The latest version of \fItexi2html\fP can be found in WWW, cf. URL |
http://wwwinfo.cern.ch/dis/texi2html/ |
.SH AUTHOR |
The main author is Lionel Cons, CERN IT/DIS/OSE, Lionel.Cons@cern.ch. |
Many other people around the net contributed to this program. |
.SH COPYRIGHT |
This program is the intellectual property of the European |
Laboratory for Particle Physics (known as CERN). No guarantee whatsoever is |
provided by CERN. No liability whatsoever is accepted for any loss or damage |
of any kind resulting from any defect or inaccuracy in this information or |
code. |
.PP |
CERN, 1211 Geneva 23, Switzerland |
.SH "SEE ALSO" |
GNU Texinfo Documentation Format, |
HyperText Markup Language (HTML), |
World Wide Web (WWW). |
.SH BUGS |
This program does not understand all Texinfo commands (yet). |
.PP |
TeX specific commands (normally enclosed in @iftex) will be |
passed unmodified. |
.ex |
texi2html
Property changes :
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: Makefile.in
===================================================================
--- Makefile.in (nonexistent)
+++ Makefile.in (revision 1765)
@@ -0,0 +1,138 @@
+# This makefile for Readline library documentation is in -*- text -*- mode.
+# Emacs likes it that way.
+top_srcdir = @top_srcdir@
+srcdir = @srcdir@
+VPATH = .:@srcdir@
+
+prefix = @prefix@
+infodir = @infodir@
+
+mandir = @mandir@
+man3dir = $(mandir)/man3
+
+SHELL = @MAKE_SHELL@
+RM = rm -f
+
+TEXINPUTDIR = $(srcdir)
+
+MAKEINFO = makeinfo
+TEXI2DVI = $(srcdir)/texi2dvi
+TEXI2HTML = $(srcdir)/texi2html
+QUIETPS = #set this to -q to shut up dvips
+DVIPS = dvips -D 300 $(QUIETPS) -o $@ # tricky
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+
+RLSRC = $(srcdir)/rlman.texinfo $(srcdir)/rluser.texinfo \
+ $(srcdir)/rltech.texinfo $(srcdir)/manvers.texinfo
+HISTSRC = $(srcdir)/hist.texinfo $(srcdir)/hsuser.texinfo \
+ $(srcdir)/hstech.texinfo $(srcdir)/manvers.texinfo
+
+# This should be a program that converts troff to an ascii-readable format
+NROFF = groff -Tascii
+
+# This should be a program that converts troff to postscript
+GROFF = groff
+
+DVIOBJ = readline.dvi history.dvi
+INFOOBJ = readline.info history.info
+PSOBJ = readline.ps history.ps
+HTMLOBJ = readline.html history.html
+HTMLTOC = readline_toc.html history_toc.html
+TEXTOBJ = readline.0
+
+INTERMEDIATE_OBJ = rlman.dvi hist.dvi
+
+CREATED_DOCS = $(DVIOBJ) $(INFOOBJ) $(PSOBJ) $(HTMLOBJ) $(HTMLTOC) $(TEXTOBJ)
+
+.SUFFIXES: .0 .3 .ps .txt .dvi
+
+.3.0:
+ $(RM) $@
+ -${NROFF} -man $< > $@
+
+all: info dvi html ps text
+nodvi: info html text
+
+readline.dvi: $(RLSRC)
+ TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rlman.texinfo
+ mv rlman.dvi readline.dvi
+
+readline.info: $(RLSRC)
+ $(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texinfo
+
+history.dvi: ${HISTSRC}
+ TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/hist.texinfo
+ mv hist.dvi history.dvi
+
+history.info: ${HISTSRC}
+ $(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/hist.texinfo
+
+readline.ps: readline.dvi
+ $(RM) $@
+ $(DVIPS) readline.dvi
+
+history.ps: history.dvi
+ $(RM) $@
+ $(DVIPS) history.dvi
+
+readline.html: ${RLSRC}
+ $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rlman.texinfo
+ sed -e 's:rlman.html:readline.html:' rlman.html > readline.html
+ $(RM) rlman.html
+
+history.html: ${HISTSRC}
+ $(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/hist.texinfo
+ sed -e 's:hist.html:history.html:' hist.html > history.html
+ $(RM) hist.html
+
+info: $(INFOOBJ)
+dvi: $(DVIOBJ)
+ps: $(PSOBJ)
+html: $(HTMLOBJ)
+text: $(TEXTOBJ)
+
+readline.0: readline.3
+
+clean:
+ $(RM) *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps *.pgs \
+ *.fns *.kys *.tps *.vrs *.o core
+
+distclean: clean
+ $(RM) $(CREATED_DOCS)
+ $(RM) $(INTERMEDIATE_OBJ)
+ $(RM) Makefile
+
+mostlyclean: clean
+
+maintainer-clean: clean
+ $(RM) $(CREATED_DOCS)
+ $(RM) $(INTERMEDIATE_OBJ)
+ $(RM) Makefile
+
+installdirs: $(top_srcdir)/support/mkdirs
+ -$(SHELL) $(top_srcdir)/support/mkdirs $(infodir) $(man3dir)
+
+install: installdirs
+ if test -f readline.info; then \
+ ${INSTALL_DATA} readline.info $(infodir)/readline.info; \
+ else \
+ ${INSTALL_DATA} $(srcdir)/readline.info $(infodir)/readline.info; \
+ fi
+ if test -f history.info; then \
+ ${INSTALL_DATA} history.info $(infodir)/history.info; \
+ else \
+ ${INSTALL_DATA} $(srcdir)/history.info $(infodir)/history.info; \
+ fi
+ if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \
+ install-info --dir-file=$(infodir)/dir $(infodir)/readline.info ; \
+ install-info --dir-file=$(infodir)/dir $(infodir)/history.info ; \
+ else true; fi
+ -${INSTALL_DATA} $(srcdir)/readline.3 $(man3dir)/readline.3
+
+uninstall:
+ $(RM) $(infodir)/readline.info
+ $(RM) $(infodir)/history.info
+ $(RM) $(man3dir)/readline.3
Index: hist.texinfo
===================================================================
--- hist.texinfo (nonexistent)
+++ hist.texinfo (revision 1765)
@@ -0,0 +1,110 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header (This is for running Texinfo on a region.)
+@setfilename history.info
+@settitle GNU History Library
+@c %**end of header (This is for running Texinfo on a region.)
+
+@setchapternewpage odd
+
+@include manvers.texinfo
+
+@ifinfo
+@dircategory Libraries
+@direntry
+* History: (history). The GNU history library API
+@end direntry
+
+This document describes the GNU History library, a programming tool that
+provides a consistent user interface for recalling lines of previously
+typed input.
+
+Copyright (C) 1988-1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+pare preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU History Library
+@subtitle Edition @value{EDITION}, for @code{History Library} Version @value{VERSION}.
+@subtitle @value{UPDATE-MONTH}
+@author Brian Fox, Free Software Foundation
+@author Chet Ramey, Case Western Reserve University
+
+@page
+This document describes the GNU History library, a programming tool that
+provides a consistent user interface for recalling lines of previously
+typed input.
+
+Published by the Free Software Foundation @*
+675 Massachusetts Avenue, @*
+Cambridge, MA 02139 USA
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
+@end titlepage
+
+@ifinfo
+@node Top
+@top GNU History Library
+
+This document describes the GNU History library, a programming tool that
+provides a consistent user interface for recalling lines of previously
+typed input.
+
+@menu
+* Using History Interactively:: GNU History User's Manual.
+* Programming with GNU History:: GNU History Programmer's Manual.
+* Concept Index:: Index of concepts described in this manual.
+* Function and Variable Index:: Index of externally visible functions
+ and variables.
+@end menu
+@end ifinfo
+
+@syncodeindex fn vr
+
+@include hsuser.texinfo
+@include hstech.texinfo
+
+@node Concept Index
+@appendix Concept Index
+@printindex cp
+
+@node Function and Variable Index
+@appendix Function and Variable Index
+@printindex vr
+
+@contents
+@bye
Index: hsuser.texinfo
===================================================================
--- hsuser.texinfo (nonexistent)
+++ hsuser.texinfo (revision 1765)
@@ -0,0 +1,398 @@
+@ignore
+This file documents the user interface to the GNU History library.
+
+Copyright (C) 1988, 1991, 1996 Free Software Foundation, Inc.
+Authored by Brian Fox and Chet Ramey.
+
+Permission is granted to make and distribute verbatim copies of this manual
+provided the copyright notice and this permission notice are preserved on
+all copies.
+
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+GNU Copyright statement is available to the distributee, and provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ignore
+
+@node Using History Interactively
+@chapter Using History Interactively
+
+@ifset BashFeatures
+This chapter describes how to use the GNU History Library interactively,
+from a user's standpoint. It should be considered a user's guide. For
+information on using the GNU History Library in other programs,
+see the GNU Readline Library Manual.
+@end ifset
+@ifclear BashFeatures
+This chapter describes how to use the GNU History Library interactively,
+from a user's standpoint. It should be considered a user's guide. For
+information on using the GNU History Library in your own programs,
+@pxref{Programming with GNU History}.
+@end ifclear
+
+@ifset BashFeatures
+@menu
+* Bash History Facilities:: How Bash lets you manipulate your command
+ history.
+* Bash History Builtins:: The Bash builtin commands that manipulate
+ the command history.
+* History Interaction:: What it feels like using History as a user.
+@end menu
+@end ifset
+@ifclear BashFeatures
+@menu
+* History Interaction:: What it feels like using History as a user.
+@end menu
+@end ifclear
+
+@ifset BashFeatures
+@node Bash History Facilities
+@section Bash History Facilities
+@cindex command history
+@cindex history list
+
+When the @samp{-o history} option to the @code{set} builtin
+is enabled (@pxref{The Set Builtin}),
+the shell provides access to the @var{command history},
+the list of commands previously typed. The text of the last
+@code{HISTSIZE}
+commands (default 500) is saved in a history list. The shell
+stores each command in the history list prior to parameter and
+variable expansion
+but after history expansion is performed, subject to the
+values of the shell variables
+@code{HISTIGNORE} and @code{HISTCONTROL}.
+When the shell starts up, the history is initialized from the
+file named by the @code{HISTFILE} variable (default @file{~/.bash_history}).
+@code{HISTFILE} is truncated, if necessary, to contain no more than
+the number of lines specified by the value of the @code{HISTFILESIZE}
+variable. When an interactive shell exits, the last
+@code{HISTSIZE} lines are copied from the history list to @code{HISTFILE}.
+If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
+the lines are appended to the history file,
+otherwise the history file is overwritten.
+If @code{HISTFILE}
+is unset, or if the history file is unwritable, the history is
+not saved. After saving the history, the history file is truncated
+to contain no more than @code{$HISTFILESIZE}
+lines. If @code{HISTFILESIZE} is not set, no truncation is performed.
+
+The builtin command @code{fc} may be used to list or edit and re-execute
+a portion of the history list.
+The @code{history} builtin can be used to display or modify the history
+list and manipulate the history file.
+When using the command-line editing, search commands
+are available in each editing mode that provide access to the
+history list.
+
+The shell allows control over which commands are saved on the history
+list. The @code{HISTCONTROL} and @code{HISTIGNORE}
+variables may be set to cause the shell to save only a subset of the
+commands entered.
+The @code{cmdhist}
+shell option, if enabled, causes the shell to attempt to save each
+line of a multi-line command in the same history entry, adding
+semicolons where necessary to preserve syntactic correctness.
+The @code{lithist}
+shell option causes the shell to save the command with embedded newlines
+instead of semicolons.
+@xref{Bash Builtins}, for a description of @code{shopt}.
+
+@node Bash History Builtins
+@section Bash History Builtins
+@cindex history builtins
+
+Bash provides two builtin commands that allow you to manipulate the
+history list and history file.
+
+@table @code
+
+@item fc
+@comment btindex fc
+@example
+@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
+@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
+@end example
+
+Fix Command. In the first form, a range of commands from @var{first} to
+@var{last} is selected from the history list. Both @var{first} and
+@var{last} may be specified as a string (to locate the most recent
+command beginning with that string) or as a number (an index into the
+history list, where a negative number is used as an offset from the
+current command number). If @var{last} is not specified it is set to
+@var{first}. If @var{first} is not specified it is set to the previous
+command for editing and @minus{}16 for listing. If the @samp{-l} flag is
+given, the commands are listed on standard output. The @samp{-n} flag
+suppresses the command numbers when listing. The @samp{-r} flag
+reverses the order of the listing. Otherwise, the editor given by
+@var{ename} is invoked on a file containing those commands. If
+@var{ename} is not given, the value of the following variable expansion
+is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
+value of the @code{FCEDIT} variable if set, or the value of the
+@code{EDITOR} variable if that is set, or @code{vi} if neither is set.
+When editing is complete, the edited commands are echoed and executed.
+
+In the second form, @var{command} is re-executed after each instance
+of @var{pat} in the selected command is replaced by @var{rep}.
+
+A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
+that typing @samp{r cc} runs the last command beginning with @code{cc}
+and typing @samp{r} re-executes the last command (@pxref{Aliases}).
+
+@item history
+@comment btindex history
+@example
+history [-c] [@var{n}]
+history [-anrw] [@var{filename}]
+history -ps @var{arg}
+@end example
+
+Display the history list with line numbers. Lines prefixed with
+with a @samp{*} have been modified. An argument of @var{n} says
+to list only the last @var{n} lines. Options, if supplied, have
+the following meanings:
+
+@table @code
+@item -w
+Write out the current history to the history file.
+
+@item -r
+Read the current history file and append its contents to
+the history list.
+
+@item -a
+Append the new
+history lines (history lines entered since the beginning of the
+current Bash session) to the history file.
+
+@item -n
+Append the history lines not already read from the history file
+to the current history list. These are lines appended to the history
+file since the beginning of the current Bash session.
+
+@item -c
+Clear the history list. This may be combined
+with the other options to replace the history list completely.
+
+@item -s
+The @var{arg}s are added to the end of
+the history list as a single entry.
+
+@item -p
+Perform history substitution on the @var{arg}s and display the result
+on the standard output, without storing the results in the history list.
+@end table
+
+When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
+used, if @var{filename}
+is given, then it is used as the history file. If not, then
+the value of the @code{HISTFILE} variable is used.
+
+@end table
+@end ifset
+
+@node History Interaction
+@section History Expansion
+@cindex history expansion
+
+The History library provides a history expansion feature that is similar
+to the history expansion provided by @code{csh}. This section
+describes the syntax used to manipulate the history information.
+
+History expansions introduce words from the history list into
+the input stream, making it easy to repeat commands, insert the
+arguments to a previous command into the current input line, or
+fix errors in previous commands quickly.
+
+History expansion takes place in two parts. The first is to determine
+which line from the history list should be used during substitution.
+The second is to select portions of that line for inclusion into the
+current one. The line selected from the history is called the
+@dfn{event}, and the portions of that line that are acted upon are
+called @dfn{words}. Various @dfn{modifiers} are available to manipulate
+the selected words. The line is broken into words in the same fashion
+that Bash does, so that several words
+surrounded by quotes are considered one word.
+History expansions are introduced by the appearance of the
+history expansion character, which is @samp{!} by default.
+@ifset BashFeatures
+Only @samp{\} and @samp{'} may be used to escape the history expansion
+character.
+@end ifset
+
+@ifset BashFeatures
+Several shell options settable with the @code{shopt}
+builtin (@pxref{Bash Builtins}) may be used to tailor
+the behavior of history expansion. If the
+@code{histverify} shell option is enabled, and Readline
+is being used, history substitutions are not immediately passed to
+the shell parser.
+Instead, the expanded line is reloaded into the Readline
+editing buffer for further modification.
+If Readline is being used, and the @code{histreedit}
+shell option is enabled, a failed history expansion will be
+reloaded into the Readline editing buffer for correction.
+The @samp{-p} option to the @code{history} builtin command
+may be used to see what a history expansion will do before using it.
+The @samp{-s} option to the @code{history} builtin may be used to
+add commands to the end of the history list without actually executing
+them, so that they are available for subsequent recall.
+This is most useful in conjunction with Readline.
+
+The shell allows control of the various characters used by the
+history expansion mechanism with the @code{histchars} variable.
+@end ifset
+
+@menu
+* Event Designators:: How to specify which history line to use.
+* Word Designators:: Specifying which words are of interest.
+* Modifiers:: Modifying the results of substitution.
+@end menu
+
+@node Event Designators
+@subsection Event Designators
+@cindex event designators
+
+An event designator is a reference to a command line entry in the
+history list.
+@cindex history events
+
+@table @asis
+
+@item @code{!}
+Start a history substitution, except when followed by a space, tab,
+the end of the line, @samp{=} or @samp{(}.
+
+@item @code{!@var{n}}
+Refer to command line @var{n}.
+
+@item @code{!-@var{n}}
+Refer to the command @var{n} lines back.
+
+@item @code{!!}
+Refer to the previous command. This is a synonym for @samp{!-1}.
+
+@item @code{!@var{string}}
+Refer to the most recent command starting with @var{string}.
+
+@item @code{!?@var{string}[?]}
+Refer to the most recent command containing @var{string}. The trailing
+@samp{?} may be omitted if the @var{string} is followed immediately by
+a newline.
+
+@item @code{^@var{string1}^@var{string2}^}
+Quick Substitution. Repeat the last command, replacing @var{string1}
+with @var{string2}. Equivalent to
+@code{!!:s/@var{string1}/@var{string2}/}.
+
+@item @code{!#}
+The entire command line typed so far.
+
+@end table
+
+@node Word Designators
+@subsection Word Designators
+
+Word designators are used to select desired words from the event.
+A @samp{:} separates the event specification from the word designator. It
+may be omitted if the word designator begins with a @samp{^}, @samp{$},
+@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
+of the line, with the first word being denoted by 0 (zero). Words are
+inserted into the current line separated by single spaces.
+
+@table @code
+
+@item 0 (zero)
+The @code{0}th word. For many applications, this is the command word.
+
+@item @var{n}
+The @var{n}th word.
+
+@item ^
+The first argument; that is, word 1.
+
+@item $
+The last argument.
+
+@item %
+The word matched by the most recent @samp{?@var{string}?} search.
+
+@item @var{x}-@var{y}
+A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
+
+@item *
+All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
+It is not an error to use @samp{*} if there is just one word in the event;
+the empty string is returned in that case.
+
+@item @var{x}*
+Abbreviates @samp{@var{x}-$}
+
+@item @var{x}-
+Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
+
+@end table
+
+If a word designator is supplied without an event specification, the
+previous command is used as the event.
+
+@node Modifiers
+@subsection Modifiers
+
+After the optional word designator, you can add a sequence of one or more
+of the following modifiers, each preceded by a @samp{:}.
+
+@table @code
+
+@item h
+Remove a trailing pathname component, leaving only the head.
+
+@item t
+Remove all leading pathname components, leaving the tail.
+
+@item r
+Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
+the basename.
+
+@item e
+Remove all but the trailing suffix.
+
+@item p
+Print the new command but do not execute it.
+
+@ifset BashFeatures
+@item q
+Quote the substituted words, escaping further substitutions.
+
+@item x
+Quote the substituted words as with @samp{q},
+but break into words at spaces, tabs, and newlines.
+@end ifset
+
+@item s/@var{old}/@var{new}/
+Substitute @var{new} for the first occurrence of @var{old} in the
+event line. Any delimiter may be used in place of @samp{/}.
+The delimiter may be quoted in @var{old} and @var{new}
+with a single backslash. If @samp{&} appears in @var{new},
+it is replaced by @var{old}. A single backslash will quote
+the @samp{&}. The final delimiter is optional if it is the last
+character on the input line.
+
+@item &
+Repeat the previous substitution.
+
+@item g
+Cause changes to be applied over the entire event line. Used in
+conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
+or with @samp{&}.
+
+@end table
Index: readline.3
===================================================================
--- readline.3 (nonexistent)
+++ readline.3 (revision 1765)
@@ -0,0 +1,1204 @@
+.\"
+.\" MAN PAGE COMMENTS to
+.\"
+.\" Chet Ramey
+.\" Information Network Services
+.\" Case Western Reserve University
+.\" chet@ins.CWRU.Edu
+.\"
+.\" Last Change: Thu Dec 31 10:16:30 EST 1998
+.\"
+.TH READLINE 3 "1998 Dec 31" GNU
+.\"
+.\" File Name macro. This used to be `.PN', for Path Name,
+.\" but Sun doesn't seem to like that very much.
+.\"
+.de FN
+\fI\|\\$1\|\fP
+..
+.SH NAME
+readline \- get a line from a user with editing
+.SH SYNOPSIS
+.LP
+.nf
+.ft B
+#include
+#include
+#include
+.ft
+.fi
+.LP
+.nf
+.ft B
+char *readline (prompt)
+char *prompt;
+.ft
+.fi
+.SH COPYRIGHT
+.if n Readline is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
+.if t Readline is Copyright \(co 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
+.SH DESCRIPTION
+.LP
+.B readline
+will read a line from the terminal
+and return it, using
+.B prompt
+as a prompt. If
+.B prompt
+is null, no prompt is issued. The line returned is allocated with
+.IR malloc (3),
+so the caller must free it when finished. The line returned
+has the final newline removed, so only the text of the line
+remains.
+.LP
+.B readline
+offers editing capabilities while the user is entering the
+line.
+By default, the line editing commands
+are similar to those of emacs.
+A vi\-style line editing interface is also available.
+.SH RETURN VALUE
+.LP
+.B readline
+returns the text of the line read. A blank line
+returns the empty string. If
+.B EOF
+is encountered while reading a line, and the line is empty,
+.B NULL
+is returned. If an
+.B EOF
+is read with a non\-empty line, it is
+treated as a newline.
+.SH NOTATION
+.LP
+An emacs-style notation is used to denote
+keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
+means Control\-N. Similarly,
+.I meta
+keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
+without a
+.I meta
+key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
+then the
+.I x
+key. This makes ESC the \fImeta prefix\fP.
+The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
+or press the Escape key
+then hold the Control key while pressing the
+.I x
+key.)
+.PP
+Readline commands may be given numeric
+.IR arguments ,
+which normally act as a repeat count. Sometimes, however, it is the
+sign of the argument that is significant. Passing a negative argument
+to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
+causes that command to act in a backward direction. Commands whose
+behavior with arguments deviates from this are noted.
+.PP
+When a command is described as \fIkilling\fP text, the text
+deleted is saved for possible future retrieval
+(\fIyanking\fP). The killed text is saved in a
+\fIkill ring\fP. Consecutive kills cause the text to be
+accumulated into one unit, which can be yanked all at once.
+Commands which do not kill text separate the chunks of text
+on the kill ring.
+.SH INITIALIZATION FILE
+.LP
+Readline is customized by putting commands in an initialization
+file (the \fIinputrc\fP file).
+The name of this file is taken from the value of the
+.B INPUTRC
+environment variable. If that variable is unset, the default is
+.IR ~/.inputrc .
+When a program which uses the readline library starts up, the
+init file is read, and the key bindings and variables are set.
+There are only a few basic constructs allowed in the
+readline init file. Blank lines are ignored.
+Lines beginning with a \fB#\fP are comments.
+Lines beginning with a \fB$\fP indicate conditional constructs.
+Other lines denote key bindings and variable settings.
+Each program using this library may add its own commands
+and bindings.
+.PP
+For example, placing
+.RS
+.PP
+M\-Control\-u: universal\-argument
+.RE
+or
+.RS
+C\-Meta\-u: universal\-argument
+.RE
+into the
+.I inputrc
+would make M\-C\-u execute the readline command
+.IR universal\-argument .
+.PP
+The following symbolic character names are recognized while
+processing key bindings:
+.IR RUBOUT ,
+.IR DEL ,
+.IR ESC ,
+.IR LFD ,
+.IR NEWLINE ,
+.IR RET ,
+.IR RETURN ,
+.IR SPC ,
+.IR SPACE ,
+and
+.IR TAB .
+In addition to command names, readline allows keys to be bound
+to a string that is inserted when the key is pressed (a \fImacro\fP).
+.PP
+.SS Key Bindings
+.PP
+The syntax for controlling key bindings in the
+.I inputrc
+file is simple. All that is required is the name of the
+command or the text of a macro and a key sequence to which
+it should be bound. The name may be specified in one of two ways:
+as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
+prefixes, or as a key sequence.
+When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP,
+.I keyname
+is the name of a key spelled out in English. For example:
+.sp
+.RS
+Control\-u: universal\-argument
+.br
+Meta\-Rubout: backward\-kill\-word
+.br
+Control\-o: ">&output"
+.RE
+.LP
+In the above example,
+.I C\-u
+is bound to the function
+.BR universal\-argument ,
+.I M-DEL
+is bound to the function
+.BR backward\-kill\-word ,
+and
+.I C\-o
+is bound to run the macro
+expressed on the right hand side (that is, to insert the text
+.I >&output
+into the line).
+.PP
+In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
+.B keyseq
+differs from
+.B keyname
+above in that strings denoting
+an entire key sequence may be specified by placing the sequence
+within double quotes. Some GNU Emacs style key escapes can be
+used, as in the following example.
+.sp
+.RS
+"\eC\-u": universal\-argument
+.br
+"\eC\-x\eC\-r": re\-read\-init\-file
+.br
+"\ee[11~": "Function Key 1"
+.RE
+.PP
+In this example,
+.I C-u
+is again bound to the function
+.BR universal\-argument .
+.I "C-x C-r"
+is bound to the function
+.BR re\-read\-init\-file ,
+and
+.I "ESC [ 1 1 ~"
+is bound to insert the text
+.BR "Function Key 1" .
+The full set of GNU Emacs style escape sequences is
+.RS
+.PD 0
+.TP
+.B \eC\-
+control prefix
+.TP
+.B \eM\-
+meta prefix
+.TP
+.B \ee
+an escape character
+.TP
+.B \e\e
+backslash
+.TP
+.B \e"
+literal "
+.TP
+.B \e'
+literal '
+.RE
+.PD
+.PP
+In addition to the GNU Emacs style escape sequences, a second
+set of backslash escapes is available:
+.RS
+.PD 0
+.TP
+.B \ea
+alert (bell)
+.TP
+.B \eb
+backspace
+.TP
+.B \ed
+delete
+.TP
+.B \ef
+form feed
+.TP
+.B \en
+newline
+.TP
+.B \er
+carriage return
+.TP
+.B \et
+horizontal tab
+.TP
+.B \ev
+vertical tab
+.TP
+.B \e\fInnn\fP
+the character whose ASCII code is the octal value \fInnn\fP
+(one to three digits)
+.TP
+.B \ex\fInnn\fP
+the character whose ASCII code is the hexadecimal value \fInnn\fP
+(one to three digits)
+.RE
+.PD
+.PP
+When entering the text of a macro, single or double quotes should
+be used to indicate a macro definition. Unquoted text
+is assumed to be a function name.
+In the macro body, the backslash escapes described above are expanded.
+Backslash will quote any other character in the macro text,
+including " and '.
+.PP
+.B Bash
+allows the current readline key bindings to be displayed or modified
+with the
+.B bind
+builtin command. The editing mode may be switched during interactive
+use by using the
+.B \-o
+option to the
+.B set
+builtin command. Other programs using this library provide
+similar mechanisms. The
+.I inputrc
+file may be edited and re-read if a program does not provide
+any other means to incorporate new bindings.
+.SS Variables
+.PP
+Readline has variables that can be used to further customize its
+behavior. A variable may be set in the
+.I inputrc
+file with a statement of the form
+.RS
+.PP
+\fBset\fP \fIvariable\-name\fP \fIvalue\fP
+.RE
+.PP
+Except where noted, readline variables can take the values
+.B On
+or
+.BR Off .
+The variables and their default values are:
+.PP
+.PD 0
+.TP
+.B bell\-style (audible)
+Controls what happens when readline wants to ring the terminal bell.
+If set to \fBnone\fP, readline never rings the bell. If set to
+\fBvisible\fP, readline uses a visible bell if one is available.
+If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
+.TP
+.B comment\-begin (``#'')
+The string that is inserted in \fBvi\fP mode when the
+.B insert\-comment
+command is executed.
+This command is bound to
+.B M\-#
+in emacs mode and to
+.B #
+in vi command mode.
+.TP
+.B completion\-ignore\-case (Off)
+If set to \fBOn\fP, readline performs filename matching and completion
+in a case\-insensitive fashion.
+.TP
+.B completion\-query\-items (100)
+This determines when the user is queried about viewing
+the number of possible completions
+generated by the \fBpossible\-completions\fP command.
+It may be set to any integer value greater than or equal to
+zero. If the number of possible completions is greater than
+or equal to the value of this variable, the user is asked whether
+or not he wishes to view them; otherwise they are simply listed
+on the terminal.
+.TP
+.B convert\-meta (On)
+If set to \fBOn\fP, readline will convert characters with the
+eighth bit set to an ASCII key sequence
+by stripping the eighth bit and prepending an
+escape character (in effect, using escape as the \fImeta prefix\fP).
+.TP
+.B disable\-completion (Off)
+If set to \fBOn\fP, readline will inhibit word completion. Completion
+characters will be inserted into the line as if they had been
+mapped to \fBself-insert\fP.
+.TP
+.B editing\-mode (emacs)
+Controls whether readline begins with a set of key bindings similar
+to \fIemacs\fP or \fIvi\fP.
+.B editing\-mode
+can be set to either
+.B emacs
+or
+.BR vi .
+.TP
+.B enable\-keypad (Off)
+When set to \fBOn\fP, readline will try to enable the application
+keypad when it is called. Some systems need this to enable the
+arrow keys.
+.TP
+.B expand\-tilde (Off)
+If set to \fBon\fP, tilde expansion is performed when readline
+attempts word completion.
+.TP
+.B horizontal\-scroll\-mode (Off)
+When set to \fBOn\fP, makes readline use a single line for display,
+scrolling the input horizontally on a single screen line when it
+becomes longer than the screen width rather than wrapping to a new line.
+.TP
+.B input\-meta (Off)
+If set to \fBOn\fP, readline will enable eight-bit input (that is,
+it will not strip the high bit from the characters it reads),
+regardless of what the terminal claims it can support. The name
+.B meta\-flag
+is a synonym for this variable.
+.TP
+.B isearch\-terminators (``C\-[C\-J'')
+The string of characters that should terminate an incremental
+search without subsequently executing the character as a command.
+If this variable has not been given a value, the characters
+\fIESC\fP and \fIC\-J\fP will terminate an incremental search.
+.TP
+.B keymap (emacs)
+Set the current readline keymap. The set of legal keymap names is
+\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
+vi-command\fP, and
+.IR vi-insert .
+\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
+equivalent to \fIemacs-standard\fP. The default value is
+.IR emacs ;
+the value of
+.B editing\-mode
+also affects the default keymap.
+.TP
+.B mark\-directories (On)
+If set to \fBOn\fP, complete)
+Move to the end of the input history, i.e., the line currently being
+entered.
+.TP
+.B reverse\-search\-history (C\-r)
+Search backward starting at the current line and moving `up' through
+the history as necessary. This is an incremental search.
+.TP
+.B forward\-search\-history (C\-s)
+Search forward starting at the current line and moving `down' through
+the history as necessary. This is an incremental search.
+.TP
+.B non\-incremental\-reverse\-search\-history (M\-p)
+Search backward through the history starting at the current line
+using a non-incremental search for a string supplied by the user.
+.TP
+.B non\-incremental\-forward\-search\-history (M\-n)
+Search forward through the history using a non-incremental search
+for a string supplied by the user.
+.TP
+.B history\-search\-forward
+Search forward through the history for the string of characters
+between the start of the current line and the current cursor
+position (the \fIpoint\fP).
+This is a non-incremental search.
+.TP
+.B history\-search\-backward
+Search backward through the history for the string of characters
+between the start of the current line and the point.
+This is a non-incremental search.
+.TP
+.B yank\-nth\-arg (M\-C\-y)
+Insert the first argument to the previous command (usually
+the second word on the previous line) at point (the current
+cursor position). With an argument
+.IR n ,
+insert the \fIn\fPth word from the previous command (the words
+in the previous command begin with word 0). A negative argument
+inserts the \fIn\fPth word from the end of the previous command.
+.TP
+.B
+yank\-last\-arg (M\-.\^, M\-_\^)
+Insert the last argument to the previous command (the last word of
+the previous history entry). With an argument,
+behave exactly like \fByank\-nth\-arg\fP.
+Successive calls to \fByank\-last\-arg\fP move back through the history
+list, inserting the last argument of each line in turn.
+.PD
+.SS Commands for Changing Text
+.PP
+.PD 0
+.TP
+.B delete\-char (C\-d)
+Delete the character under the cursor. If point is at the
+beginning of the line, there are no characters in the line, and
+the last character typed was not bound to \fBBdelete\-char\fP, then return
+.SM
+.BR EOF .
+.TP
+.B backward\-delete\-char (Rubout)
+Delete the character behind the cursor. When given a numeric argument,
+save the deleted text on the kill ring.
+.TP
+.B forward\-backward\-delete\-char
+Delete the character under the cursor, unless the cursor is at the
+end of the line, in which case the character behind the cursor is
+deleted. By default, this is not bound to a key.
+.TP
+.B quoted\-insert (C\-q, C\-v)
+Add the next character that you type to the line verbatim. This is
+how to insert characters like \fBC\-q\fP, for example.
+.TP
+.B tab\-insert (M-TAB)
+Insert a tab character.
+.TP
+.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
+Insert the character typed.
+.TP
+.B transpose\-chars (C\-t)
+Drag the character before point forward over the character at point.
+Point moves forward as well. If point is at the end of the line, then
+transpose the two characters before point. Negative arguments don't work.
+.TP
+.B transpose\-words (M\-t)
+Drag the word behind the cursor past the word in front of the cursor
+moving the cursor over that word as well.
+.TP
+.B upcase\-word (M\-u)
+Uppercase the current (or following) word. With a negative argument,
+uppercase the previous word, but do not move point.
+.TP
+.B downcase\-word (M\-l)
+Lowercase the current (or following) word. With a negative argument,
+lowercase the previous word, but do not move point.
+.TP
+.B capitalize\-word (M\-c)
+Capitalize the current (or following) word. With a negative argument,
+capitalize the previous word, but do not move point.
+.PD
+.SS Killing and Yanking
+.PP
+.PD 0
+.TP
+.B kill\-line (C\-k)
+Kill the text from the current cursor position to the end of the line.
+.TP
+.B backward\-kill\-line (C\-x Rubout)
+Kill backward to the beginning of the line.
+.TP
+.B unix\-line\-discard (C\-u)
+Kill backward from point to the beginning of the line.
+The killed text is saved on the kill-ring.
+.\" There is no real difference between this and backward-kill-line
+.TP
+.B kill\-whole\-line
+Kill all characters on the current line, no matter where the
+cursor is.
+.TP
+.B kill\-word (M\-d)
+Kill from the cursor to the end of the current word, or if between
+words, to the end of the next word. Word boundaries are the same as
+those used by \fBforward\-word\fP.
+.TP
+.B backward\-kill\-word (M\-Rubout)
+Kill the word behind the cursor. Word boundaries are the same as
+those used by \fBbackward\-word\fP.
+.TP
+.B unix\-word\-rubout (C\-w)
+Kill the word behind the cursor, using white space as a word boundary.
+The word boundaries are different from
+.BR backward\-kill\-word .
+.TP
+.B delete\-horizontal\-space (M\-\e)
+Delete all spaces and tabs around point.
+.TP
+.B kill\-region
+Kill the text between the point and \fImark\fP (saved cursor position).
+This text is referred to as the \fIregion\fP.
+.TP
+.B copy\-region\-as\-kill
+Copy the text in the region to the kill buffer.
+.TP
+.B copy\-backward\-word
+Copy the word before point to the kill buffer.
+The word boundaries are the same as \fBbackward\-word\fP.
+.TP
+.B copy\-forward\-word
+Copy the word following point to the kill buffer.
+The word boundaries are the same as \fBforward\-word\fP.
+.TP
+.B yank (C\-y)
+Yank the top of the kill ring into the buffer at the cursor.
+.TP
+.B yank\-pop (M\-y)
+Rotate the kill ring, and yank the new top. Only works following
+.B yank
+or
+.BR yank\-pop .
+.PD
+.SS Numeric Arguments
+.PP
+.PD 0
+.TP
+.B digit\-argument (M\-0, M\-1, ..., M\-\-)
+Add this digit to the argument already accumulating, or start a new
+argument. M\-\- starts a negative argument.
+.TP
+.B universal\-argument
+This is another way to specify an argument.
+If this command is followed by one or more digits, optionally with a
+leading minus sign, those digits define the argument.
+If the command is followed by digits, executing
+.B universal\-argument
+again ends the numeric argument, but is otherwise ignored.
+As a special case, if this command is immediately followed by a
+character that is neither a digit or minus sign, the argument count
+for the next command is multiplied by four.
+The argument count is initially one, so executing this function the
+first time makes the argument count four, a second time makes the
+argument count sixteen, and so on.
+.PD
+.SS Completing
+.PP
+.PD 0
+.TP
+.B complete (TAB)
+Attempt to perform completion on the text before point.
+The actual completion performed is application-specific.
+.BR Bash ,
+for instance, attempts completion treating the text as a variable
+(if the text begins with \fB$\fP), username (if the text begins with
+\fB~\fP), hostname (if the text begins with \fB@\fP), or
+command (including aliases and functions) in turn. If none
+of these produces a match, filename completion is attempted.
+.BR Gdb ,
+on the other hand,
+allows completion of program functions and variables, and
+only attempts filename completion under certain circumstances.
+.TP
+.B possible\-completions (M\-?)
+List the possible completions of the text before point.
+.TP
+.B insert\-completions (M\-*)
+Insert all completions of the text before point
+that would have been generated by
+\fBpossible\-completions\fP.
+.TP
+.B menu\-complete
+Similar to \fBcomplete\fP, but replaces the word to be completed
+with a single match from the list of possible completions.
+Repeated execution of \fBmenu\-complete\fP steps through the list
+of possible completions, inserting each match in turn.
+At the end of the list of completions, the bell is rung and the
+original text is restored.
+An argument of \fIn\fP moves \fIn\fP positions forward in the list
+of matches; a negative argument may be used to move backward
+through the list.
+This command is intended to be bound to \fBTAB\fP, but is unbound
+by default.
+.TP
+.B delete\-char\-or\-list
+Deletes the character under the cursor if not at the beginning or
+end of the line (like \fBdelete-char\fP).
+If at the end of the line, behaves identically to
+\fBpossible-completions\fP.
+This command is unbound by default.
+.PD
+.SS Keyboard Macros
+.PP
+.PD 0
+.TP
+.B start\-kbd\-macro (C\-x (\^)
+Begin saving the characters typed into the current keyboard macro.
+.TP
+.B end\-kbd\-macro (C\-x )\^)
+Stop saving the characters typed into the current keyboard macro
+and store the definition.
+.TP
+.B call\-last\-kbd\-macro (C\-x e)
+Re-execute the last keyboard macro defined, by making the characters
+in the macro appear as if typed at the keyboard.
+.PD
+.SS Miscellaneous
+.PP
+.PD 0
+.TP
+.B re\-read\-init\-file (C\-x C\-r)
+Read in the contents of the \fIinputrc\fP file, and incorporate
+any bindings or variable assignments found there.
+.TP
+.B abort (C\-g)
+Abort the current editing command and
+ring the terminal's bell (subject to the setting of
+.BR bell\-style ).
+.TP
+.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
+If the metafied character \fIx\fP is lowercase, run the command
+that is bound to the corresponding uppercase character.
+.TP
+.B prefix\-meta (ESC)
+Metafy the next character typed.
+.SM
+.B ESC
+.B f
+is equivalent to
+.BR Meta\-f .
+.TP
+.B undo (C\-_, C\-x C\-u)
+Incremental undo, separately remembered for each line.
+.TP
+.B revert\-line (M\-r)
+Undo all changes made to this line. This is like executing the
+.B undo
+command enough times to return the line to its initial state.
+.TP
+.B tilde\-expand (M\-&)
+Perform tilde expansion on the current word.
+.TP
+.B set\-mark (C\-@, M-)
+Set the mark to the current point. If a
+numeric argument is supplied, the mark is set to that position.
+.TP
+.B exchange\-point\-and\-mark (C\-x C\-x)
+Swap the point with the mark. The current cursor position is set to
+the saved position, and the old cursor position is saved as the mark.
+.TP
+.B character\-search (C\-])
+A character is read and point is moved to the next occurrence of that
+character. A negative count searches for previous occurrences.
+.TP
+.B character\-search\-backward (M\-C\-])
+A character is read and point is moved to the previous occurrence of that
+character. A negative count searches for subsequent occurrences.
+.TP
+.B insert\-comment (M\-#)
+The value of the readline
+.B comment\-begin
+variable is inserted at the beginning of the current line, and the line
+is accepted as if a newline had been typed. This makes the current line
+a shell comment.
+.TP
+.B dump\-functions
+Print all of the functions and their key bindings to the
+readline output stream. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B dump\-variables
+Print all of the settable variables and their values to the
+readline output stream. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B dump\-macros
+Print all of the readline key sequences bound to macros and the
+strings they ouput. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an \fIinputrc\fP file.
+.TP
+.B emacs\-editing\-mode (C\-e)
+When in
+.B vi
+editing mode, this causes a switch to
+.B emacs
+editing mode.
+.TP
+.B vi\-editing\-mode (M\-C\-j)
+When in
+.B emacs
+editing mode, this causes a switch to
+.B vi
+editing mode.
+.PD
+.SH DEFAULT KEY BINDINGS
+.LP
+The following is a list of the default emacs and vi bindings.
+Characters with the 8th bit set are written as M\-, and
+are referred to as
+.I metafied
+characters.
+The printable ASCII characters not mentioned in the list of emacs
+standard bindings are bound to the
+.I self\-insert
+function, which just inserts the given character into the input line.
+In vi insertion mode, all characters not specifically mentioned are
+bound to
+.IR self\-insert .
+Characters assigned to signal generation by
+.IR stty (1)
+or the terminal driver, such as C-Z or C-C,
+retain that function.
+Upper and lower case
+.I metafied
+characters are bound to the same function in the emacs mode
+meta keymap.
+The remaining characters are unbound, which causes readline
+to ring the bell (subject to the setting of the
+.B bell\-style
+variable).
+.SS Emacs Mode
+.RS +.6i
+.nf
+.ta 2.5i
+.sp
+Emacs Standard bindings
+.sp
+"C-@" set-mark
+"C-A" beginning-of-line
+"C-B" backward-char
+"C-D" delete-char
+"C-E" end-of-line
+"C-F" forward-char
+"C-G" abort
+"C-H" backward-delete-char
+"C-I" complete
+"C-J" accept-line
+"C-K" kill-line
+"C-L" clear-screen
+"C-M" accept-line
+"C-N" next-history
+"C-P" previous-history
+"C-Q" quoted-insert
+"C-R" reverse-search-history
+"C-S" forward-search-history
+"C-T" transpose-chars
+"C-U" unix-line-discard
+"C-V" quoted-insert
+"C-W" unix-word-rubout
+"C-Y" yank
+"C-]" character-search
+"C-_" undo
+"\^ " to "/" self-insert
+"0" to "9" self-insert
+":" to "~" self-insert
+"C-?" backward-delete-char
+.PP
+Emacs Meta bindings
+.sp
+"M-C-G" abort
+"M-C-H" backward-kill-word
+"M-C-I" tab-insert
+"M-C-J" vi-editing-mode
+"M-C-M" vi-editing-mode
+"M-C-R" revert-line
+"M-C-Y" yank-nth-arg
+"M-C-[" complete
+"M-C-]" character-search-backward
+"M-space" set-mark
+"M-#" insert-comment
+"M-&" tilde-expand
+"M-*" insert-completions
+"M--" digit-argument
+"M-." yank-last-arg
+"M-0" digit-argument
+"M-1" digit-argument
+"M-2" digit-argument
+"M-3" digit-argument
+"M-4" digit-argument
+"M-5" digit-argument
+"M-6" digit-argument
+"M-7" digit-argument
+"M-8" digit-argument
+"M-9" digit-argument
+"M-<" beginning-of-history
+"M-=" possible-completions
+"M->" end-of-history
+"M-?" possible-completions
+"M-B" backward-word
+"M-C" capitalize-word
+"M-D" kill-word
+"M-F" forward-word
+"M-L" downcase-word
+"M-N" non-incremental-forward-search-history
+"M-P" non-incremental-reverse-search-history
+"M-R" revert-line
+"M-T" transpose-words
+"M-U" upcase-word
+"M-Y" yank-pop
+"M-\e" delete-horizontal-space
+"M-~" tilde-expand
+"M-C-?" backward-delete-word
+"M-_" yank-last-arg
+.PP
+Emacs Control-X bindings
+.sp
+"C-XC-G" abort
+"C-XC-R" re-read-init-file
+"C-XC-U" undo
+"C-XC-X" exchange-point-and-mark
+"C-X(" start-kbd-macro
+"C-X)" end-kbd-macro
+"C-XE" call-last-kbd-macro
+"C-XC-?" backward-kill-line
+.sp
+.RE
+.SS VI Mode bindings
+.RS +.6i
+.nf
+.ta 2.5i
+.sp
+.PP
+VI Insert Mode functions
+.sp
+"C-D" vi-eof-maybe
+"C-H" backward-delete-char
+"C-I" complete
+"C-J" accept-line
+"C-M" accept-line
+"C-R" reverse-search-history
+"C-S" forward-search-history
+"C-T" transpose-chars
+"C-U" unix-line-discard
+"C-V" quoted-insert
+"C-W" unix-word-rubout
+"C-Y" yank
+"C-[" vi-movement-mode
+"C-_" undo
+"\^ " to "~" self-insert
+"C-?" backward-delete-char
+.PP
+VI Command Mode functions
+.sp
+"C-D" vi-eof-maybe
+"C-E" emacs-editing-mode
+"C-G" abort
+"C-H" backward-char
+"C-J" accept-line
+"C-K" kill-line
+"C-L" clear-screen
+"C-M" accept-line
+"C-N" next-history
+"C-P" previous-history
+"C-Q" quoted-insert
+"C-R" reverse-search-history
+"C-S" forward-search-history
+"C-T" transpose-chars
+"C-U" unix-line-discard
+"C-V" quoted-insert
+"C-W" unix-word-rubout
+"C-Y" yank
+"\^ " forward-char
+"#" insert-comment
+"$" end-of-line
+"%" vi-match
+"&" vi-tilde-expand
+"*" vi-complete
+"+" next-history
+"," vi-char-search
+"-" previous-history
+"." vi-redo
+"/" vi-search
+"0" beginning-of-line
+"1" to "9" vi-arg-digit
+";" vi-char-search
+"=" vi-complete
+"?" vi-search
+"A" vi-append-eol
+"B" vi-prev-word
+"C" vi-change-to
+"D" vi-delete-to
+"E" vi-end-word
+"F" vi-char-search
+"G" vi-fetch-history
+"I" vi-insert-beg
+"N" vi-search-again
+"P" vi-put
+"R" vi-replace
+"S" vi-subst
+"T" vi-char-search
+"U" revert-line
+"W" vi-next-word
+"X" backward-delete-char
+"Y" vi-yank-to
+"\e" vi-complete
+"^" vi-first-print
+"_" vi-yank-arg
+"`" vi-goto-mark
+"a" vi-append-mode
+"b" vi-prev-word
+"c" vi-change-to
+"d" vi-delete-to
+"e" vi-end-word
+"f" vi-char-search
+"h" backward-char
+"i" vi-insertion-mode
+"j" next-history
+"k" prev-history
+"l" forward-char
+"m" vi-set-mark
+"n" vi-search-again
+"p" vi-put
+"r" vi-change-char
+"s" vi-subst
+"t" vi-char-search
+"u" undo
+"w" vi-next-word
+"x" vi-delete
+"y" vi-yank-to
+"|" vi-column
+"~" vi-change-case
+.RE
+.SH "SEE ALSO"
+.PD 0
+.TP
+\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
+.TP
+\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
+.TP
+\fIbash\fP(1)
+.PD
+.SH FILES
+.PD 0
+.TP
+.FN ~/.inputrc
+Individual \fBreadline\fP initialization file
+.PD
+.SH AUTHORS
+Brian Fox, Free Software Foundation (primary author)
+.br
+bfox@ai.MIT.Edu
+.PP
+Chet Ramey, Case Western Reserve University
+.br
+chet@ins.CWRU.Edu
+.SH BUG REPORTS
+If you find a bug in
+.B readline,
+you should report it. But first, you should
+make sure that it really is a bug, and that it appears in the latest
+version of the
+.B readline
+library that you have.
+.PP
+Once you have determined that a bug actually exists, mail a
+bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
+If you have a fix, you are welcome to mail that
+as well! Suggestions and `philosophical' bug reports may be mailed
+to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
+newsgroup
+.BR gnu.bash.bug .
+.PP
+Comments and bug reports concerning
+this manual page should be directed to
+.IR chet@ins.CWRU.Edu .
+.SH BUGS
+.PP
+It's too big and too slow.
Index: rlman.texinfo
===================================================================
--- rlman.texinfo (nonexistent)
+++ rlman.texinfo (revision 1765)
@@ -0,0 +1,108 @@
+\input texinfo @c -*-texinfo-*-
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename readline.info
+@settitle GNU Readline Library
+@comment %**end of header (This is for running Texinfo on a region.)
+@synindex vr fn
+@setchapternewpage odd
+
+@include manvers.texinfo
+
+@ifinfo
+@dircategory Libraries
+@direntry
+* Readline: (readline). The GNU readline library API
+@end direntry
+
+This document describes the GNU Readline Library, a utility which aids
+in the consistency of user interface across discrete programs that need
+to provide a command line interface.
+
+Copyright (C) 1988-1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+pare preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU Readline Library
+@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}.
+@subtitle @value{UPDATE-MONTH}
+@author Brian Fox, Free Software Foundation
+@author Chet Ramey, Case Western Reserve University
+
+@page
+This document describes the GNU Readline Library, a utility which aids
+in the consistency of user interface across discrete programs that need
+to provide a command line interface.
+
+Published by the Free Software Foundation @*
+675 Massachusetts Avenue, @*
+Cambridge, MA 02139 USA
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
+@end titlepage
+
+@ifinfo
+@node Top
+@top GNU Readline Library
+
+This document describes the GNU Readline Library, a utility which aids
+in the consistency of user interface across discrete programs that need
+to provide a command line interface.
+
+@menu
+* Command Line Editing:: GNU Readline User's Manual.
+* Programming with GNU Readline:: GNU Readline Programmer's Manual.
+* Concept Index:: Index of concepts described in this manual.
+* Function and Variable Index:: Index of externally visible functions
+ and variables.
+@end menu
+@end ifinfo
+
+@include rluser.texinfo
+@include rltech.texinfo
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@node Function and Variable Index
+@unnumbered Function and Variable Index
+@printindex fn
+
+@contents
+@bye
Index: manvers.texinfo
===================================================================
--- manvers.texinfo (nonexistent)
+++ manvers.texinfo (revision 1765)
@@ -0,0 +1,6 @@
+@set EDITION 4.0
+@set VERSION 4.0
+@set UPDATED 31 December 1998
+@set UPDATE-MONTH December 1998
+
+@set LASTCHANGE Thu Dec 31 10:17:05 EST 1998
Index: ChangeLog
===================================================================
--- ChangeLog (nonexistent)
+++ ChangeLog (revision 1765)
@@ -0,0 +1,53 @@
+Tue Apr 18 15:43:52 2000 Andrew Cagney
+
+ * readline.0: Delete. Generated by Makefile, deleted by distclean
+ rule.
+
+Tue Mar 28 16:06:22 2000 Andrew Cagney
+
+ * inc-hist.texinfo, rluser.texinfo: Revert change Fri Mar 24
+ 18:04:32 2000 Andrew Cagney .
+ Unconditionally provide @chapter and @node.
+
+Fri Mar 24 18:04:32 2000 Andrew Cagney
+
+ * inc-hist.texinfo: When GDBN omit the chapter/node.
+ * rluser.texinfo (Command Line Editing): Ditto.
+
+1999-08-10 Elena Zannoni
+
+ * hsuser.texinfo (Bash History Builtins): Comment out btindex
+ commands.
+
+ * inc-hist.texinfo: New file. Same as hsuser.texinfo, but w/o
+ cross reference to GNU History Manual.
+
+Tue Dec 22 10:07:58 1998 Elena Zannoni
+
+ * hsuser.texinfo (Bash History Builtins): comment out btindex
+ commands.
+
+ * Import of Readline 2.2.1.
+
+ New files: readline.0, readline.3, texi2dvi, texi2html.
+
+1998-12-17 Felix Lee
+
+ * inc-hist.texi: @node line "Using History" was wrong.
+
+Thu Jul 9 17:03:26 1998 Edith Epstein
+
+ * inc-hist.texi: one line change.
+
+Wed Sep 20 12:57:29 1995 Ian Lance Taylor
+
+ * Makefile.in (maintainer-clean): New synonym for realclean.
+
+Tue Feb 2 11:40:04 1993 Roland H. Pesch (pesch@fowanton.cygnus.com)
+
+ * Makefile.in: configurable (and useable) Makefile template
+ * Makefile: removed, replaced with configurable Makefile.in
+ * texindex.c texinfo.tex: remove, replacing w/refs to tools
+ elsewhere in distribution tree
+ * configure.in: pro forma configure stub
+ * ChangeLog: new file
Index: rluser.texinfo
===================================================================
--- rluser.texinfo (nonexistent)
+++ rluser.texinfo (revision 1765)
@@ -0,0 +1,1287 @@
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename rluser.info
+@comment %**end of header (This is for running Texinfo on a region.)
+@setchapternewpage odd
+
+@ignore
+This file documents the end user interface to the GNU command line
+editing features. It is to be an appendix to manuals for programs which
+use these features. There is a document entitled "readline.texinfo"
+which contains both end-user and programmer documentation for the GNU
+Readline Library.
+
+Copyright (C) 1988, 1991, 1993, 1996 Free Software Foundation, Inc.
+
+Authored by Brian Fox and Chet Ramey.
+
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+Permission is granted to make and distribute verbatim copies of this manual
+provided the copyright notice and this permission notice are preserved on
+all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+GNU Copyright statement is available to the distributee, and provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ignore
+
+@comment If you are including this manual as an appendix, then set the
+@comment variable readline-appendix.
+
+@node Command Line Editing
+@chapter Command Line Editing
+
+This chapter describes the basic features of the @sc{GNU}
+command line editing interface.
+
+@menu
+* Introduction and Notation:: Notation used in this text.
+* Readline Interaction:: The minimum set of commands for editing a line.
+* Readline Init File:: Customizing Readline from a user's view.
+* Bindable Readline Commands:: A description of most of the Readline commands
+ available for binding
+* Readline vi Mode:: A short description of how to make Readline
+ behave like the vi editor.
+@end menu
+
+@node Introduction and Notation
+@section Introduction to Line Editing
+
+The following paragraphs describe the notation used to represent
+keystrokes.
+
+The text @key{C-k} is read as `Control-K' and describes the character
+produced when the @key{k} key is pressed while the Control key
+is depressed.
+
+The text @key{M-k} is read as `Meta-K' and describes the character
+produced when the meta key (if you have one) is depressed, and the @key{k}
+key is pressed. If you do not have a meta key, the identical keystroke
+can be generated by typing @key{ESC} @i{first}, and then typing @key{k}.
+Either process is known as @dfn{metafying} the @key{k} key.
+
+The text @key{M-C-k} is read as `Meta-Control-k' and describes the
+character produced by @dfn{metafying} @key{C-k}.
+
+In addition, several keys have their own names. Specifically,
+@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
+stand for themselves when seen in this text, or in an init file
+(@pxref{Readline Init File}).
+
+@node Readline Interaction
+@section Readline Interaction
+@cindex interaction, readline
+
+Often during an interactive session you type in a long line of text,
+only to notice that the first word on the line is misspelled. The
+Readline library gives you a set of commands for manipulating the text
+as you type it in, allowing you to just fix your typo, and not forcing
+you to retype the majority of the line. Using these editing commands,
+you move the cursor to the place that needs correction, and delete or
+insert the text of the corrections. Then, when you are satisfied with
+the line, you simply press @key{RETURN}. You do not have to be at the
+end of the line to press @key{RETURN}; the entire line is accepted
+regardless of the location of the cursor within the line.
+
+@menu
+* Readline Bare Essentials:: The least you need to know about Readline.
+* Readline Movement Commands:: Moving about the input line.
+* Readline Killing Commands:: How to delete text, and how to get it back!
+* Readline Arguments:: Giving numeric arguments to commands.
+* Searching:: Searching through previous lines.
+@end menu
+
+@node Readline Bare Essentials
+@subsection Readline Bare Essentials
+@cindex notation, readline
+@cindex command editing
+@cindex editing command lines
+
+In order to enter characters into the line, simply type them. The typed
+character appears where the cursor was, and then the cursor moves one
+space to the right. If you mistype a character, you can use your
+erase character to back up and delete the mistyped character.
+
+Sometimes you may miss typing a character that you wanted to type, and
+not notice your error until you have typed several other characters. In
+that case, you can type @key{C-b} to move the cursor to the left, and then
+correct your mistake. Afterwards, you can move the cursor to the right
+with @key{C-f}.
+
+When you add text in the middle of a line, you will notice that characters
+to the right of the cursor are `pushed over' to make room for the text
+that you have inserted. Likewise, when you delete text behind the cursor,
+characters to the right of the cursor are `pulled back' to fill in the
+blank space created by the removal of the text. A list of the basic bare
+essentials for editing the text of an input line follows.
+
+@table @asis
+@item @key{C-b}
+Move back one character.
+@item @key{C-f}
+Move forward one character.
+@item @key{DEL}
+Delete the character to the left of the cursor.
+@item @key{C-d}
+Delete the character underneath the cursor.
+@item @w{Printing characters}
+Insert the character into the line at the cursor.
+@item @key{C-_}
+Undo the last editing command. You can undo all the way back to an
+empty line.
+@end table
+
+@node Readline Movement Commands
+@subsection Readline Movement Commands
+
+
+The above table describes the most basic possible keystrokes that you need
+in order to do editing of the input line. For your convenience, many
+other commands have been added in addition to @key{C-b}, @key{C-f},
+@key{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
+about the line.
+
+@table @key
+@item C-a
+Move to the start of the line.
+@item C-e
+Move to the end of the line.
+@item M-f
+Move forward a word, where a word is composed of letters and digits.
+@item M-b
+Move backward a word.
+@item C-l
+Clear the screen, reprinting the current line at the top.
+@end table
+
+Notice how @key{C-f} moves forward a character, while @key{M-f} moves
+forward a word. It is a loose convention that control keystrokes
+operate on characters while meta keystrokes operate on words.
+
+@node Readline Killing Commands
+@subsection Readline Killing Commands
+
+@cindex killing text
+@cindex yanking text
+
+@dfn{Killing} text means to delete the text from the line, but to save
+it away for later use, usually by @dfn{yanking} (re-inserting)
+it back into the line.
+If the description for a command says that it `kills' text, then you can
+be sure that you can get the text back in a different (or the same)
+place later.
+
+When you use a kill command, the text is saved in a @dfn{kill-ring}.
+Any number of consecutive kills save all of the killed text together, so
+that when you yank it back, you get it all. The kill
+ring is not line specific; the text that you killed on a previously
+typed line is available to be yanked back later, when you are typing
+another line.
+@cindex kill ring
+
+Here is the list of commands for killing text.
+
+@table @key
+@item C-k
+Kill the text from the current cursor position to the end of the line.
+
+@item M-d
+Kill from the cursor to the end of the current word, or if between
+words, to the end of the next word.
+
+@item M-DEL
+Kill from the cursor the start of the previous word, or if between
+words, to the start of the previous word.
+
+@item C-w
+Kill from the cursor to the previous whitespace. This is different than
+@key{M-DEL} because the word boundaries differ.
+
+@end table
+
+Here is how to @dfn{yank} the text back into the line. Yanking
+means to copy the most-recently-killed text from the kill buffer.
+
+@table @key
+@item C-y
+Yank the most recently killed text back into the buffer at the cursor.
+
+@item M-y
+Rotate the kill-ring, and yank the new top. You can only do this if
+the prior command is @key{C-y} or @key{M-y}.
+@end table
+
+@node Readline Arguments
+@subsection Readline Arguments
+
+You can pass numeric arguments to Readline commands. Sometimes the
+argument acts as a repeat count, other times it is the @i{sign} of the
+argument that is significant. If you pass a negative argument to a
+command which normally acts in a forward direction, that command will
+act in a backward direction. For example, to kill text back to the
+start of the line, you might type @samp{M-- C-k}.
+
+The general way to pass numeric arguments to a command is to type meta
+digits before the command. If the first `digit' typed is a minus
+sign (@key{-}), then the sign of the argument will be negative. Once
+you have typed one meta digit to get the argument started, you can type
+the remainder of the digits, and then the command. For example, to give
+the @key{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}.
+
+@node Searching
+@subsection Searching for Commands in the History
+
+Readline provides commands for searching through the command history
+@ifset BashFeatures
+(@pxref{Bash History Facilities})
+@end ifset
+for lines containing a specified string.
+There are two search modes: @var{incremental} and @var{non-incremental}.
+
+Incremental searches begin before the user has finished typing the
+search string.
+As each character of the search string is typed, Readline displays
+the next entry from the history matching the string typed so far.
+An incremental search requires only as many characters as needed to
+find the desired history entry.
+The characters present in the value of the @var{isearch-terminators} variable
+are used to terminate an incremental search.
+If that variable has not been assigned a value, the @key{ESC} and
+@key{C-J} characters will terminate an incremental search.
+@key{C-g} will abort an incremental search and restore the original line.
+When the search is terminated, the history entry containing the
+search string becomes the current line.
+To find other matching entries in the history list, type @key{C-s} or
+@key{C-r} as appropriate.
+This will search backward or forward in the history for the next
+entry matching the search string typed so far.
+Any other key sequence bound to a Readline command will terminate
+the search and execute that command.
+For instance, a @key{RET} will terminate the search and accept
+the line, thereby executing the command from the history list.
+
+Non-incremental searches read the entire search string before starting
+to search for matching history lines. The search string may be
+typed by the user or be part of the contents of the current line.
+
+@node Readline Init File
+@section Readline Init File
+@cindex initialization file, readline
+
+Although the Readline library comes with a set of @code{emacs}-like
+keybindings installed by default, it is possible to use a different set
+of keybindings.
+Any user can customize programs that use Readline by putting
+commands in an @dfn{inputrc} file in his home directory.
+The name of this
+@ifset BashFeatures
+file is taken from the value of the shell variable @code{INPUTRC}. If
+@end ifset
+@ifclear BashFeatures
+file is taken from the value of the environment variable @code{INPUTRC}. If
+@end ifclear
+that variable is unset, the default is @file{~/.inputrc}.
+
+When a program which uses the Readline library starts up, the
+init file is read, and the key bindings are set.
+
+In addition, the @code{C-x C-r} command re-reads this init file, thus
+incorporating any changes that you might have made to it.
+
+@menu
+* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
+
+* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
+
+* Sample Init File:: An example inputrc file.
+@end menu
+
+@node Readline Init File Syntax
+@subsection Readline Init File Syntax
+
+There are only a few basic constructs allowed in the
+Readline init file. Blank lines are ignored.
+Lines beginning with a @samp{#} are comments.
+Lines beginning with a @samp{$} indicate conditional
+constructs (@pxref{Conditional Init Constructs}). Other lines
+denote variable settings and key bindings.
+
+@table @asis
+@item Variable Settings
+You can modify the run-time behavior of Readline by
+altering the values of variables in Readline
+using the @code{set} command within the init file. Here is how to
+change from the default Emacs-like key binding to use
+@code{vi} line editing commands:
+
+@example
+set editing-mode vi
+@end example
+
+A great deal of run-time behavior is changeable with the following
+variables.
+
+@table @code
+
+@item bell-style
+@vindex bell-style
+Controls what happens when Readline wants to ring the terminal bell.
+If set to @samp{none}, Readline never rings the bell. If set to
+@samp{visible}, Readline uses a visible bell if one is available.
+If set to @samp{audible} (the default), Readline attempts to ring
+the terminal's bell.
+
+@item comment-begin
+@vindex comment-begin
+The string to insert at the beginning of the line when the
+@code{insert-comment} command is executed. The default value
+is @code{"#"}.
+
+@item completion-ignore-case
+If set to @samp{on}, Readline performs filename matching and completion
+in a case-insensitive fashion.
+The default value is @samp{off}.
+
+@item completion-query-items
+@vindex completion-query-items
+The number of possible completions that determines when the user is
+asked whether he wants to see the list of possibilities. If the
+number of possible completions is greater than this value,
+Readline will ask the user whether or not he wishes to view
+them; otherwise, they are simply listed. The default limit is
+@code{100}.
+
+@item convert-meta
+@vindex convert-meta
+If set to @samp{on}, Readline will convert characters with the
+eighth bit set to an ASCII key sequence by stripping the eighth
+bit and prepending an @key{ESC} character, converting them to a
+meta-prefixed key sequence. The default value is @samp{on}.
+
+@item disable-completion
+@vindex disable-completion
+If set to @samp{On}, Readline will inhibit word completion.
+Completion characters will be inserted into the line as if they had
+been mapped to @code{self-insert}. The default is @samp{off}.
+
+@item editing-mode
+@vindex editing-mode
+The @code{editing-mode} variable controls which default set of
+key bindings is used. By default, Readline starts up in Emacs editing
+mode, where the keystrokes are most similar to Emacs. This variable can be
+set to either @samp{emacs} or @samp{vi}.
+
+@item enable-keypad
+@vindex enable-keypad
+When set to @samp{on}, Readline will try to enable the application
+keypad when it is called. Some systems need this to enable the
+arrow keys. The default is @samp{off}.
+
+@item expand-tilde
+@vindex expand-tilde
+If set to @samp{on}, tilde expansion is performed when Readline
+attempts word completion. The default is @samp{off}.
+
+@item horizontal-scroll-mode
+@vindex horizontal-scroll-mode
+This variable can be set to either @samp{on} or @samp{off}. Setting it
+to @samp{on} means that the text of the lines being edited will scroll
+horizontally on a single screen line when they are longer than the width
+of the screen, instead of wrapping onto a new screen line. By default,
+this variable is set to @samp{off}.
+
+@item input-meta
+@vindex input-meta
+@vindex meta-flag
+If set to @samp{on}, Readline will enable eight-bit input (it
+will not strip the eighth bit from the characters it reads),
+regardless of what the terminal claims it can support. The
+default value is @samp{off}. The name @code{meta-flag} is a
+synonym for this variable.
+
+@item isearch-terminators
+@vindex isearch-terminators
+The string of characters that should terminate an incremental search without
+subsequently executing the character as a command (@pxref{Searching}).
+If this variable has not been given a value, the characters @key{ESC} and
+@key{C-J} will terminate an incremental search.
+
+@item keymap
+@vindex keymap
+Sets Readline's idea of the current keymap for key binding commands.
+Acceptable @code{keymap} names are
+@code{emacs},
+@code{emacs-standard},
+@code{emacs-meta},
+@code{emacs-ctlx},
+@code{vi},
+@code{vi-command}, and
+@code{vi-insert}.
+@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
+equivalent to @code{emacs-standard}. The default value is @code{emacs}.
+The value of the @code{editing-mode} variable also affects the
+default keymap.
+
+@item mark-directories
+If set to @samp{on}, completed directory names have a slash
+appended. The default is @samp{on}.
+
+@item mark-modified-lines
+@vindex mark-modified-lines
+This variable, when set to @samp{on}, causes Readline to display an
+asterisk (@samp{*}) at the start of history lines which have been modified.
+This variable is @samp{off} by default.
+
+@item output-meta
+@vindex output-meta
+If set to @samp{on}, Readline will display characters with the
+eighth bit set directly rather than as a meta-prefixed escape
+sequence. The default is @samp{off}.
+
+@item print-completions-horizontally
+If set to @samp{on}, Readline will display completions with matches
+sorted horizontally in alphabetical order, rather than down the screen.
+The default is @samp{off}.
+
+@item show-all-if-ambiguous
+@vindex show-all-if-ambiguous
+This alters the default behavior of the completion functions. If
+set to @samp{on},
+words which have more than one possible completion cause the
+matches to be listed immediately instead of ringing the bell.
+The default value is @samp{off}.
+
+@item visible-stats
+@vindex visible-stats
+If set to @samp{on}, a character denoting a file's type
+is appended to the filename when listing possible
+completions. The default is @samp{off}.
+
+@end table
+
+@item Key Bindings
+The syntax for controlling key bindings in the init file is
+simple. First you have to know the name of the command that you
+want to change. The following sections contain tables of the command
+name, the default keybinding, if any, and a short description of what
+the command does.
+
+Once you know the name of the command, simply place the name of the key
+you wish to bind the command to, a colon, and then the name of the
+command on a line in the init file. The name of the key
+can be expressed in different ways, depending on which is most
+comfortable for you.
+
+@table @asis
+@item @w{@var{keyname}: @var{function-name} or @var{macro}}
+@var{keyname} is the name of a key spelled out in English. For example:
+@example
+Control-u: universal-argument
+Meta-Rubout: backward-kill-word
+Control-o: "> output"
+@end example
+
+In the above example, @key{C-u} is bound to the function
+@code{universal-argument}, and @key{C-o} is bound to run the macro
+expressed on the right hand side (that is, to insert the text
+@samp{> output} into the line).
+
+@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
+@var{keyseq} differs from @var{keyname} above in that strings
+denoting an entire key sequence can be specified, by placing
+the key sequence in double quotes. Some GNU Emacs style key
+escapes can be used, as in the following example, but the
+special character names are not recognized.
+
+@example
+"\C-u": universal-argument
+"\C-x\C-r": re-read-init-file
+"\e[11~": "Function Key 1"
+@end example
+
+In the above example, @key{C-u} is bound to the function
+@code{universal-argument} (just as it was in the first example),
+@samp{@key{C-x} @key{C-r}} is bound to the function @code{re-read-init-file},
+and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
+the text @samp{Function Key 1}.
+
+@end table
+
+The following GNU Emacs style escape sequences are available when
+specifying key sequences:
+
+@table @code
+@item @kbd{\C-}
+control prefix
+@item @kbd{\M-}
+meta prefix
+@item @kbd{\e}
+an escape character
+@item @kbd{\\}
+backslash
+@item @kbd{\"}
+@key{"}
+@item @kbd{\'}
+@key{'}
+@end table
+
+In addition to the GNU Emacs style escape sequences, a second
+set of backslash escapes is available:
+
+@table @code
+@item \a
+alert (bell)
+@item \b
+backspace
+@item \d
+delete
+@item \f
+form feed
+@item \n
+newline
+@item \r
+carriage return
+@item \t
+horizontal tab
+@item \v
+vertical tab
+@item \@var{nnn}
+the character whose ASCII code is the octal value @var{nnn}
+(one to three digits)
+@item \x@var{nnn}
+the character whose ASCII code is the hexadecimal value @var{nnn}
+(one to three digits)
+@end table
+
+When entering the text of a macro, single or double quotes must
+be used to indicate a macro definition.
+Unquoted text is assumed to be a function name.
+In the macro body, the backslash escapes described above are expanded.
+Backslash will quote any other character in the macro text,
+including @samp{"} and @samp{'}.
+For example, the following binding will make @samp{C-x \}
+insert a single @samp{\} into the line:
+@example
+"\C-x\\": "\\"
+@end example
+
+@end table
+
+@node Conditional Init Constructs
+@subsection Conditional Init Constructs
+
+Readline implements a facility similar in spirit to the conditional
+compilation features of the C preprocessor which allows key
+bindings and variable settings to be performed as the result
+of tests. There are four parser directives used.
+
+@table @code
+@item $if
+The @code{$if} construct allows bindings to be made based on the
+editing mode, the terminal being used, or the application using
+Readline. The text of the test extends to the end of the line;
+no characters are required to isolate it.
+
+@table @code
+@item mode
+The @code{mode=} form of the @code{$if} directive is used to test
+whether Readline is in @code{emacs} or @code{vi} mode.
+This may be used in conjunction
+with the @samp{set keymap} command, for instance, to set bindings in
+the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
+Readline is starting out in @code{emacs} mode.
+
+@item term
+The @code{term=} form may be used to include terminal-specific
+key bindings, perhaps to bind the key sequences output by the
+terminal's function keys. The word on the right side of the
+@samp{=} is tested against both the full name of the terminal and
+the portion of the terminal name before the first @samp{-}. This
+allows @code{sun} to match both @code{sun} and @code{sun-cmd},
+for instance.
+
+@item application
+The @var{application} construct is used to include
+application-specific settings. Each program using the Readline
+library sets the @var{application name}, and you can test for it.
+This could be used to bind key sequences to functions useful for
+a specific program. For instance, the following command adds a
+key sequence that quotes the current or previous word in Bash:
+@example
+$if Bash
+# Quote the current or previous word
+"\C-xq": "\eb\"\ef\""
+$endif
+@end example
+@end table
+
+@item $endif
+This command, as seen in the previous example, terminates an
+@code{$if} command.
+
+@item $else
+Commands in this branch of the @code{$if} directive are executed if
+the test fails.
+
+@item $include
+This directive takes a single filename as an argument and reads commands
+and bindings from that file.
+@example
+$include /etc/inputrc
+@end example
+@end table
+
+@node Sample Init File
+@subsection Sample Init File
+
+Here is an example of an inputrc file. This illustrates key
+binding, variable assignment, and conditional syntax.
+
+@example
+@page
+# This file controls the behaviour of line input editing for
+# programs that use the Gnu Readline library. Existing programs
+# include FTP, Bash, and Gdb.
+#
+# You can re-read the inputrc file with C-x C-r.
+# Lines beginning with '#' are comments.
+#
+# First, include any systemwide bindings and variable assignments from
+# /etc/Inputrc
+$include /etc/Inputrc
+
+#
+# Set various bindings for emacs mode.
+
+set editing-mode emacs
+
+$if mode=emacs
+
+Meta-Control-h: backward-kill-word Text after the function name is ignored
+
+#
+# Arrow keys in keypad mode
+#
+#"\M-OD": backward-char
+#"\M-OC": forward-char
+#"\M-OA": previous-history
+#"\M-OB": next-history
+#
+# Arrow keys in ANSI mode
+#
+"\M-[D": backward-char
+"\M-[C": forward-char
+"\M-[A": previous-history
+"\M-[B": next-history
+#
+# Arrow keys in 8 bit keypad mode
+#
+#"\M-\C-OD": backward-char
+#"\M-\C-OC": forward-char
+#"\M-\C-OA": previous-history
+#"\M-\C-OB": next-history
+#
+# Arrow keys in 8 bit ANSI mode
+#
+#"\M-\C-[D": backward-char
+#"\M-\C-[C": forward-char
+#"\M-\C-[A": previous-history
+#"\M-\C-[B": next-history
+
+C-q: quoted-insert
+
+$endif
+
+# An old-style binding. This happens to be the default.
+TAB: complete
+
+# Macros that are convenient for shell interaction
+$if Bash
+# edit the path
+"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
+# prepare to type a quoted word -- insert open and close double quotes
+# and move to just after the open quote
+"\C-x\"": "\"\"\C-b"
+# insert a backslash (testing backslash escapes in sequences and macros)
+"\C-x\\": "\\"
+# Quote the current or previous word
+"\C-xq": "\eb\"\ef\""
+# Add a binding to refresh the line, which is unbound
+"\C-xr": redraw-current-line
+# Edit variable on current line.
+"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
+$endif
+
+# use a visible bell if one is available
+set bell-style visible
+
+# don't strip characters to 7 bits when reading
+set input-meta on
+
+# allow iso-latin1 characters to be inserted rather than converted to
+# prefix-meta sequences
+set convert-meta off
+
+# display characters with the eighth bit set directly rather than
+# as meta-prefixed characters
+set output-meta on
+
+# if there are more than 150 possible completions for a word, ask the
+# user if he wants to see all of them
+set completion-query-items 150
+
+# For FTP
+$if Ftp
+"\C-xg": "get \M-?"
+"\C-xt": "put \M-?"
+"\M-.": yank-last-arg
+$endif
+@end example
+
+@node Bindable Readline Commands
+@section Bindable Readline Commands
+
+@menu
+* Commands For Moving:: Moving about the line.
+* Commands For History:: Getting at previous lines.
+* Commands For Text:: Commands for changing text.
+* Commands For Killing:: Commands for killing and yanking.
+* Numeric Arguments:: Specifying numeric arguments, repeat counts.
+* Commands For Completion:: Getting Readline to do the typing for you.
+* Keyboard Macros:: Saving and re-executing typed characters
+* Miscellaneous Commands:: Other miscellaneous commands.
+@end menu
+
+This section describes Readline commands that may be bound to key
+sequences.
+
+@node Commands For Moving
+@subsection Commands For Moving
+@ftable @code
+@item beginning-of-line (C-a)
+Move to the start of the current line.
+
+@item end-of-line (C-e)
+Move to the end of the line.
+
+@item forward-char (C-f)
+Move forward a character.
+
+@item backward-char (C-b)
+Move back a character.
+
+@item forward-word (M-f)
+Move forward to the end of the next word. Words are composed of
+letters and digits.
+
+@item backward-word (M-b)
+Move back to the start of this, or the previous, word. Words are
+composed of letters and digits.
+
+@item clear-screen (C-l)
+Clear the screen and redraw the current line,
+leaving the current line at the top of the screen.
+
+@item redraw-current-line ()
+Refresh the current line. By default, this is unbound.
+
+@end ftable
+
+@node Commands For History
+@subsection Commands For Manipulating The History
+
+@ftable @code
+@item accept-line (Newline, Return)
+@ifset BashFeatures
+Accept the line regardless of where the cursor is. If this line is
+non-empty, add it to the history list according to the setting of
+the @code{HISTCONTROL} and @code{HISTIGNORE} variables.
+If this line was a history line, then restore the history line to its
+original state.
+@end ifset
+@ifclear BashFeatures
+Accept the line regardless of where the cursor is. If this line is
+non-empty, add it to the history list. If this line was a history
+line, then restore the history line to its original state.
+@end ifclear
+
+@item previous-history (C-p)
+Move `up' through the history list.
+
+@item next-history (C-n)
+Move `down' through the history list.
+
+@item beginning-of-history (M-<)
+Move to the first line in the history.
+
+@item end-of-history (M->)
+Move to the end of the input history, i.e., the line currently
+being entered.
+
+@item reverse-search-history (C-r)
+Search backward starting at the current line and moving `up' through
+the history as necessary. This is an incremental search.
+
+@item forward-search-history (C-s)
+Search forward starting at the current line and moving `down' through
+the the history as necessary. This is an incremental search.
+
+@item non-incremental-reverse-search-history (M-p)
+Search backward starting at the current line and moving `up'
+through the history as necessary using a non-incremental search
+for a string supplied by the user.
+
+@item non-incremental-forward-search-history (M-n)
+Search forward starting at the current line and moving `down'
+through the the history as necessary using a non-incremental search
+for a string supplied by the user.
+
+@item history-search-forward ()
+Search forward through the history for the string of characters
+between the start of the current line and the current cursor
+position (the @var{point}). This is a non-incremental search. By
+default, this command is unbound.
+
+@item history-search-backward ()
+Search backward through the history for the string of characters
+between the start of the current line and the point. This
+is a non-incremental search. By default, this command is unbound.
+
+@item yank-nth-arg (M-C-y)
+Insert the first argument to the previous command (usually
+the second word on the previous line). With an argument @var{n},
+insert the @var{n}th word from the previous command (the words
+in the previous command begin with word 0). A negative argument
+inserts the @var{n}th word from the end of the previous command.
+
+@item yank-last-arg (M-., M-_)
+Insert last argument to the previous command (the last word of the
+previous history entry). With an
+argument, behave exactly like @code{yank-nth-arg}.
+Successive calls to @code{yank-last-arg} move back through the history
+list, inserting the last argument of each line in turn.
+
+@end ftable
+
+@node Commands For Text
+@subsection Commands For Changing Text
+
+@ftable @code
+@item delete-char (C-d)
+Delete the character under the cursor. If the cursor is at the
+beginning of the line, there are no characters in the line, and
+the last character typed was not bound to @code{delete-char}, then
+return @code{EOF}.
+
+@item backward-delete-char (Rubout)
+Delete the character behind the cursor. A numeric argument means
+to kill the characters instead of deleting them.
+
+@item forward-backward-delete-char ()
+Delete the character under the cursor, unless the cursor is at the
+end of the line, in which case the character behind the cursor is
+deleted. By default, this is not bound to a key.
+
+@item quoted-insert (C-q, C-v)
+Add the next character typed to the line verbatim. This is
+how to insert key sequences like @key{C-q}, for example.
+
+@ifclear BashFeatures
+@item tab-insert (M-TAB)
+Insert a tab character.
+@end ifclear
+
+@item self-insert (a, b, A, 1, !, ...)
+Insert yourself.
+
+@item transpose-chars (C-t)
+Drag the character before the cursor forward over
+the character at the cursor, moving the
+cursor forward as well. If the insertion point
+is at the end of the line, then this
+transposes the last two characters of the line.
+Negative arguments don't work.
+
+@item transpose-words (M-t)
+Drag the word behind the cursor past the word in front of the cursor
+moving the cursor over that word as well.
+
+@item upcase-word (M-u)
+Uppercase the current (or following) word. With a negative argument,
+uppercase the previous word, but do not move the cursor.
+
+@item downcase-word (M-l)
+Lowercase the current (or following) word. With a negative argument,
+lowercase the previous word, but do not move the cursor.
+
+@item capitalize-word (M-c)
+Capitalize the current (or following) word. With a negative argument,
+capitalize the previous word, but do not move the cursor.
+
+@end ftable
+
+@node Commands For Killing
+@subsection Killing And Yanking
+
+@ftable @code
+
+@item kill-line (C-k)
+Kill the text from the current cursor position to the end of the line.
+
+@item backward-kill-line (C-x Rubout)
+Kill backward to the beginning of the line.
+
+@item unix-line-discard (C-u)
+Kill backward from the cursor to the beginning of the current line.
+The killed text is saved on the kill-ring.
+
+@item kill-whole-line ()
+Kill all characters on the current line, no matter where the
+cursor is. By default, this is unbound.
+
+@item kill-word (M-d)
+Kill from the cursor to the end of the current word, or if between
+words, to the end of the next word. Word boundaries are the same
+as @code{forward-word}.
+
+@item backward-kill-word (M-DEL)
+Kill the word behind the cursor. Word boundaries are the same
+as @code{backward-word}.
+
+@item unix-word-rubout (C-w)
+Kill the word behind the cursor, using white space as a word
+boundary. The killed text is saved on the kill-ring.
+
+@item delete-horizontal-space ()
+Delete all spaces and tabs around point. By default, this is unbound.
+
+@item kill-region ()
+Kill the text between the point and the @emph{mark} (saved
+cursor position). This text is referred to as the @var{region}.
+By default, this command is unbound.
+
+@item copy-region-as-kill ()
+Copy the text in the region to the kill buffer, so it can be yanked
+right away. By default, this command is unbound.
+
+@item copy-backward-word ()
+Copy the word before point to the kill buffer.
+The word boundaries are the same as @code{backward-word}.
+By default, this command is unbound.
+
+@item copy-forward-word ()
+Copy the word following point to the kill buffer.
+The word boundaries are the same as @code{forward-word}.
+By default, this command is unbound.
+
+@item yank (C-y)
+Yank the top of the kill ring into the buffer at the current
+cursor position.
+
+@item yank-pop (M-y)
+Rotate the kill-ring, and yank the new top. You can only do this if
+the prior command is yank or yank-pop.
+@end ftable
+
+@node Numeric Arguments
+@subsection Specifying Numeric Arguments
+@ftable @code
+
+@item digit-argument (M-0, M-1, ... M--)
+Add this digit to the argument already accumulating, or start a new
+argument. @key{M--} starts a negative argument.
+
+@item universal-argument ()
+This is another way to specify an argument.
+If this command is followed by one or more digits, optionally with a
+leading minus sign, those digits define the argument.
+If the command is followed by digits, executing @code{universal-argument}
+again ends the numeric argument, but is otherwise ignored.
+As a special case, if this command is immediately followed by a
+character that is neither a digit or minus sign, the argument count
+for the next command is multiplied by four.
+The argument count is initially one, so executing this function the
+first time makes the argument count four, a second time makes the
+argument count sixteen, and so on.
+By default, this is not bound to a key.
+@end ftable
+
+@node Commands For Completion
+@subsection Letting Readline Type For You
+
+@ftable @code
+@item complete (TAB)
+Attempt to do completion on the text before the cursor. This is
+application-specific. Generally, if you are typing a filename
+argument, you can do filename completion; if you are typing a command,
+you can do command completion; if you are typing in a symbol to GDB, you
+can do symbol name completion; if you are typing in a variable to Bash,
+you can do variable name completion, and so on.
+@ifset BashFeatures
+Bash attempts completion treating the text as a variable (if the
+text begins with @samp{$}), username (if the text begins with
+@samp{~}), hostname (if the text begins with @samp{@@}), or
+command (including aliases and functions) in turn. If none
+of these produces a match, filename completion is attempted.
+@end ifset
+
+@item possible-completions (M-?)
+List the possible completions of the text before the cursor.
+
+@item insert-completions (M-*)
+Insert all completions of the text before point that would have
+been generated by @code{possible-completions}.
+
+@item menu-complete ()
+Similar to @code{complete}, but replaces the word to be completed
+with a single match from the list of possible completions.
+Repeated execution of @code{menu-complete} steps through the list
+of possible completions, inserting each match in turn.
+At the end of the list of completions, the bell is rung and the
+original text is restored.
+An argument of @var{n} moves @var{n} positions forward in the list
+of matches; a negative argument may be used to move backward
+through the list.
+This command is intended to be bound to @code{TAB}, but is unbound
+by default.
+
+@item delete-char-or-list ()
+Deletes the character under the cursor if not at the beginning or
+end of the line (like @code{delete-char}).
+If at the end of the line, behaves identically to
+@code{possible-completions}.
+This command is unbound by default.
+
+@ifset BashFeatures
+@item complete-filename (M-/)
+Attempt filename completion on the text before point.
+
+@item possible-filename-completions (C-x /)
+List the possible completions of the text before point,
+treating it as a filename.
+
+@item complete-username (M-~)
+Attempt completion on the text before point, treating
+it as a username.
+
+@item possible-username-completions (C-x ~)
+List the possible completions of the text before point,
+treating it as a username.
+
+@item complete-variable (M-$)
+Attempt completion on the text before point, treating
+it as a shell variable.
+
+@item possible-variable-completions (C-x $)
+List the possible completions of the text before point,
+treating it as a shell variable.
+
+@item complete-hostname (M-@@)
+Attempt completion on the text before point, treating
+it as a hostname.
+
+@item possible-hostname-completions (C-x @@)
+List the possible completions of the text before point,
+treating it as a hostname.
+
+@item complete-command (M-!)
+Attempt completion on the text before point, treating
+it as a command name. Command completion attempts to
+match the text against aliases, reserved words, shell
+functions, shell builtins, and finally executable filenames,
+in that order.
+
+@item possible-command-completions (C-x !)
+List the possible completions of the text before point,
+treating it as a command name.
+
+@item dynamic-complete-history (M-TAB)
+Attempt completion on the text before point, comparing
+the text against lines from the history list for possible
+completion matches.
+
+@item complete-into-braces (M-@{)
+Perform filename completion and return the list of possible completions
+enclosed within braces so the list is available to the shell
+(@pxref{Brace Expansion}).
+
+@end ifset
+@end ftable
+
+@node Keyboard Macros
+@subsection Keyboard Macros
+@ftable @code
+
+@item start-kbd-macro (C-x ()
+Begin saving the characters typed into the current keyboard macro.
+
+@item end-kbd-macro (C-x ))
+Stop saving the characters typed into the current keyboard macro
+and save the definition.
+
+@item call-last-kbd-macro (C-x e)
+Re-execute the last keyboard macro defined, by making the characters
+in the macro appear as if typed at the keyboard.
+
+@end ftable
+
+@node Miscellaneous Commands
+@subsection Some Miscellaneous Commands
+@ftable @code
+
+@item re-read-init-file (C-x C-r)
+Read in the contents of the inputrc file, and incorporate
+any bindings or variable assignments found there.
+
+@item abort (C-g)
+Abort the current editing command and
+ring the terminal's bell (subject to the setting of
+@code{bell-style}).
+
+@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
+If the metafied character @var{x} is lowercase, run the command
+that is bound to the corresponding uppercase character.
+
+@item prefix-meta (ESC)
+Make the next character typed be metafied. This is for keyboards
+without a meta key. Typing @samp{ESC f} is equivalent to typing
+@samp{M-f}.
+
+@item undo (C-_, C-x C-u)
+Incremental undo, separately remembered for each line.
+
+@item revert-line (M-r)
+Undo all changes made to this line. This is like executing the @code{undo}
+command enough times to get back to the beginning.
+
+@ifset BashFeatures
+@item tilde-expand (M-&)
+@end ifset
+@ifclear BashFeatures
+@item tilde-expand (M-~)
+@end ifclear
+Perform tilde expansion on the current word.
+
+@item set-mark (C-@@)
+Set the mark to the current point. If a
+numeric argument is supplied, the mark is set to that position.
+
+@item exchange-point-and-mark (C-x C-x)
+Swap the point with the mark. The current cursor position is set to
+the saved position, and the old cursor position is saved as the mark.
+
+@item character-search (C-])
+A character is read and point is moved to the next occurrence of that
+character. A negative count searches for previous occurrences.
+
+@item character-search-backward (M-C-])
+A character is read and point is moved to the previous occurrence
+of that character. A negative count searches for subsequent
+occurrences.
+
+@item insert-comment (M-#)
+The value of the @code{comment-begin}
+variable is inserted at the beginning of the current line,
+and the line is accepted as if a newline had been typed.
+@ifset BashFeatures
+This makes the current line a shell comment.
+@end ifset
+
+@item dump-functions ()
+Print all of the functions and their key bindings to the
+Readline output stream. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file. This command is unbound by default.
+
+@item dump-variables ()
+Print all of the settable variables and their values to the
+Readline output stream. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file. This command is unbound by default.
+
+@item dump-macros ()
+Print all of the Readline key sequences bound to macros and the
+strings they ouput. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file. This command is unbound by default.
+
+@ifset BashFeatures
+@item glob-expand-word (C-x *)
+The word before point is treated as a pattern for pathname expansion,
+and the list of matching file names is inserted, replacing the word.
+
+@item glob-list-expansions (C-x g)
+The list of expansions that would have been generated by
+@code{glob-expand-word} is displayed, and the line is redrawn.
+
+@item display-shell-version (C-x C-v)
+Display version information about the current instance of Bash.
+
+@item shell-expand-line (M-C-e)
+Expand the line as the shell does.
+This performs alias and history expansion as well as all of the shell
+word expansions (@pxref{Shell Expansions}).
+
+@item history-expand-line (M-^)
+Perform history expansion on the current line.
+
+@item magic-space ()
+Perform history expansion on the current line and insert a space
+(@pxref{History Interaction}).
+
+@item alias-expand-line ()
+Perform alias expansion on the current line (@pxref{Aliases}).
+
+@item history-and-alias-expand-line ()
+Perform history and alias expansion on the current line.
+
+@item insert-last-argument (M-., M-_)
+A synonym for @code{yank-last-arg}.
+
+@item operate-and-get-next (C-o)
+Accept the current line for execution and fetch the next line
+relative to the current line from the history for editing. Any
+argument is ignored.
+
+@item emacs-editing-mode (C-e)
+When in @code{vi} editing mode, this causes a switch back to
+@code{emacs} editing mode, as if the command @samp{set -o emacs} had
+been executed.
+
+@end ifset
+
+@end ftable
+
+@node Readline vi Mode
+@section Readline vi Mode
+
+While the Readline library does not have a full set of @code{vi}
+editing functions, it does contain enough to allow simple editing
+of the line. The Readline @code{vi} mode behaves as specified in
+the @sc{POSIX} 1003.2 standard.
+
+@ifset BashFeatures
+In order to switch interactively between @code{emacs} and @code{vi}
+editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
+commands (@pxref{The Set Builtin}).
+@end ifset
+@ifclear BashFeatures
+In order to switch interactively between @code{emacs} and @code{vi}
+editing modes, use the command M-C-j (toggle-editing-mode).
+@end ifclear
+The Readline default is @code{emacs} mode.
+
+When you enter a line in @code{vi} mode, you are already placed in
+`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
+switches you into `command' mode, where you can edit the text of the
+line with the standard @code{vi} movement keys, move to previous
+history lines with @samp{k} and subsequent lines with @samp{j}, and
+so forth.
Index: hstech.texinfo
===================================================================
--- hstech.texinfo (nonexistent)
+++ hstech.texinfo (revision 1765)
@@ -0,0 +1,515 @@
+@ignore
+This file documents the user interface to the GNU History library.
+
+Copyright (C) 1988, 1991, 1994, 1996 Free Software Foundation, Inc.
+Authored by Brian Fox and Chet Ramey.
+
+Permission is granted to make and distribute verbatim copies of this manual
+provided the copyright notice and this permission notice are preserved on
+all copies.
+
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+GNU Copyright statement is available to the distributee, and provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ignore
+
+@node Programming with GNU History
+@chapter Programming with GNU History
+
+This chapter describes how to interface programs that you write
+with the GNU History Library.
+It should be considered a technical guide.
+For information on the interactive use of GNU History, @pxref{Using
+History Interactively}.
+
+@menu
+* Introduction to History:: What is the GNU History library for?
+* History Storage:: How information is stored.
+* History Functions:: Functions that you can use.
+* History Variables:: Variables that control behaviour.
+* History Programming Example:: Example of using the GNU History Library.
+@end menu
+
+@node Introduction to History
+@section Introduction to History
+
+Many programs read input from the user a line at a time. The GNU History
+library is able to keep track of those lines, associate arbitrary data with
+each line, and utilize information from previous lines in composing new
+ones.
+
+The programmer using the History library has available functions
+for remembering lines on a history list, associating arbitrary data
+with a line, removing lines from the list, searching through the list
+for a line containing an arbitrary text string, and referencing any line
+in the list directly. In addition, a history @dfn{expansion} function
+is available which provides for a consistent user interface across
+different programs.
+
+The user using programs written with the History library has the
+benefit of a consistent user interface with a set of well-known
+commands for manipulating the text of previous lines and using that text
+in new commands. The basic history manipulation commands are similar to
+the history substitution provided by @code{csh}.
+
+If the programmer desires, he can use the Readline library, which
+includes some history manipulation by default, and has the added
+advantage of command line editing.
+
+@node History Storage
+@section History Storage
+
+The history list is an array of history entries. A history entry is
+declared as follows:
+
+@example
+typedef struct _hist_entry @{
+ char *line;
+ char *data;
+@} HIST_ENTRY;
+@end example
+
+The history list itself might therefore be declared as
+
+@example
+HIST_ENTRY **the_history_list;
+@end example
+
+The state of the History library is encapsulated into a single structure:
+
+@example
+/* A structure used to pass the current state of the history stuff around. */
+typedef struct _hist_state @{
+ HIST_ENTRY **entries; /* Pointer to the entries themselves. */
+ int offset; /* The location pointer within this array. */
+ int length; /* Number of elements within this array. */
+ int size; /* Number of slots allocated to this array. */
+ int flags;
+@} HISTORY_STATE;
+@end example
+
+If the flags member includes @code{HS_STIFLED}, the history has been
+stifled.
+
+@node History Functions
+@section History Functions
+
+This section describes the calling sequence for the various functions
+present in GNU History.
+
+@menu
+* Initializing History and State Management:: Functions to call when you
+ want to use history in a
+ program.
+* History List Management:: Functions used to manage the list
+ of history entries.
+* Information About the History List:: Functions returning information about
+ the history list.
+* Moving Around the History List:: Functions used to change the position
+ in the history list.
+* Searching the History List:: Functions to search the history list
+ for entries containing a string.
+* Managing the History File:: Functions that read and write a file
+ containing the history list.
+* History Expansion:: Functions to perform csh-like history
+ expansion.
+@end menu
+
+@node Initializing History and State Management
+@subsection Initializing History and State Management
+
+This section describes functions used to initialize and manage
+the state of the History library when you want to use the history
+functions in your program.
+
+@deftypefun void using_history ()
+Begin a session in which the history functions might be used. This
+initializes the interactive variables.
+@end deftypefun
+
+@deftypefun {HISTORY_STATE *} history_get_history_state ()
+Return a structure describing the current state of the input history.
+@end deftypefun
+
+@deftypefun void history_set_history_state (HISTORY_STATE *state)
+Set the state of the history list according to @var{state}.
+@end deftypefun
+
+@node History List Management
+@subsection History List Management
+
+These functions manage individual entries on the history list, or set
+parameters managing the list itself.
+
+@deftypefun void add_history (char *string)
+Place @var{string} at the end of the history list. The associated data
+field (if any) is set to @code{NULL}.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} remove_history (int which)
+Remove history entry at offset @var{which} from the history. The
+removed element is returned so you can free the line, data,
+and containing structure.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
+Make the history entry at offset @var{which} have @var{line} and @var{data}.
+This returns the old entry so you can dispose of the data. In the case
+of an invalid @var{which}, a @code{NULL} pointer is returned.
+@end deftypefun
+
+@deftypefun void clear_history ()
+Clear the history list by deleting all the entries.
+@end deftypefun
+
+@deftypefun void stifle_history (int max)
+Stifle the history list, remembering only the last @var{max} entries.
+@end deftypefun
+
+@deftypefun int unstifle_history ()
+Stop stifling the history. This returns the previous amount the
+history was stifled. The value is positive if the history was
+stifled, negative if it wasn't.
+@end deftypefun
+
+@deftypefun int history_is_stifled ()
+Returns non-zero if the history is stifled, zero if it is not.
+@end deftypefun
+
+@node Information About the History List
+@subsection Information About the History List
+
+These functions return information about the entire history list or
+individual list entries.
+
+@deftypefun {HIST_ENTRY **} history_list ()
+Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
+current input history. Element 0 of this list is the beginning of time.
+If there is no history, return @code{NULL}.
+@end deftypefun
+
+@deftypefun int where_history ()
+Returns the offset of the current history element.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} current_history ()
+Return the history entry at the current position, as determined by
+@code{where_history ()}. If there is no entry there, return a @code{NULL}
+pointer.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} history_get (int offset)
+Return the history entry at position @var{offset}, starting from
+@code{history_base}. If there is no entry there, or if @var{offset}
+is greater than the history length, return a @code{NULL} pointer.
+@end deftypefun
+
+@deftypefun int history_total_bytes ()
+Return the number of bytes that the primary history entries are using.
+This function returns the sum of the lengths of all the lines in the
+history.
+@end deftypefun
+
+@node Moving Around the History List
+@subsection Moving Around the History List
+
+These functions allow the current index into the history list to be
+set or changed.
+
+@deftypefun int history_set_pos (int pos)
+Set the position in the history list to @var{pos}, an absolute index
+into the list.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} previous_history ()
+Back up the current history offset to the previous history entry, and
+return a pointer to that entry. If there is no previous entry, return
+a @code{NULL} pointer.
+@end deftypefun
+
+@deftypefun {HIST_ENTRY *} next_history ()
+Move the current history offset forward to the next history entry, and
+return the a pointer to that entry. If there is no next entry, return
+a @code{NULL} pointer.
+@end deftypefun
+
+@node Searching the History List
+@subsection Searching the History List
+@cindex History Searching
+
+These functions allow searching of the history list for entries containing
+a specific string. Searching may be performed both forward and backward
+from the current history position. The search may be @dfn{anchored},
+meaning that the string must match at the beginning of the history entry.
+@cindex anchored search
+
+@deftypefun int history_search (char *string, int direction)
+Search the history for @var{string}, starting at the current history
+offset. If @var{direction} < 0, then the search is through previous entries,
+else through subsequent. If @var{string} is found, then
+the current history index is set to that history entry, and the value
+returned is the offset in the line of the entry where
+@var{string} was found. Otherwise, nothing is changed, and a -1 is
+returned.
+@end deftypefun
+
+@deftypefun int history_search_prefix (char *string, int direction)
+Search the history for @var{string}, starting at the current history
+offset. The search is anchored: matching lines must begin with
+@var{string}. If @var{direction} < 0, then the search is through previous
+entries, else through subsequent. If @var{string} is found, then the
+current history index is set to that entry, and the return value is 0.
+Otherwise, nothing is changed, and a -1 is returned.
+@end deftypefun
+
+@deftypefun int history_search_pos (char *string, int direction, int pos)
+Search for @var{string} in the history list, starting at @var{pos}, an
+absolute index into the list. If @var{direction} is negative, the search
+proceeds backward from @var{pos}, otherwise forward. Returns the absolute
+index of the history element where @var{string} was found, or -1 otherwise.
+@end deftypefun
+
+@node Managing the History File
+@subsection Managing the History File
+
+The History library can read the history from and write it to a file.
+This section documents the functions for managing a history file.
+
+@deftypefun int read_history (char *filename)
+Add the contents of @var{filename} to the history list, a line at a
+time. If @var{filename} is @code{NULL}, then read from
+@file{~/.history}. Returns 0 if successful, or errno if not.
+@end deftypefun
+
+@deftypefun int read_history_range (char *filename, int from, int to)
+Read a range of lines from @var{filename}, adding them to the history list.
+Start reading at line @var{from} and end at @var{to}. If
+@var{from} is zero, start at the beginning. If @var{to} is less than
+@var{from}, then read until the end of the file. If @var{filename} is
+@code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
+or @code{errno} if not.
+@end deftypefun
+
+@deftypefun int write_history (char *filename)
+Write the current history to @var{filename}, overwriting @var{filename}
+if necessary. If @var{filename} is
+@code{NULL}, then write the history list to @file{~/.history}. Values
+returned are as in @code{read_history ()}.
+@end deftypefun
+
+@deftypefun int append_history (int nelements, char *filename)
+Append the last @var{nelements} of the history list to @var{filename}.
+@end deftypefun
+
+@deftypefun int history_truncate_file (char *filename, int nlines)
+Truncate the history file @var{filename}, leaving only the last
+@var{nlines} lines.
+@end deftypefun
+
+@node History Expansion
+@subsection History Expansion
+
+These functions implement @code{csh}-like history expansion.
+
+@deftypefun int history_expand (char *string, char **output)
+Expand @var{string}, placing the result into @var{output}, a pointer
+to a string (@pxref{History Interaction}). Returns:
+@table @code
+@item 0
+If no expansions took place (or, if the only change in
+the text was the de-slashifying of the history expansion
+character);
+@item 1
+if expansions did take place;
+@item -1
+if there was an error in expansion;
+@item 2
+if the returned line should only be displayed, but not executed,
+as with the @code{:p} modifier (@pxref{Modifiers}).
+@end table
+
+If an error ocurred in expansion, then @var{output} contains a descriptive
+error message.
+@end deftypefun
+
+@deftypefun {char *} history_arg_extract (int first, int last, char *string)
+Extract a string segment consisting of the @var{first} through @var{last}
+arguments present in @var{string}. Arguments are broken up as in Bash.
+@end deftypefun
+
+@deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
+Returns the text of the history event beginning at @var{string} +
+@var{*cindex}. @var{*cindex} is modified to point to after the event
+specifier. At function entry, @var{cindex} points to the index into
+@var{string} where the history event specification begins. @var{qchar}
+is a character that is allowed to end the event specification in addition
+to the ``normal'' terminating characters.
+@end deftypefun
+
+@deftypefun {char **} history_tokenize (char *string)
+Return an array of tokens parsed out of @var{string}, much as the
+shell might. The tokens are split on white space and on the
+characters @code{()<>;&|$}, and shell quoting conventions are
+obeyed.
+@end deftypefun
+
+@node History Variables
+@section History Variables
+
+This section describes the externally visible variables exported by
+the GNU History Library.
+
+@deftypevar int history_base
+The logical offset of the first entry in the history list.
+@end deftypevar
+
+@deftypevar int history_length
+The number of entries currently stored in the history list.
+@end deftypevar
+
+@deftypevar int max_input_history
+The maximum number of history entries. This must be changed using
+@code{stifle_history ()}.
+@end deftypevar
+
+@deftypevar char history_expansion_char
+The character that starts a history event. The default is @samp{!}.
+@end deftypevar
+
+@deftypevar char history_subst_char
+The character that invokes word substitution if found at the start of
+a line. The default is @samp{^}.
+@end deftypevar
+
+@deftypevar char history_comment_char
+During tokenization, if this character is seen as the first character
+of a word, then it and all subsequent characters up to a newline are
+ignored, suppressing history expansion for the remainder of the line.
+This is disabled by default.
+@end deftypevar
+
+@deftypevar {char *} history_no_expand_chars
+The list of characters which inhibit history expansion if found immediately
+following @var{history_expansion_char}. The default is whitespace and
+@samp{=}.
+@end deftypevar
+
+@deftypevar {char *} history_search_delimiter_chars
+The list of additional characters which can delimit a history search
+string, in addition to whitespace, @samp{:} and @samp{?} in the case of
+a substring search. The default is empty.
+@end deftypevar
+
+@deftypevar int history_quotes_inhibit_expansion
+If non-zero, single-quoted words are not scanned for the history expansion
+character. The default value is 0.
+@end deftypevar
+
+@deftypevar {Function *} history_inhibit_expansion_function
+This should be set to the address of a function that takes two arguments:
+a @code{char *} (@var{string}) and an integer index into that string (@var{i}).
+It should return a non-zero value if the history expansion starting at
+@var{string[i]} should not be performed; zero if the expansion should
+be done.
+It is intended for use by applications like Bash that use the history
+expansion character for additional purposes.
+By default, this variable is set to NULL.
+@end deftypevar
+
+@node History Programming Example
+@section History Programming Example
+
+The following program demonstrates simple use of the GNU History Library.
+
+@smallexample
+main ()
+@{
+ char line[1024], *t;
+ int len, done = 0;
+
+ line[0] = 0;
+
+ using_history ();
+ while (!done)
+ @{
+ printf ("history$ ");
+ fflush (stdout);
+ t = fgets (line, sizeof (line) - 1, stdin);
+ if (t && *t)
+ @{
+ len = strlen (t);
+ if (t[len - 1] == '\n')
+ t[len - 1] = '\0';
+ @}
+
+ if (!t)
+ strcpy (line, "quit");
+
+ if (line[0])
+ @{
+ char *expansion;
+ int result;
+
+ result = history_expand (line, &expansion);
+ if (result)
+ fprintf (stderr, "%s\n", expansion);
+
+ if (result < 0 || result == 2)
+ @{
+ free (expansion);
+ continue;
+ @}
+
+ add_history (expansion);
+ strncpy (line, expansion, sizeof (line) - 1);
+ free (expansion);
+ @}
+
+ if (strcmp (line, "quit") == 0)
+ done = 1;
+ else if (strcmp (line, "save") == 0)
+ write_history ("history_file");
+ else if (strcmp (line, "read") == 0)
+ read_history ("history_file");
+ else if (strcmp (line, "list") == 0)
+ @{
+ register HIST_ENTRY **the_list;
+ register int i;
+
+ the_list = history_list ();
+ if (the_list)
+ for (i = 0; the_list[i]; i++)
+ printf ("%d: %s\n", i + history_base, the_list[i]->line);
+ @}
+ else if (strncmp (line, "delete", 6) == 0)
+ @{
+ int which;
+ if ((sscanf (line + 6, "%d", &which)) == 1)
+ @{
+ HIST_ENTRY *entry = remove_history (which);
+ if (!entry)
+ fprintf (stderr, "No such entry %d\n", which);
+ else
+ @{
+ free (entry->line);
+ free (entry);
+ @}
+ @}
+ else
+ @{
+ fprintf (stderr, "non-numeric arg given to `delete'\n");
+ @}
+ @}
+ @}
+@}
+@end smallexample
Index: inc-hist.texinfo
===================================================================
--- inc-hist.texinfo (nonexistent)
+++ inc-hist.texinfo (revision 1765)
@@ -0,0 +1,399 @@
+@ignore
+This file documents the user interface to the GNU History library.
+
+Copyright (C) 1988, 1991, 1996 Free Software Foundation, Inc.
+Authored by Brian Fox and Chet Ramey.
+
+Permission is granted to make and distribute verbatim copies of this manual
+provided the copyright notice and this permission notice are preserved on
+all copies.
+
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+GNU Copyright statement is available to the distributee, and provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ignore
+
+@node Using History Interactively
+@chapter Using History Interactively
+
+@ifset BashFeatures
+This chapter describes how to use the GNU History Library interactively,
+from a user's standpoint. It should be considered a user's guide. For
+information on using the GNU History Library in other programs,
+see the GNU Readline Library Manual.
+@end ifset
+@ifclear BashFeatures
+This chapter describes how to use the GNU History Library interactively,
+from a user's standpoint. It should be considered a user's guide.
+@c For
+@c information on using the GNU History Library in your own programs,
+@c @pxref{Programming with GNU History}.
+@end ifclear
+
+@ifset BashFeatures
+@menu
+* Bash History Facilities:: How Bash lets you manipulate your command
+ history.
+* Bash History Builtins:: The Bash builtin commands that manipulate
+ the command history.
+* History Interaction:: What it feels like using History as a user.
+@end menu
+@end ifset
+@ifclear BashFeatures
+@menu
+* History Interaction:: What it feels like using History as a user.
+@end menu
+@end ifclear
+
+@ifset BashFeatures
+@node Bash History Facilities
+@section Bash History Facilities
+@cindex command history
+@cindex history list
+
+When the @samp{-o history} option to the @code{set} builtin
+is enabled (@pxref{The Set Builtin}),
+the shell provides access to the @var{command history},
+the list of commands previously typed. The text of the last
+@code{HISTSIZE}
+commands (default 500) is saved in a history list. The shell
+stores each command in the history list prior to parameter and
+variable expansion
+but after history expansion is performed, subject to the
+values of the shell variables
+@code{HISTIGNORE} and @code{HISTCONTROL}.
+When the shell starts up, the history is initialized from the
+file named by the @code{HISTFILE} variable (default @file{~/.bash_history}).
+@code{HISTFILE} is truncated, if necessary, to contain no more than
+the number of lines specified by the value of the @code{HISTFILESIZE}
+variable. When an interactive shell exits, the last
+@code{HISTSIZE} lines are copied from the history list to @code{HISTFILE}.
+If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
+the lines are appended to the history file,
+otherwise the history file is overwritten.
+If @code{HISTFILE}
+is unset, or if the history file is unwritable, the history is
+not saved. After saving the history, the history file is truncated
+to contain no more than @code{$HISTFILESIZE}
+lines. If @code{HISTFILESIZE} is not set, no truncation is performed.
+
+The builtin command @code{fc} may be used to list or edit and re-execute
+a portion of the history list.
+The @code{history} builtin can be used to display or modify the history
+list and manipulate the history file.
+When using the command-line editing, search commands
+are available in each editing mode that provide access to the
+history list.
+
+The shell allows control over which commands are saved on the history
+list. The @code{HISTCONTROL} and @code{HISTIGNORE}
+variables may be set to cause the shell to save only a subset of the
+commands entered.
+The @code{cmdhist}
+shell option, if enabled, causes the shell to attempt to save each
+line of a multi-line command in the same history entry, adding
+semicolons where necessary to preserve syntactic correctness.
+The @code{lithist}
+shell option causes the shell to save the command with embedded newlines
+instead of semicolons.
+@xref{Bash Builtins}, for a description of @code{shopt}.
+
+@node Bash History Builtins
+@section Bash History Builtins
+@cindex history builtins
+
+Bash provides two builtin commands that allow you to manipulate the
+history list and history file.
+
+@table @code
+
+@item fc
+@c btindex fc
+@example
+@code{fc [-e @var{ename}] [-nlr] [@var{first}] [@var{last}]}
+@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
+@end example
+
+Fix Command. In the first form, a range of commands from @var{first} to
+@var{last} is selected from the history list. Both @var{first} and
+@var{last} may be specified as a string (to locate the most recent
+command beginning with that string) or as a number (an index into the
+history list, where a negative number is used as an offset from the
+current command number). If @var{last} is not specified it is set to
+@var{first}. If @var{first} is not specified it is set to the previous
+command for editing and @minus{}16 for listing. If the @samp{-l} flag is
+given, the commands are listed on standard output. The @samp{-n} flag
+suppresses the command numbers when listing. The @samp{-r} flag
+reverses the order of the listing. Otherwise, the editor given by
+@var{ename} is invoked on a file containing those commands. If
+@var{ename} is not given, the value of the following variable expansion
+is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the
+value of the @code{FCEDIT} variable if set, or the value of the
+@code{EDITOR} variable if that is set, or @code{vi} if neither is set.
+When editing is complete, the edited commands are echoed and executed.
+
+In the second form, @var{command} is re-executed after each instance
+of @var{pat} in the selected command is replaced by @var{rep}.
+
+A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
+that typing @samp{r cc} runs the last command beginning with @code{cc}
+and typing @samp{r} re-executes the last command (@pxref{Aliases}).
+
+@item history
+@c btindex history
+@example
+history [-c] [@var{n}]
+history [-anrw] [@var{filename}]
+history -ps @var{arg}
+@end example
+
+Display the history list with line numbers. Lines prefixed with
+with a @samp{*} have been modified. An argument of @var{n} says
+to list only the last @var{n} lines. Options, if supplied, have
+the following meanings:
+
+@table @code
+@item -w
+Write out the current history to the history file.
+
+@item -r
+Read the current history file and append its contents to
+the history list.
+
+@item -a
+Append the new
+history lines (history lines entered since the beginning of the
+current Bash session) to the history file.
+
+@item -n
+Append the history lines not already read from the history file
+to the current history list. These are lines appended to the history
+file since the beginning of the current Bash session.
+
+@item -c
+Clear the history list. This may be combined
+with the other options to replace the history list completely.
+
+@item -s
+The @var{arg}s are added to the end of
+the history list as a single entry.
+
+@item -p
+Perform history substitution on the @var{arg}s and display the result
+on the standard output, without storing the results in the history list.
+@end table
+
+When the @samp{-w}, @samp{-r}, @samp{-a}, or @samp{-n} option is
+used, if @var{filename}
+is given, then it is used as the history file. If not, then
+the value of the @code{HISTFILE} variable is used.
+
+@end table
+@end ifset
+
+@node History Interaction
+@section History Expansion
+@cindex history expansion
+
+The History library provides a history expansion feature that is similar
+to the history expansion provided by @code{csh}. This section
+describes the syntax used to manipulate the history information.
+
+History expansions introduce words from the history list into
+the input stream, making it easy to repeat commands, insert the
+arguments to a previous command into the current input line, or
+fix errors in previous commands quickly.
+
+History expansion takes place in two parts. The first is to determine
+which line from the history list should be used during substitution.
+The second is to select portions of that line for inclusion into the
+current one. The line selected from the history is called the
+@dfn{event}, and the portions of that line that are acted upon are
+called @dfn{words}. Various @dfn{modifiers} are available to manipulate
+the selected words. The line is broken into words in the same fashion
+that Bash does, so that several words
+surrounded by quotes are considered one word.
+History expansions are introduced by the appearance of the
+history expansion character, which is @samp{!} by default.
+@ifset BashFeatures
+Only @samp{\} and @samp{'} may be used to escape the history expansion
+character.
+@end ifset
+
+@ifset BashFeatures
+Several shell options settable with the @code{shopt}
+builtin (@pxref{Bash Builtins}) may be used to tailor
+the behavior of history expansion. If the
+@code{histverify} shell option is enabled, and Readline
+is being used, history substitutions are not immediately passed to
+the shell parser.
+Instead, the expanded line is reloaded into the Readline
+editing buffer for further modification.
+If Readline is being used, and the @code{histreedit}
+shell option is enabled, a failed history expansion will be
+reloaded into the Readline editing buffer for correction.
+The @samp{-p} option to the @code{history} builtin command
+may be used to see what a history expansion will do before using it.
+The @samp{-s} option to the @code{history} builtin may be used to
+add commands to the end of the history list without actually executing
+them, so that they are available for subsequent recall.
+This is most useful in conjunction with Readline.
+
+The shell allows control of the various characters used by the
+history expansion mechanism with the @code{histchars} variable.
+@end ifset
+
+@menu
+* Event Designators:: How to specify which history line to use.
+* Word Designators:: Specifying which words are of interest.
+* Modifiers:: Modifying the results of substitution.
+@end menu
+
+@node Event Designators
+@subsection Event Designators
+@cindex event designators
+
+An event designator is a reference to a command line entry in the
+history list.
+@cindex history events
+
+@table @asis
+
+@item @code{!}
+Start a history substitution, except when followed by a space, tab,
+the end of the line, @samp{=} or @samp{(}.
+
+@item @code{!@var{n}}
+Refer to command line @var{n}.
+
+@item @code{!-@var{n}}
+Refer to the command @var{n} lines back.
+
+@item @code{!!}
+Refer to the previous command. This is a synonym for @samp{!-1}.
+
+@item @code{!@var{string}}
+Refer to the most recent command starting with @var{string}.
+
+@item @code{!?@var{string}[?]}
+Refer to the most recent command containing @var{string}. The trailing
+@samp{?} may be omitted if the @var{string} is followed immediately by
+a newline.
+
+@item @code{^@var{string1}^@var{string2}^}
+Quick Substitution. Repeat the last command, replacing @var{string1}
+with @var{string2}. Equivalent to
+@code{!!:s/@var{string1}/@var{string2}/}.
+
+@item @code{!#}
+The entire command line typed so far.
+
+@end table
+
+@node Word Designators
+@subsection Word Designators
+
+Word designators are used to select desired words from the event.
+A @samp{:} separates the event specification from the word designator. It
+may be omitted if the word designator begins with a @samp{^}, @samp{$},
+@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning
+of the line, with the first word being denoted by 0 (zero). Words are
+inserted into the current line separated by single spaces.
+
+@table @code
+
+@item 0 (zero)
+The @code{0}th word. For many applications, this is the command word.
+
+@item @var{n}
+The @var{n}th word.
+
+@item ^
+The first argument; that is, word 1.
+
+@item $
+The last argument.
+
+@item %
+The word matched by the most recent @samp{?@var{string}?} search.
+
+@item @var{x}-@var{y}
+A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}.
+
+@item *
+All of the words, except the @code{0}th. This is a synonym for @samp{1-$}.
+It is not an error to use @samp{*} if there is just one word in the event;
+the empty string is returned in that case.
+
+@item @var{x}*
+Abbreviates @samp{@var{x}-$}
+
+@item @var{x}-
+Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word.
+
+@end table
+
+If a word designator is supplied without an event specification, the
+previous command is used as the event.
+
+@node Modifiers
+@subsection Modifiers
+
+After the optional word designator, you can add a sequence of one or more
+of the following modifiers, each preceded by a @samp{:}.
+
+@table @code
+
+@item h
+Remove a trailing pathname component, leaving only the head.
+
+@item t
+Remove all leading pathname components, leaving the tail.
+
+@item r
+Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving
+the basename.
+
+@item e
+Remove all but the trailing suffix.
+
+@item p
+Print the new command but do not execute it.
+
+@ifset BashFeatures
+@item q
+Quote the substituted words, escaping further substitutions.
+
+@item x
+Quote the substituted words as with @samp{q},
+but break into words at spaces, tabs, and newlines.
+@end ifset
+
+@item s/@var{old}/@var{new}/
+Substitute @var{new} for the first occurrence of @var{old} in the
+event line. Any delimiter may be used in place of @samp{/}.
+The delimiter may be quoted in @var{old} and @var{new}
+with a single backslash. If @samp{&} appears in @var{new},
+it is replaced by @var{old}. A single backslash will quote
+the @samp{&}. The final delimiter is optional if it is the last
+character on the input line.
+
+@item &
+Repeat the previous substitution.
+
+@item g
+Cause changes to be applied over the entire event line. Used in
+conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/},
+or with @samp{&}.
+
+@end table
Index: rltech.texinfo
===================================================================
--- rltech.texinfo (nonexistent)
+++ rltech.texinfo (revision 1765)
@@ -0,0 +1,1707 @@
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename rltech.info
+@comment %**end of header (This is for running Texinfo on a region.)
+@setchapternewpage odd
+
+@ifinfo
+This document describes the GNU Readline Library, a utility for aiding
+in the consitency of user interface across discrete programs that need
+to provide a command line interface.
+
+Copyright (C) 1988, 1994, 1996, 1998, 1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+pare preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Foundation.
+@end ifinfo
+
+@node Programming with GNU Readline
+@chapter Programming with GNU Readline
+
+This chapter describes the interface between the GNU Readline Library and
+other programs. If you are a programmer, and you wish to include the
+features found in GNU Readline
+such as completion, line editing, and interactive history manipulation
+in your own programs, this section is for you.
+
+@menu
+* Basic Behavior:: Using the default behavior of Readline.
+* Custom Functions:: Adding your own functions to Readline.
+* Readline Variables:: Variables accessible to custom
+ functions.
+* Readline Convenience Functions:: Functions which Readline supplies to
+ aid in writing your own custom
+ functions.
+* Readline Signal Handling:: How Readline behaves when it receives signals.
+* Custom Completers:: Supplanting or supplementing Readline's
+ completion functions.
+@end menu
+
+@node Basic Behavior
+@section Basic Behavior
+
+Many programs provide a command line interface, such as @code{mail},
+@code{ftp}, and @code{sh}. For such programs, the default behaviour of
+Readline is sufficient. This section describes how to use Readline in
+the simplest way possible, perhaps to replace calls in your code to
+@code{gets()} or @code{fgets ()}.
+
+@findex readline
+@cindex readline, function
+The function @code{readline ()} prints a prompt and then reads and returns
+a single line of text from the user. The line @code{readline}
+returns is allocated with @code{malloc ()}; you should @code{free ()}
+the line when you are done with it. The declaration for @code{readline}
+in ANSI C is
+
+@example
+@code{char *readline (char *@var{prompt});}
+@end example
+
+@noindent
+So, one might say
+@example
+@code{char *line = readline ("Enter a line: ");}
+@end example
+@noindent
+in order to read a line of text from the user.
+The line returned has the final newline removed, so only the
+text remains.
+
+If @code{readline} encounters an @code{EOF} while reading the line, and the
+line is empty at that point, then @code{(char *)NULL} is returned.
+Otherwise, the line is ended just as if a newline had been typed.
+
+If you want the user to be able to get at the line later, (with
+@key{C-p} for example), you must call @code{add_history ()} to save the
+line away in a @dfn{history} list of such lines.
+
+@example
+@code{add_history (line)};
+@end example
+
+@noindent
+For full details on the GNU History Library, see the associated manual.
+
+It is preferable to avoid saving empty lines on the history list, since
+users rarely have a burning need to reuse a blank line. Here is
+a function which usefully replaces the standard @code{gets ()} library
+function, and has the advantage of no static buffer to overflow:
+
+@example
+/* A static variable for holding the line. */
+static char *line_read = (char *)NULL;
+
+/* Read a string, and return a pointer to it. Returns NULL on EOF. */
+char *
+rl_gets ()
+@{
+ /* If the buffer has already been allocated, return the memory
+ to the free pool. */
+ if (line_read)
+ @{
+ free (line_read);
+ line_read = (char *)NULL;
+ @}
+
+ /* Get a line from the user. */
+ line_read = readline ("");
+
+ /* If the line has any text in it, save it on the history. */
+ if (line_read && *line_read)
+ add_history (line_read);
+
+ return (line_read);
+@}
+@end example
+
+This function gives the user the default behaviour of @key{TAB}
+completion: completion on file names. If you do not want Readline to
+complete on filenames, you can change the binding of the @key{TAB} key
+with @code{rl_bind_key ()}.
+
+@example
+@code{int rl_bind_key (int @var{key}, int (*@var{function})());}
+@end example
+
+@code{rl_bind_key ()} takes two arguments: @var{key} is the character that
+you want to bind, and @var{function} is the address of the function to
+call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()}
+makes @key{TAB} insert itself.
+@code{rl_bind_key ()} returns non-zero if @var{key} is not a valid
+ASCII character code (between 0 and 255).
+
+Thus, to disable the default @key{TAB} behavior, the following suffices:
+@example
+@code{rl_bind_key ('\t', rl_insert);}
+@end example
+
+This code should be executed once at the start of your program; you
+might write a function called @code{initialize_readline ()} which
+performs this and other desired initializations, such as installing
+custom completers (@pxref{Custom Completers}).
+
+@node Custom Functions
+@section Custom Functions
+
+Readline provides many functions for manipulating the text of
+the line, but it isn't possible to anticipate the needs of all
+programs. This section describes the various functions and variables
+defined within the Readline library which allow a user program to add
+customized functionality to Readline.
+
+@menu
+* The Function Type:: C declarations to make code readable.
+* Function Writing:: Variables and calling conventions.
+@end menu
+
+@node The Function Type
+@subsection The Function Type
+
+For readabilty, we declare a new type of object, called
+@dfn{Function}. A @code{Function} is a C function which
+returns an @code{int}. The type declaration for @code{Function} is:
+
+@noindent
+@code{typedef int Function ();}
+
+The reason for declaring this new type is to make it easier to write
+code describing pointers to C functions. Let us say we had a variable
+called @var{func} which was a pointer to a function. Instead of the
+classic C declaration
+
+@code{int (*)()func;}
+
+@noindent
+we may write
+
+@code{Function *func;}
+
+@noindent
+Similarly, there are
+
+@example
+typedef void VFunction ();
+typedef char *CPFunction (); @r{and}
+typedef char **CPPFunction ();
+@end example
+
+@noindent
+for functions returning no value, @code{pointer to char}, and
+@code{pointer to pointer to char}, respectively.
+
+@node Function Writing
+@subsection Writing a New Function
+
+In order to write new functions for Readline, you need to know the
+calling conventions for keyboard-invoked functions, and the names of the
+variables that describe the current state of the line read so far.
+
+The calling sequence for a command @code{foo} looks like
+
+@example
+@code{foo (int count, int key)}
+@end example
+
+@noindent
+where @var{count} is the numeric argument (or 1 if defaulted) and
+@var{key} is the key that invoked this function.
+
+It is completely up to the function as to what should be done with the
+numeric argument. Some functions use it as a repeat count, some
+as a flag, and others to choose alternate behavior (refreshing the current
+line as opposed to refreshing the screen, for example). Some choose to
+ignore it. In general, if a
+function uses the numeric argument as a repeat count, it should be able
+to do something useful with both negative and positive arguments.
+At the very least, it should be aware that it can be passed a
+negative argument.
+
+@node Readline Variables
+@section Readline Variables
+
+These variables are available to function writers.
+
+@deftypevar {char *} rl_line_buffer
+This is the line gathered so far. You are welcome to modify the
+contents of the line, but see @ref{Allowing Undoing}.
+@end deftypevar
+
+@deftypevar int rl_point
+The offset of the current cursor position in @code{rl_line_buffer}
+(the @emph{point}).
+@end deftypevar
+
+@deftypevar int rl_end
+The number of characters present in @code{rl_line_buffer}. When
+@code{rl_point} is at the end of the line, @code{rl_point} and
+@code{rl_end} are equal.
+@end deftypevar
+
+@deftypevar int rl_mark
+The mark (saved position) in the current line. If set, the mark
+and point define a @emph{region}.
+@end deftypevar
+
+@deftypevar int rl_done
+Setting this to a non-zero value causes Readline to return the current
+line immediately.
+@end deftypevar
+
+@deftypevar int rl_pending_input
+Setting this to a value makes it the next keystroke read. This is a
+way to stuff a single character into the input stream.
+@end deftypevar
+
+@deftypevar int rl_erase_empty_line
+Setting this to a non-zero value causes Readline to completely erase
+the current line, including any prompt, any time a newline is typed as
+the only character on an otherwise-empty line. The cursor is moved to
+the beginning of the newly-blank line.
+@end deftypevar
+
+@deftypevar {char *} rl_prompt
+The prompt Readline uses. This is set from the argument to
+@code{readline ()}, and should not be assigned to directly.
+@end deftypevar
+
+@deftypevar {char *} rl_library_version
+The version number of this revision of the library.
+@end deftypevar
+
+@deftypevar {char *} rl_terminal_name
+The terminal type, used for initialization.
+@end deftypevar
+
+@deftypevar {char *} rl_readline_name
+This variable is set to a unique name by each application using Readline.
+The value allows conditional parsing of the inputrc file
+(@pxref{Conditional Init Constructs}).
+@end deftypevar
+
+@deftypevar {FILE *} rl_instream
+The stdio stream from which Readline reads input.
+@end deftypevar
+
+@deftypevar {FILE *} rl_outstream
+The stdio stream to which Readline performs output.
+@end deftypevar
+
+@deftypevar {Function *} rl_startup_hook
+If non-zero, this is the address of a function to call just
+before @code{readline} prints the first prompt.
+@end deftypevar
+
+@deftypevar {Function *} rl_pre_input_hook
+If non-zero, this is the address of a function to call after
+the first prompt has been printed and just before @code{readline}
+starts reading input characters.
+@end deftypevar
+
+@deftypevar {Function *} rl_event_hook
+If non-zero, this is the address of a function to call periodically
+when readline is waiting for terminal input.
+@end deftypevar
+
+@deftypevar {Function *} rl_getc_function
+If non-zero, @code{readline} will call indirectly through this pointer
+to get a character from the input stream. By default, it is set to
+@code{rl_getc}, the default @code{readline} character input function
+(@pxref{Utility Functions}).
+@end deftypevar
+
+@deftypevar {VFunction *} rl_redisplay_function
+If non-zero, @code{readline} will call indirectly through this pointer
+to update the display with the current contents of the editing buffer.
+By default, it is set to @code{rl_redisplay}, the default @code{readline}
+redisplay function (@pxref{Redisplay}).
+@end deftypevar
+
+@deftypevar {Keymap} rl_executing_keymap
+This variable is set to the keymap (@pxref{Keymaps}) in which the
+currently executing readline function was found.
+@end deftypevar
+
+@deftypevar {Keymap} rl_binding_keymap
+This variable is set to the keymap (@pxref{Keymaps}) in which the
+last key binding occurred.
+@end deftypevar
+
+@node Readline Convenience Functions
+@section Readline Convenience Functions
+
+@menu
+* Function Naming:: How to give a function you write a name.
+* Keymaps:: Making keymaps.
+* Binding Keys:: Changing Keymaps.
+* Associating Function Names and Bindings:: Translate function names to
+ key sequences.
+* Allowing Undoing:: How to make your functions undoable.
+* Redisplay:: Functions to control line display.
+* Modifying Text:: Functions to modify @code{rl_line_buffer}.
+* Utility Functions:: Generally useful functions and hooks.
+* Alternate Interface:: Using Readline in a `callback' fashion.
+@end menu
+
+@node Function Naming
+@subsection Naming a Function
+
+The user can dynamically change the bindings of keys while using
+Readline. This is done by representing the function with a descriptive
+name. The user is able to type the descriptive name when referring to
+the function. Thus, in an init file, one might find
+
+@example
+Meta-Rubout: backward-kill-word
+@end example
+
+This binds the keystroke @key{Meta-Rubout} to the function
+@emph{descriptively} named @code{backward-kill-word}. You, as the
+programmer, should bind the functions you write to descriptive names as
+well. Readline provides a function for doing that:
+
+@deftypefun int rl_add_defun (char *name, Function *function, int key)
+Add @var{name} to the list of named functions. Make @var{function} be
+the function that gets called. If @var{key} is not -1, then bind it to
+@var{function} using @code{rl_bind_key ()}.
+@end deftypefun
+
+Using this function alone is sufficient for most applications. It is
+the recommended way to add a few functions to the default functions that
+Readline has built in. If you need to do something other
+than adding a function to Readline, you may need to use the
+underlying functions described below.
+
+@node Keymaps
+@subsection Selecting a Keymap
+
+Key bindings take place on a @dfn{keymap}. The keymap is the
+association between the keys that the user types and the functions that
+get run. You can make your own keymaps, copy existing keymaps, and tell
+Readline which keymap to use.
+
+@deftypefun Keymap rl_make_bare_keymap ()
+Returns a new, empty keymap. The space for the keymap is allocated with
+@code{malloc ()}; you should @code{free ()} it when you are done.
+@end deftypefun
+
+@deftypefun Keymap rl_copy_keymap (Keymap map)
+Return a new keymap which is a copy of @var{map}.
+@end deftypefun
+
+@deftypefun Keymap rl_make_keymap ()
+Return a new keymap with the printing characters bound to rl_insert,
+the lowercase Meta characters bound to run their equivalents, and
+the Meta digits bound to produce numeric arguments.
+@end deftypefun
+
+@deftypefun void rl_discard_keymap (Keymap keymap)
+Free the storage associated with @var{keymap}.
+@end deftypefun
+
+Readline has several internal keymaps. These functions allow you to
+change which keymap is active.
+
+@deftypefun Keymap rl_get_keymap ()
+Returns the currently active keymap.
+@end deftypefun
+
+@deftypefun void rl_set_keymap (Keymap keymap)
+Makes @var{keymap} the currently active keymap.
+@end deftypefun
+
+@deftypefun Keymap rl_get_keymap_by_name (char *name)
+Return the keymap matching @var{name}. @var{name} is one which would
+be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
+@end deftypefun
+
+@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
+Return the name matching @var{keymap}. @var{name} is one which would
+be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
+@end deftypefun
+
+@node Binding Keys
+@subsection Binding Keys
+
+You associate keys with functions through the keymap. Readline has
+several internal keymaps: @code{emacs_standard_keymap},
+@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
+@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
+@code{emacs_standard_keymap} is the default, and the examples in
+this manual assume that.
+
+These functions manage key bindings.
+
+@deftypefun int rl_bind_key (int key, Function *function)
+Binds @var{key} to @var{function} in the currently active keymap.
+Returns non-zero in the case of an invalid @var{key}.
+@end deftypefun
+
+@deftypefun int rl_bind_key_in_map (int key, Function *function, Keymap map)
+Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case
+of an invalid @var{key}.
+@end deftypefun
+
+@deftypefun int rl_unbind_key (int key)
+Bind @var{key} to the null function in the currently active keymap.
+Returns non-zero in case of error.
+@end deftypefun
+
+@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
+Bind @var{key} to the null function in @var{map}.
+Returns non-zero in case of error.
+@end deftypefun
+
+@deftypefun int rl_unbind_function_in_map (Function *function, Keymap map)
+Unbind all keys that execute @var{function} in @var{map}.
+@end deftypefun
+
+@deftypefun int rl_unbind_command_in_map (char *command, Keymap map)
+Unbind all keys that are bound to @var{command} in @var{map}.
+@end deftypefun
+
+@deftypefun int rl_generic_bind (int type, char *keyseq, char *data, Keymap map)
+Bind the key sequence represented by the string @var{keyseq} to the arbitrary
+pointer @var{data}. @var{type} says what kind of data is pointed to by
+@var{data}; this can be a function (@code{ISFUNC}), a macro
+(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
+necessary. The initial keymap in which to do bindings is @var{map}.
+@end deftypefun
+
+@deftypefun int rl_parse_and_bind (char *line)
+Parse @var{line} as if it had been read from the @code{inputrc} file and
+perform any key bindings and variable assignments found
+(@pxref{Readline Init File}).
+@end deftypefun
+
+@deftypefun int rl_read_init_file (char *filename)
+Read keybindings and variable assignments from @var{filename}
+(@pxref{Readline Init File}).
+@end deftypefun
+
+@node Associating Function Names and Bindings
+@subsection Associating Function Names and Bindings
+
+These functions allow you to find out what keys invoke named functions
+and the functions invoked by a particular key sequence.
+
+@deftypefun {Function *} rl_named_function (char *name)
+Return the function with name @var{name}.
+@end deftypefun
+
+@deftypefun {Function *} rl_function_of_keyseq (char *keyseq, Keymap map, int *type)
+Return the function invoked by @var{keyseq} in keymap @var{map}.
+If @var{map} is NULL, the current keymap is used. If @var{type} is
+not NULL, the type of the object is returned in it (one of @code{ISFUNC},
+@code{ISKMAP}, or @code{ISMACR}).
+@end deftypefun
+
+@deftypefun {char **} rl_invoking_keyseqs (Function *function)
+Return an array of strings representing the key sequences used to
+invoke @var{function} in the current keymap.
+@end deftypefun
+
+@deftypefun {char **} rl_invoking_keyseqs_in_map (Function *function, Keymap map)
+Return an array of strings representing the key sequences used to
+invoke @var{function} in the keymap @var{map}.
+@end deftypefun
+
+@deftypefun void rl_function_dumper (int readable)
+Print the readline function names and the key sequences currently
+bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
+the list is formatted in such a way that it can be made part of an
+@code{inputrc} file and re-read.
+@end deftypefun
+
+@deftypefun void rl_list_funmap_names ()
+Print the names of all bindable Readline functions to @code{rl_outstream}.
+@end deftypefun
+
+@node Allowing Undoing
+@subsection Allowing Undoing
+
+Supporting the undo command is a painless thing, and makes your
+functions much more useful. It is certainly easy to try
+something if you know you can undo it. I could use an undo function for
+the stock market.
+
+If your function simply inserts text once, or deletes text once, and
+uses @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
+undoing is already done for you automatically.
+
+If you do multiple insertions or multiple deletions, or any combination
+of these operations, you should group them together into one operation.
+This is done with @code{rl_begin_undo_group ()} and
+@code{rl_end_undo_group ()}.
+
+The types of events that can be undone are:
+
+@example
+enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
+@end example
+
+Notice that @code{UNDO_DELETE} means to insert some text, and
+@code{UNDO_INSERT} means to delete some text. That is, the undo code
+tells undo what to undo, not how to undo it. @code{UNDO_BEGIN} and
+@code{UNDO_END} are tags added by @code{rl_begin_undo_group ()} and
+@code{rl_end_undo_group ()}.
+
+@deftypefun int rl_begin_undo_group ()
+Begins saving undo information in a group construct. The undo
+information usually comes from calls to @code{rl_insert_text ()} and
+@code{rl_delete_text ()}, but could be the result of calls to
+@code{rl_add_undo ()}.
+@end deftypefun
+
+@deftypefun int rl_end_undo_group ()
+Closes the current undo group started with @code{rl_begin_undo_group
+()}. There should be one call to @code{rl_end_undo_group ()}
+for each call to @code{rl_begin_undo_group ()}.
+@end deftypefun
+
+@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
+Remember how to undo an event (according to @var{what}). The affected
+text runs from @var{start} to @var{end}, and encompasses @var{text}.
+@end deftypefun
+
+@deftypefun void free_undo_list ()
+Free the existing undo list.
+@end deftypefun
+
+@deftypefun int rl_do_undo ()
+Undo the first thing on the undo list. Returns @code{0} if there was
+nothing to undo, non-zero if something was undone.
+@end deftypefun
+
+Finally, if you neither insert nor delete text, but directly modify the
+existing text (e.g., change its case), call @code{rl_modifying ()}
+once, just before you modify the text. You must supply the indices of
+the text range that you are going to modify.
+
+@deftypefun int rl_modifying (int start, int end)
+Tell Readline to save the text between @var{start} and @var{end} as a
+single undo unit. It is assumed that you will subsequently modify
+that text.
+@end deftypefun
+
+@node Redisplay
+@subsection Redisplay
+
+@deftypefun void rl_redisplay ()
+Change what's displayed on the screen to reflect the current contents
+of @code{rl_line_buffer}.
+@end deftypefun
+
+@deftypefun int rl_forced_update_display ()
+Force the line to be updated and redisplayed, whether or not
+Readline thinks the screen display is correct.
+@end deftypefun
+
+@deftypefun int rl_on_new_line ()
+Tell the update routines that we have moved onto a new (empty) line,
+usually after ouputting a newline.
+@end deftypefun
+
+@deftypefun int rl_reset_line_state ()
+Reset the display state to a clean state and redisplay the current line
+starting on a new line.
+@end deftypefun
+
+@deftypefun int rl_message (va_alist)
+The arguments are a string as would be supplied to @code{printf}. The
+resulting string is displayed in the @dfn{echo area}. The echo area
+is also used to display numeric arguments and search strings.
+@end deftypefun
+
+@deftypefun int rl_clear_message ()
+Clear the message in the echo area.
+@end deftypefun
+
+@deftypefun void rl_save_prompt ()
+Save the local Readline prompt display state in preparation for
+displaying a new message in the message area with @code{rl_message}.
+@end deftypefun
+
+@deftypefun void rl_restore_prompt ()
+Restore the local Readline prompt display state saved by the most
+recent call to @code{rl_save_prompt}.
+@end deftypefun
+
+@node Modifying Text
+@subsection Modifying Text
+
+@deftypefun int rl_insert_text (char *text)
+Insert @var{text} into the line at the current cursor position.
+@end deftypefun
+
+@deftypefun int rl_delete_text (int start, int end)
+Delete the text between @var{start} and @var{end} in the current line.
+@end deftypefun
+
+@deftypefun {char *} rl_copy_text (int start, int end)
+Return a copy of the text between @var{start} and @var{end} in
+the current line.
+@end deftypefun
+
+@deftypefun int rl_kill_text (int start, int end)
+Copy the text between @var{start} and @var{end} in the current line
+to the kill ring, appending or prepending to the last kill if the
+last command was a kill command. The text is deleted.
+If @var{start} is less than @var{end},
+the text is appended, otherwise prepended. If the last command was
+not a kill, a new kill ring slot is used.
+@end deftypefun
+
+@node Utility Functions
+@subsection Utility Functions
+
+@deftypefun int rl_read_key ()
+Return the next character available. This handles input inserted into
+the input stream via @var{pending input} (@pxref{Readline Variables})
+and @code{rl_stuff_char ()}, macros, and characters read from the keyboard.
+@end deftypefun
+
+@deftypefun int rl_getc (FILE *)
+Return the next character available from the keyboard.
+@end deftypefun
+
+@deftypefun int rl_stuff_char (int c)
+Insert @var{c} into the Readline input stream. It will be "read"
+before Readline attempts to read characters from the terminal with
+@code{rl_read_key ()}.
+@end deftypefun
+
+@deftypefun rl_extend_line_buffer (int len)
+Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
+characters, possibly reallocating it if necessary.
+@end deftypefun
+
+@deftypefun int rl_initialize ()
+Initialize or re-initialize Readline's internal state.
+@end deftypefun
+
+@deftypefun int rl_reset_terminal (char *terminal_name)
+Reinitialize Readline's idea of the terminal settings using
+@var{terminal_name} as the terminal type (e.g., @code{vt100}).
+@end deftypefun
+
+@deftypefun int alphabetic (int c)
+Return 1 if @var{c} is an alphabetic character.
+@end deftypefun
+
+@deftypefun int numeric (int c)
+Return 1 if @var{c} is a numeric character.
+@end deftypefun
+
+@deftypefun int ding ()
+Ring the terminal bell, obeying the setting of @code{bell-style}.
+@end deftypefun
+
+@deftypefun void rl_display_match_list (char **matches, int len, int max)
+A convenience function for displaying a list of strings in
+columnar format on Readline's output stream. @code{matches} is the list
+of strings, in argv format, such as a list of completion matches.
+@code{len} is the number of strings in @code{matches}, and @code{max}
+is the length of the longest string in @code{matches}. This function uses
+the setting of @code{print-completions-horizontally} to select how the
+matches are displayed (@pxref{Readline Init File Syntax}).
+@end deftypefun
+
+The following are implemented as macros, defined in @code{chartypes.h}.
+
+@deftypefun int uppercase_p (int c)
+Return 1 if @var{c} is an uppercase alphabetic character.
+@end deftypefun
+
+@deftypefun int lowercase_p (int c)
+Return 1 if @var{c} is a lowercase alphabetic character.
+@end deftypefun
+
+@deftypefun int digit_p (int c)
+Return 1 if @var{c} is a numeric character.
+@end deftypefun
+
+@deftypefun int to_upper (int c)
+If @var{c} is a lowercase alphabetic character, return the corresponding
+uppercase character.
+@end deftypefun
+
+@deftypefun int to_lower (int c)
+If @var{c} is an uppercase alphabetic character, return the corresponding
+lowercase character.
+@end deftypefun
+
+@deftypefun int digit_value (int c)
+If @var{c} is a number, return the value it represents.
+@end deftypefun
+
+@node Alternate Interface
+@subsection Alternate Interface
+
+An alternate interface is available to plain @code{readline()}. Some
+applications need to interleave keyboard I/O with file, device, or
+window system I/O, typically by using a main loop to @code{select()}
+on various file descriptors. To accomodate this need, readline can
+also be invoked as a `callback' function from an event loop. There
+are functions available to make this easy.
+
+@deftypefun void rl_callback_handler_install (char *prompt, Vfunction *lhandler)
+Set up the terminal for readline I/O and display the initial
+expanded value of @var{prompt}. Save the value of @var{lhandler} to
+use as a callback when a complete line of input has been entered.
+@end deftypefun
+
+@deftypefun void rl_callback_read_char ()
+Whenever an application determines that keyboard input is available, it
+should call @code{rl_callback_read_char()}, which will read the next
+character from the current input source. If that character completes the
+line, @code{rl_callback_read_char} will invoke the @var{lhandler}
+function saved by @code{rl_callback_handler_install} to process the
+line. @code{EOF} is indicated by calling @var{lhandler} with a
+@code{NULL} line.
+@end deftypefun
+
+@deftypefun void rl_callback_handler_remove ()
+Restore the terminal to its initial state and remove the line handler.
+This may be called from within a callback as well as independently.
+@end deftypefun
+
+@subsection An Example
+
+Here is a function which changes lowercase characters to their uppercase
+equivalents, and uppercase characters to lowercase. If
+this function was bound to @samp{M-c}, then typing @samp{M-c} would
+change the case of the character under point. Typing @samp{M-1 0 M-c}
+would change the case of the following 10 characters, leaving the cursor on
+the last character changed.
+
+@example
+/* Invert the case of the COUNT following characters. */
+int
+invert_case_line (count, key)
+ int count, key;
+@{
+ register int start, end, i;
+
+ start = rl_point;
+
+ if (rl_point >= rl_end)
+ return (0);
+
+ if (count < 0)
+ @{
+ direction = -1;
+ count = -count;
+ @}
+ else
+ direction = 1;
+
+ /* Find the end of the range to modify. */
+ end = start + (count * direction);
+
+ /* Force it to be within range. */
+ if (end > rl_end)
+ end = rl_end;
+ else if (end < 0)
+ end = 0;
+
+ if (start == end)
+ return (0);
+
+ if (start > end)
+ @{
+ int temp = start;
+ start = end;
+ end = temp;
+ @}
+
+ /* Tell readline that we are modifying the line, so it will save
+ the undo information. */
+ rl_modifying (start, end);
+
+ for (i = start; i != end; i++)
+ @{
+ if (uppercase_p (rl_line_buffer[i]))
+ rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
+ else if (lowercase_p (rl_line_buffer[i]))
+ rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
+ @}
+ /* Move point to on top of the last character changed. */
+ rl_point = (direction == 1) ? end - 1 : start;
+ return (0);
+@}
+@end example
+
+@node Readline Signal Handling
+@section Readline Signal Handling
+
+Signals are asynchronous events sent to a process by the Unix kernel,
+sometimes on behalf of another process. They are intended to indicate
+exceptional events, like a user pressing the interrupt key on his
+terminal, or a network connection being broken. There is a class of
+signals that can be sent to the process currently reading input from
+the keyboard. Since Readline changes the terminal attributes when it
+is called, it needs to perform special processing when a signal is
+received to restore the terminal to a sane state, or provide application
+writers with functions to do so manually.
+
+Readline contains an internal signal handler that is installed for a
+number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
+@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
+When one of these signals is received, the signal handler
+will reset the terminal attributes to those that were in effect before
+@code{readline ()} was called, reset the signal handling to what it was
+before @code{readline ()} was called, and resend the signal to the calling
+application.
+If and when the calling application's signal handler returns, Readline
+will reinitialize the terminal and continue to accept input.
+When a @code{SIGINT} is received, the Readline signal handler performs
+some additional work, which will cause any partially-entered line to be
+aborted (see the description of @code{rl_free_line_state ()}).
+
+There is an additional Readline signal handler, for @code{SIGWINCH}, which
+the kernel sends to a process whenever the terminal's size changes (for
+example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
+handler updates Readline's internal screen size state, and then calls any
+@code{SIGWINCH} signal handler the calling application has installed.
+Readline calls the application's @code{SIGWINCH} signal handler without
+resetting the terminal to its original state. If the application's signal
+handler does more than update its idea of the terminal size and return (for
+example, a @code{longjmp} back to a main processing loop), it @emph{must}
+call @code{rl_cleanup_after_signal ()} (described below), to restore the
+terminal state.
+
+Readline provides two variables that allow application writers to
+control whether or not it will catch certain signals and act on them
+when they are received. It is important that applications change the
+values of these variables only when calling @code{readline ()}, not in
+a signal handler, so Readline's internal signal state is not corrupted.
+
+@deftypevar int rl_catch_signals
+If this variable is non-zero, Readline will install signal handlers for
+@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
+@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
+
+The default value of @code{rl_catch_signals} is 1.
+@end deftypevar
+
+@deftypevar int rl_catch_sigwinch
+If this variable is non-zero, Readline will install a signal handler for
+@code{SIGWINCH}.
+
+The default value of @code{rl_catch_sigwinch} is 1.
+@end deftypevar
+
+If an application does not wish to have Readline catch any signals, or
+to handle signals other than those Readline catches (@code{SIGHUP},
+for example),
+Readline provides convenience functions to do the necessary terminal
+and internal state cleanup upon receipt of a signal.
+
+@deftypefun void rl_cleanup_after_signal (void)
+This function will reset the state of the terminal to what it was before
+@code{readline ()} was called, and remove the Readline signal handlers for
+all signals, depending on the values of @code{rl_catch_signals} and
+@code{rl_catch_sigwinch}.
+@end deftypefun
+
+@deftypefun void rl_free_line_state (void)
+This will free any partial state associated with the current input line
+(undo information, any partial history entry, any partially-entered
+keyboard macro, and any partially-entered numeric argument). This
+should be called before @code{rl_cleanup_after_signal ()}. The
+Readline signal handler for @code{SIGINT} calls this to abort the
+current input line.
+@end deftypefun
+
+@deftypefun void rl_reset_after_signal (void)
+This will reinitialize the terminal and reinstall any Readline signal
+handlers, depending on the values of @code{rl_catch_signals} and
+@code{rl_catch_sigwinch}.
+@end deftypefun
+
+If an application does not wish Readline to catch @code{SIGWINCH}, it may
+call @code{rl_resize_terminal ()} to force Readline to update its idea of
+the terminal size when a @code{SIGWINCH} is received.
+
+@deftypefun void rl_resize_terminal (void)
+Update Readline's internal screen size.
+@end deftypefun
+
+The following functions install and remove Readline's signal handlers.
+
+@deftypefun int rl_set_signals (void)
+Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
+@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
+@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
+@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
+@end deftypefun
+
+@deftypefun int rl_clear_signals (void)
+Remove all of the Readline signal handlers installed by
+@code{rl_set_signals ()}.
+@end deftypefun
+
+@node Custom Completers
+@section Custom Completers
+
+Typically, a program that reads commands from the user has a way of
+disambiguating commands and data. If your program is one of these, then
+it can provide completion for commands, data, or both.
+The following sections describe how your program and Readline
+cooperate to provide this service.
+
+@menu
+* How Completing Works:: The logic used to do completion.
+* Completion Functions:: Functions provided by Readline.
+* Completion Variables:: Variables which control completion.
+* A Short Completion Example:: An example of writing completer subroutines.
+@end menu
+
+@node How Completing Works
+@subsection How Completing Works
+
+In order to complete some text, the full list of possible completions
+must be available. That is, it is not possible to accurately
+expand a partial word without knowing all of the possible words
+which make sense in that context. The Readline library provides
+the user interface to completion, and two of the most common
+completion functions: filename and username. For completing other types
+of text, you must write your own completion function. This section
+describes exactly what such functions must do, and provides an example.
+
+There are three major functions used to perform completion:
+
+@enumerate
+@item
+The user-interface function @code{rl_complete ()}. This function is
+called with the same arguments as other Readline
+functions intended for interactive use: @var{count} and
+@var{invoking_key}. It isolates the word to be completed and calls
+@code{completion_matches ()} to generate a list of possible completions.
+It then either lists the possible completions, inserts the possible
+completions, or actually performs the
+completion, depending on which behavior is desired.
+
+@item
+The internal function @code{completion_matches ()} uses your
+@dfn{generator} function to generate the list of possible matches, and
+then returns the array of these matches. You should place the address
+of your generator function in @code{rl_completion_entry_function}.
+
+@item
+The generator function is called repeatedly from
+@code{completion_matches ()}, returning a string each time. The
+arguments to the generator function are @var{text} and @var{state}.
+@var{text} is the partial word to be completed. @var{state} is zero the
+first time the function is called, allowing the generator to perform
+any necessary initialization, and a positive non-zero integer for
+each subsequent call. When the generator function returns
+@code{(char *)NULL} this signals @code{completion_matches ()} that there are
+no more possibilities left. Usually the generator function computes the
+list of possible completions when @var{state} is zero, and returns them
+one at a time on subsequent calls. Each string the generator function
+returns as a match must be allocated with @code{malloc()}; Readline
+frees the strings when it has finished with them.
+
+@end enumerate
+
+@deftypefun int rl_complete (int ignore, int invoking_key)
+Complete the word at or before point. You have supplied the function
+that does the initial simple matching selection algorithm (see
+@code{completion_matches ()}). The default is to do filename completion.
+@end deftypefun
+
+@deftypevar {Function *} rl_completion_entry_function
+This is a pointer to the generator function for @code{completion_matches
+()}. If the value of @code{rl_completion_entry_function} is
+@code{(Function *)NULL} then the default filename generator function,
+@code{filename_completion_function ()}, is used.
+@end deftypevar
+
+@node Completion Functions
+@subsection Completion Functions
+
+Here is the complete list of callable completion functions present in
+Readline.
+
+@deftypefun int rl_complete_internal (int what_to_do)
+Complete the word at or before point. @var{what_to_do} says what to do
+with the completion. A value of @samp{?} means list the possible
+completions. @samp{TAB} means do standard completion. @samp{*} means
+insert all of the possible completions. @samp{!} means to display
+all of the possible completions, if there is more than one, as well as
+performing partial completion.
+@end deftypefun
+
+@deftypefun int rl_complete (int ignore, int invoking_key)
+Complete the word at or before point. You have supplied the function
+that does the initial simple matching selection algorithm (see
+@code{completion_matches ()} and @code{rl_completion_entry_function}).
+The default is to do filename
+completion. This calls @code{rl_complete_internal ()} with an
+argument depending on @var{invoking_key}.
+@end deftypefun
+
+@deftypefun int rl_possible_completions (int count, int invoking_key))
+List the possible completions. See description of @code{rl_complete
+()}. This calls @code{rl_complete_internal ()} with an argument of
+@samp{?}.
+@end deftypefun
+
+@deftypefun int rl_insert_completions (int count, int invoking_key))
+Insert the list of possible completions into the line, deleting the
+partially-completed word. See description of @code{rl_complete ()}.
+This calls @code{rl_complete_internal ()} with an argument of @samp{*}.
+@end deftypefun
+
+@deftypefun {char **} completion_matches (char *text, CPFunction *entry_func)
+Returns an array of @code{(char *)} which is a list of completions for
+@var{text}. If there are no completions, returns @code{(char **)NULL}.
+The first entry in the returned array is the substitution for @var{text}.
+The remaining entries are the possible completions. The array is
+terminated with a @code{NULL} pointer.
+
+@var{entry_func} is a function of two args, and returns a
+@code{(char *)}. The first argument is @var{text}. The second is a
+state argument; it is zero on the first call, and non-zero on subsequent
+calls. @var{entry_func} returns a @code{NULL} pointer to the caller
+when there are no more matches.
+@end deftypefun
+
+@deftypefun {char *} filename_completion_function (char *text, int state)
+A generator function for filename completion in the general case. Note
+that completion in Bash is a little different because of all
+the pathnames that must be followed when looking up completions for a
+command. The Bash source is a useful reference for writing custom
+completion functions.
+@end deftypefun
+
+@deftypefun {char *} username_completion_function (char *text, int state)
+A completion generator for usernames. @var{text} contains a partial
+username preceded by a random character (usually @samp{~}). As with all
+completion generators, @var{state} is zero on the first call and non-zero
+for subsequent calls.
+@end deftypefun
+
+@node Completion Variables
+@subsection Completion Variables
+
+@deftypevar {Function *} rl_completion_entry_function
+A pointer to the generator function for @code{completion_matches ()}.
+@code{NULL} means to use @code{filename_entry_function ()}, the default
+filename completer.
+@end deftypevar
+
+@deftypevar {CPPFunction *} rl_attempted_completion_function
+A pointer to an alternative function to create matches.
+The function is called with @var{text}, @var{start}, and @var{end}.
+@var{start} and @var{end} are indices in @code{rl_line_buffer} saying
+what the boundaries of @var{text} are. If this function exists and
+returns @code{NULL}, or if this variable is set to @code{NULL}, then
+@code{rl_complete ()} will call the value of
+@code{rl_completion_entry_function} to generate matches, otherwise the
+array of strings returned will be used.
+@end deftypevar
+
+@deftypevar {CPFunction *} rl_filename_quoting_function
+A pointer to a function that will quote a filename in an application-
+specific fashion. This is called if filename completion is being
+attempted and one of the characters in @code{rl_filename_quote_characters}
+appears in a completed filename. The function is called with
+@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
+is the filename to be quoted. The @var{match_type} is either
+@code{SINGLE_MATCH}, if there is only one completion match, or
+@code{MULT_MATCH}. Some functions use this to decide whether or not to
+insert a closing quote character. The @var{quote_pointer} is a pointer
+to any opening quote character the user typed. Some functions choose
+to reset this character.
+@end deftypevar
+
+@deftypevar {CPFunction *} rl_filename_dequoting_function
+A pointer to a function that will remove application-specific quoting
+characters from a filename before completion is attempted, so those
+characters do not interfere with matching the text against names in
+the filesystem. It is called with @var{text}, the text of the word
+to be dequoted, and @var{quote_char}, which is the quoting character
+that delimits the filename (usually @samp{'} or @samp{"}). If
+@var{quote_char} is zero, the filename was not in an embedded string.
+@end deftypevar
+
+@deftypevar {Function *} rl_char_is_quoted_p
+A pointer to a function to call that determines whether or not a specific
+character in the line buffer is quoted, according to whatever quoting
+mechanism the program calling readline uses. The function is called with
+two arguments: @var{text}, the text of the line, and @var{index}, the
+index of the character in the line. It is used to decide whether a
+character found in @code{rl_completer_word_break_characters} should be
+used to break words for the completer.
+@end deftypevar
+
+@deftypevar int rl_completion_query_items
+Up to this many items will be displayed in response to a
+possible-completions call. After that, we ask the user if she is sure
+she wants to see them all. The default value is 100.
+@end deftypevar
+
+@deftypevar {char *} rl_basic_word_break_characters
+The basic list of characters that signal a break between words for the
+completer routine. The default value of this variable is the characters
+which break words for completion in Bash, i.e.,
+@code{" \t\n\"\\'`@@$><=;|&@{("}.
+@end deftypevar
+
+@deftypevar {char *} rl_basic_quote_characters
+List of quote characters which can cause a word break.
+@end deftypevar
+
+@deftypevar {char *} rl_completer_word_break_characters
+The list of characters that signal a break between words for
+@code{rl_complete_internal ()}. The default list is the value of
+@code{rl_basic_word_break_characters}.
+@end deftypevar
+
+@deftypevar {char *} rl_completer_quote_characters
+List of characters which can be used to quote a substring of the line.
+Completion occurs on the entire substring, and within the substring
+@code{rl_completer_word_break_characters} are treated as any other character,
+unless they also appear within this list.
+@end deftypevar
+
+@deftypevar {char *} rl_filename_quote_characters
+A list of characters that cause a filename to be quoted by the completer
+when they appear in a completed filename. The default is the null string.
+@end deftypevar
+
+@deftypevar {char *} rl_special_prefixes
+The list of characters that are word break characters, but should be
+left in @var{text} when it is passed to the completion function.
+Programs can use this to help determine what kind of completing to do.
+For instance, Bash sets this variable to "$@@" so that it can complete
+shell variables and hostnames.
+@end deftypevar
+
+@deftypevar {int} rl_completion_append_character
+When a single completion alternative matches at the end of the command
+line, this character is appended to the inserted completion text. The
+default is a space character (@samp{ }). Setting this to the null
+character (@samp{\0}) prevents anything being appended automatically.
+This can be changed in custom completion functions to
+provide the ``most sensible word separator character'' according to
+an application-specific command line syntax specification.
+@end deftypevar
+
+@deftypevar int rl_ignore_completion_duplicates
+If non-zero, then disallow duplicates in the matches. Default is 1.
+@end deftypevar
+
+@deftypevar int rl_filename_completion_desired
+Non-zero means that the results of the matches are to be treated as
+filenames. This is @emph{always} zero on entry, and can only be changed
+within a completion entry generator function. If it is set to a non-zero
+value, directory names have a slash appended and Readline attempts to
+quote completed filenames if they contain any embedded word break
+characters.
+@end deftypevar
+
+@deftypevar int rl_filename_quoting_desired
+Non-zero means that the results of the matches are to be quoted using
+double quotes (or an application-specific quoting mechanism) if the
+completed filename contains any characters in
+@code{rl_filename_quote_chars}. This is @emph{always} non-zero
+on entry, and can only be changed within a completion entry generator
+function. The quoting is effected via a call to the function pointed to
+by @code{rl_filename_quoting_function}.
+@end deftypevar
+
+@deftypevar int rl_inhibit_completion
+If this variable is non-zero, completion is inhibit
+#include
+#include
+#include
+#include
+
+#include
+#include
+
+extern char *getwd ();
+extern char *xmalloc ();
+
+/* The names of functions that actually do the manipulation. */
+int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
+int com_delete (), com_help (), com_cd (), com_quit ();
+
+/* A structure which contains information on the commands this program
+ can understand. */
+
+typedef struct @{
+ char *name; /* User printable name of the function. */
+ Function *func; /* Function to call to do the job. */
+ char *doc; /* Documentation for this function. */
+@} COMMAND;
+
+COMMAND commands[] = @{
+ @{ "cd", com_cd, "Change to directory DIR" @},
+ @{ "delete", com_delete, "Delete FILE" @},
+ @{ "help", com_help, "Display this text" @},
+ @{ "?", com_help, "Synonym for `help'" @},
+ @{ "list", com_list, "List files in DIR" @},
+ @{ "ls", com_list, "Synonym for `list'" @},
+ @{ "pwd", com_pwd, "Print the current working directory" @},
+ @{ "quit", com_quit, "Quit using Fileman" @},
+ @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
+ @{ "stat", com_stat, "Print out statistics on FILE" @},
+ @{ "view", com_view, "View the contents of FILE" @},
+ @{ (char *)NULL, (Function *)NULL, (char *)NULL @}
+@};
+
+/* Forward declarations. */
+char *stripwhite ();
+COMMAND *find_command ();
+
+/* The name of this program, as taken from argv[0]. */
+char *progname;
+
+/* When non-zero, this global means the user is done using this program. */
+int done;
+
+char *
+dupstr (s)
+ int s;
+@{
+ char *r;
+
+ r = xmalloc (strlen (s) + 1);
+ strcpy (r, s);
+ return (r);
+@}
+
+main (argc, argv)
+ int argc;
+ char **argv;
+@{
+ char *line, *s;
+
+ progname = argv[0];
+
+ initialize_readline (); /* Bind our completer. */
+
+ /* Loop reading and executing lines until the user quits. */
+ for ( ; done == 0; )
+ @{
+ line = readline ("FileMan: ");
+
+ if (!line)
+ break;
+
+ /* Remove leading and trailing whitespace from the line.
+ Then, if there is anything left, add it to the history list
+ and execute it. */
+ s = stripwhite (line);
+
+ if (*s)
+ @{
+ add_history (s);
+ execute_line (s);
+ @}
+
+ free (line);
+ @}
+ exit (0);
+@}
+
+/* Execute a command line. */
+int
+execute_line (line)
+ char *line;
+@{
+ register int i;
+ COMMAND *command;
+ char *word;
+
+ /* Isolate the command word. */
+ i = 0;
+ while (line[i] && whitespace (line[i]))
+ i++;
+ word = line + i;
+
+ while (line[i] && !whitespace (line[i]))
+ i++;
+
+ if (line[i])
+ line[i++] = '\0';
+
+ command = find_command (word);
+
+ if (!command)
+ @{
+ fprintf (stderr, "%s: No such command for FileMan.\n", word);
+ return (-1);
+ @}
+
+ /* Get argument to command, if any. */
+ while (whitespace (line[i]))
+ i++;
+
+ word = line + i;
+
+ /* Call the function. */
+ return ((*(command->func)) (word));
+@}
+
+/* Look up NAME as the name of a command, and return a pointer to that
+ command. Return a NULL pointer if NAME isn't a command name. */
+COMMAND *
+find_command (name)
+ char *name;
+@{
+ register int i;
+
+ for (i = 0; commands[i].name; i++)
+ if (strcmp (name, commands[i].name) == 0)
+ return (&commands[i]);
+
+ return ((COMMAND *)NULL);
+@}
+
+/* Strip whitespace from the start and end of STRING. Return a pointer
+ into STRING. */
+char *
+stripwhite (string)
+ char *string;
+@{
+ register char *s, *t;
+
+ for (s = string; whitespace (*s); s++)
+ ;
+
+ if (*s == 0)
+ return (s);
+
+ t = s + strlen (s) - 1;
+ while (t > s && whitespace (*t))
+ t--;
+ *++t = '\0';
+
+ return s;
+@}
+
+/* **************************************************************** */
+/* */
+/* Interface to Readline Completion */
+/* */
+/* **************************************************************** */
+
+char *command_generator ();
+char **fileman_completion ();
+
+/* Tell the GNU Readline library how to complete. We want to try to complete
+ on command names if this is the first word in the line, or on filenames
+ if not. */
+initialize_readline ()
+@{
+ /* Allow conditional parsing of the ~/.inputrc file. */
+ rl_readline_name = "FileMan";
+
+ /* Tell the completer that we want a crack first. */
+ rl_attempted_completion_function = (CPPFunction *)fileman_completion;
+@}
+
+/* Attempt to complete on the contents of TEXT. START and END bound the
+ region of rl_line_buffer that contains the word to complete. TEXT is
+ the word to complete. We can use the entire contents of rl_line_buffer
+ in case we want to do some simple parsing. Return the array of matches,
+ or NULL if there aren't any. */
+char **
+fileman_completion (text, start, end)
+ char *text;
+ int start, end;
+@{
+ char **matches;
+
+ matches = (char **)NULL;
+
+ /* If this word is at the start of the line, then it is a command
+ to complete. Otherwise it is the name of a file in the current
+ directory. */
+ if (start == 0)
+ matches = completion_matches (text, command_generator);
+
+ return (matches);
+@}
+
+/* Generator function for command completion. STATE lets us know whether
+ to start from scratch; without any state (i.e. STATE == 0), then we
+ start at the top of the list. */
+char *
+command_generator (text, state)
+ char *text;
+ int state;
+@{
+ static int list_index, len;
+ char *name;
+
+ /* If this is a new word to complete, initialize now. This includes
+ saving the length of TEXT for efficiency, and initializing the index
+ variable to 0. */
+ if (!state)
+ @{
+ list_index = 0;
+ len = strlen (text);
+ @}
+
+ /* Return the next name which partially matches from the command list. */
+ while (name = commands[list_index].name)
+ @{
+ list_index++;
+
+ if (strncmp (name, text, len) == 0)
+ return (dupstr(name));
+ @}
+
+ /* If no names matched, then return NULL. */
+ return ((char *)NULL);
+@}
+
+/* **************************************************************** */
+/* */
+/* FileMan Commands */
+/* */
+/* **************************************************************** */
+
+/* String to pass to system (). This is for the LIST, VIEW and RENAME
+ commands. */
+static char syscom[1024];
+
+/* List the file(s) named in arg. */
+com_list (arg)
+ char *arg;
+@{
+ if (!arg)
+ arg = "";
+
+ sprintf (syscom, "ls -FClg %s", arg);
+ return (system (syscom));
+@}
+
+com_view (arg)
+ char *arg;
+@{
+ if (!valid_argument ("view", arg))
+ return 1;
+
+ sprintf (syscom, "more %s", arg);
+ return (system (syscom));
+@}
+
+com_rename (arg)
+ char *arg;
+@{
+ too_dangerous ("rename");
+ return (1);
+@}
+
+com_stat (arg)
+ char *arg;
+@{
+ struct stat finfo;
+
+ if (!valid_argument ("stat", arg))
+ return (1);
+
+ if (stat (arg, &finfo) == -1)
+ @{
+ perror (arg);
+ return (1);
+ @}
+
+ printf ("Statistics for `%s':\n", arg);
+
+ printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
+ finfo.st_nlink,
+ (finfo.st_nlink == 1) ? "" : "s",
+ finfo.st_size,
+ (finfo.st_size == 1) ? "" : "s");
+ printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
+ printf (" Last access at: %s", ctime (&finfo.st_atime));
+ printf (" Last modified at: %s", ctime (&finfo.st_mtime));
+ return (0);
+@}
+
+com_delete (arg)
+ char *arg;
+@{
+ too_dangerous ("delete");
+ return (1);
+@}
+
+/* Print out help for ARG, or for all of the commands if ARG is
+ not present. */
+com_help (arg)
+ char *arg;
+@{
+ register int i;
+ int printed = 0;
+
+ for (i = 0; commands[i].name; i++)
+ @{
+ if (!*arg || (strcmp (arg, commands[i].name) == 0))
+ @{
+ printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
+ printed++;
+ @}
+ @}
+
+ if (!printed)
+ @{
+ printf ("No commands match `%s'. Possibilties are:\n", arg);
+
+ for (i = 0; commands[i].name; i++)
+ @{
+ /* Print in six columns. */
+ if (printed == 6)
+ @{
+ printed = 0;
+ printf ("\n");
+ @}
+
+ printf ("%s\t", commands[i].name);
+ printed++;
+ @}
+
+ if (printed)
+ printf ("\n");
+ @}
+ return (0);
+@}
+
+/* Change to the directory ARG. */
+com_cd (arg)
+ char *arg;
+@{
+ if (chdir (arg) == -1)
+ @{
+ perror (arg);
+ return 1;
+ @}
+
+ com_pwd ("");
+ return (0);
+@}
+
+/* Print out the current working directory. */
+com_pwd (ignore)
+ char *ignore;
+@{
+ char dir[1024], *s;
+
+ s = getwd (dir);
+ if (s == 0)
+ @{
+ printf ("Error getting pwd: %s\n", dir);
+ return 1;
+ @}
+
+ printf ("Current directory is %s\n", dir);
+ return 0;
+@}
+
+/* The user wishes to quit using this program. Just set DONE non-zero. */
+com_quit (arg)
+ char *arg;
+@{
+ done = 1;
+ return (0);
+@}
+
+/* Function which tells you that you can't do this. */
+too_dangerous (caller)
+ char *caller;
+@{
+ fprintf (stderr,
+ "%s: Too dangerous for me to distribute. Write it yourself.\n",
+ caller);
+@}
+
+/* Return non-zero if ARG is a valid argument for CALLER, else print
+ an error message and return zero. */
+int
+valid_argument (caller, arg)
+ char *caller, *arg;
+@{
+ if (!arg || !*arg)
+ @{
+ fprintf (stderr, "%s: Argument required.\n", caller);
+ return (0);
+ @}
+
+ return (1);
+@}
+@end smallexample
Index: texi2dvi
===================================================================
--- texi2dvi (nonexistent)
+++ texi2dvi (revision 1765)
@@ -0,0 +1,362 @@
+#! /bin/sh
+# texi2dvi --- smartly produce DVI files from texinfo sources
+# $Id: texi2dvi,v 1.1.1.1 2001-05-18 11:22:18 markom Exp $
+#
+# Copyright (C) 1992, 93, 94, 95, 96, 97, 98 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, you can either send email to this
+# program's maintainer or write to: The Free Software Foundation,
+# Inc.; 59 Temple Place, Suite 330; Boston, MA 02111-1307, USA.
+#
+# Commentary:
+#
+# Author: Noah Friedman
+#
+# Please send bug reports, etc. to bug-texinfo@gnu.org.
+# If possible, please send a copy of the output of the script called with
+# the `--debug' option when making a bug report.
+#
+# In the interest of general portability, some common bourne shell
+# constructs were avoided because they weren't guaranteed to be available
+# in some earlier implementations. I've tried to make this program as
+# portable as possible. Welcome to unix, where the lowest common
+# denominator is rapidly diminishing.
+#
+# Among the more interesting lossages I noticed among Bourne shells:
+# * No shell functions.
+# * No `unset' builtin.
+# * `shift' cannot take a numeric argument, and signals an error if
+# there are no arguments to shift.
+#
+# Code:
+
+# Name by which this script was invoked.
+progname=`echo "$0" | sed -e 's/[^\/]*\///g'`
+
+# This string is expanded by rcs automatically when this file is checked out.
+rcs_revision='$Revision: 1.1.1.1 $'
+version=`set - $rcs_revision; echo $2`
+
+# To prevent hairy quoting and escaping later.
+bq='`'
+eq="'"
+
+usage="Usage: $0 [OPTION]... FILE...
+Run a Texinfo document through TeX.
+
+Options:
+-b, --batch No interaction (\nonstopmode in TeX).
+-c, --clean Remove all auxiliary files.
+-D, --debug Turn on shell debugging ($bq${bq}set -x$eq$eq).
+-t, --texinfo CMD Insert CMD after @setfilename before running TeX.
+--verbose Report on what is done.
+-h, --help Display this help and exit.
+-v, --version Display version information and exit.
+
+The values of the TEX, TEXINDEX, and MAKEINFO environment variables are
+used to run those commands, if they are set.
+
+Email bug reports to bug-texinfo@gnu.org."
+
+# Initialize variables.
+# Don't use `unset' since old bourne shells don't have this command.
+# Instead, assign them an empty value.
+# Some of these, like TEX and TEXINDEX, may be inherited from the environment.
+backup_extension=.bak # these files get deleted if all goes well.
+batch=
+clean=
+debug=
+orig_pwd="`pwd`"
+textra=
+verbose=false
+makeinfo="${MAKEINFO-makeinfo}"
+texindex="${TEXINDEX-texindex}"
+tex="${TEX-tex}"
+
+# Save this so we can construct a new TEXINPUTS path for each file.
+TEXINPUTS_orig="$TEXINPUTS"
+export TEXINPUTS
+
+# Parse command line arguments.
+# Make sure that all wildcarded options are long enough to be unambiguous.
+# It's a good idea to document the full long option name in each case.
+# Long options which take arguments will need a `*' appended to the
+# canonical name to match the value appended after the `=' character.
+while :; do
+ test $# -eq 0 && break
+
+ case "$1" in
+ -b | --batch | --b* ) batch=t; shift ;;
+ -c | --clean | --c* ) clean=t; shift ;;
+ -D | --debug | --d* ) debug=t; shift ;;
+ -h | --help | --h* ) echo "$usage"; exit 0 ;;
+ # OK, we should do real option parsing here, but be lazy for now.
+ -t | --texinfo | --t*) shift; textra="$textra $1"; shift ;;
+ -v | --vers* )
+ echo "$progname (GNU Texinfo 3.12) $version"
+ echo "Copyright (C) 1998 Free Software Foundation, Inc.
+There is NO warranty. You may redistribute this software
+under the terms of the GNU General Public License.
+For more information about these matters, see the files named COPYING."
+ exit 0 ;;
+ --verb* ) verbose=echo; shift ;;
+ -- ) # Stop option processing
+ shift
+ break ;;
+ -* )
+ case "$1" in
+ --*=* ) arg=`echo "$1" | sed -e 's/=.*//'` ;;
+ * ) arg="$1" ;;
+ esac
+ exec 1>&2
+ echo "$progname: Unknown or ambiguous option $bq$arg$eq."
+ echo "$progname: Try $bq--help$eq for more information."
+ exit 1 ;;
+ * ) break ;;
+ esac
+done
+
+# See if there are any command line args left (which will be interpreted as
+# filename arguments).
+if test $# -eq 0; then
+ exec 1>&2
+ echo "$progname: At least one file name is required as an argument."
+ echo "$progname: Try $bq--help$eq for more information."
+ exit 2
+fi
+
+test "$debug" = t && set -x
+
+# Texify files
+for command_line_filename in ${1+"$@"}; do
+ $verbose "Processing $command_line_filename ..."
+
+ # See if file exists. If it doesn't we're in trouble since, even
+ # though the user may be able to reenter a valid filename at the tex
+ # prompt (assuming they're attending the terminal), this script won't
+ # be able to find the right index files and so forth.
+ if test ! -r "${command_line_filename}"; then
+ echo "$0: Could not read ${command_line_filename}." >&2
+ continue
+ fi
+
+ # Roughly equivalent to `dirname ...`, but more portable
+ directory="`echo ${command_line_filename} | sed 's/\/[^\/]*$//'`"
+ filename_texi="`basename ${command_line_filename}`"
+ # Strip off the last extension part (probably .texinfo or .texi)
+ filename_noext="`echo ${filename_texi} | sed 's/\.[^.]*$//'`"
+
+ # Use same basename since we want to generate aux files with the same
+ # basename as the manual. Use extension .texi for the temp file so
+ # that TeX will ignore it. Thus, we must use a subdirectory.
+ #
+ # Output the macro-expanded file to here. The vastly abbreviated
+ # temporary directory name is so we don't have collisions on 8.3 or
+ # 14-character filesystems.
+ tmp_dir=${TMPDIR-/tmp}/txi2d.$$
+ filename_tmp=$tmp_dir/$filename_noext.texi
+ # Output the file with the user's extra commands to here.
+ tmp_dir2=${tmp_dir}.2
+ filename_tmp2=$tmp_dir2/$filename_noext.texi
+ mkdir $tmp_dir $tmp_dir2
+ # Always remove the temporary directories.
+ trap "rm -rf $tmp_dir $tmp_dir2" 1 2 15
+
+ # If directory and file are the same, then it's probably because there's
+ # no pathname component. Set dirname to `.', the current directory.
+ if test "z${directory}" = "z${command_line_filename}"; then
+ directory=.
+ fi
+
+ # Source file might @include additional texinfo sources. Put `.' and
+ # directory where source file(s) reside in TEXINPUTS before anything
+ # else. `.' goes first to ensure that any old .aux, .cps, etc. files in
+ # ${directory} don't get used in preference to fresher files in `.'.
+ TEXINPUTS=".:${directory}:${TEXINPUTS_orig}"
+
+ # Expand macro commands in the original source file using Makeinfo;
+ # the macro syntax bfox implemented is impossible to implement in TeX.
+ # Always use `end' footnote style, since the `separate' style
+ # generates different output (arguably this is a bug in -E).
+ # Discard main info output, the user asked to run TeX, not makeinfo.
+ # Redirect output to /dev/null to throw away `Making info file...' msg.
+ $verbose "Macro-expanding $command_line_filename to $filename_tmp ..."
+ $makeinfo --footnote-style=end -E $filename_tmp -o /dev/null \
+ $command_line_filename >/dev/null
+
+ # But if there were no macros, or makeinfo failed for some reason,
+ # just use the original file. (It shouldn't make any difference, but
+ # let's be safe.)
+ if test $? -ne 0 || cmp -s $filename_tmp $command_line_filename; then
+ $verbose "Reverting to $command_line_filename ..."
+ cp -p $command_line_filename $filename_tmp
+ fi
+ filename_input=$filename_tmp
+ dirname_input=$tmp_dir
+
+ # Used most commonly for @finalout, @smallbook, etc.
+ if test -n "$textra"; then
+ $verbose "Inserting extra commands: $textra."
+ sed '/^@setfilename/a\
+'"$textra" $filename_input >$filename_tmp2
+ filename_input=$filename_tmp2
+ dirname_input=$tmp_dir2
+ fi
+
+ # If clean mode was specified, then move to the temporary directory.
+ if test "$clean" = t; then
+ $verbose "cd $dirname_input"
+ cd $dirname_input || exit 1
+ filename_input=`basename $filename_input`
+ fi
+
+ while true; do # will break out of loop below
+ # "Unset" variables that might have values from previous iterations and
+ # which won't be completely reset later.
+ definite_index_files=
+
+ # Find all files having root filename with a two-letter extension,
+ # determine whether they're really index files, and save them. Foo.aux
+ # is actually the cross-references file, but we need to keep track of
+ # that too.
+ possible_index_files="`eval echo ${filename_noext}.?? ${filename_noext}.aux`"
+ for this_file in ${possible_index_files}; do
+ # If file is empty, forget it.
+ test -s "${this_file}" || continue
+
+ # Examine first character of file. If it's not suitable to be an
+ # index or xref file, don't process it.
+ first_character="`sed -n '1s/^\(.\).*$/\1/p;q' ${this_file}`"
+ if test "x${first_character}" = "x\\" \
+ || test "x${first_character}" = "x'"; then
+ definite_index_files="${definite_index_files} ${this_file}"
+ fi
+ done
+ orig_index_files="${definite_index_files}"
+ orig_index_files_sans_aux="`echo ${definite_index_files} \
+ | sed 's/'${filename_noext}'\.aux//;
+ s/^[ ]*//;s/[ ]*$//;'`"
+
+ # Now save copies of original index files so we have some means of
+ # comparison later.
+ $verbose "Backing up current index files: $orig_index_files ..."
+ for index_file_to_save in ${orig_index_files}; do
+ cp "${index_file_to_save}" "${index_file_to_save}${backup_extension}"
+ done
+
+ # Run texindex on current index files. If they already exist, and
+ # after running TeX a first time the index files don't change, then
+ # there's no reason to run TeX again. But we won't know that if the
+ # index files are out of date or nonexistent.
+ if test -n "${orig_index_files_sans_aux}"; then
+ $verbose "Running $texindex $orig_index_files_sans_aux ..."
+ ${texindex} ${orig_index_files_sans_aux}
+ fi
+
+ # Finally, run TeX.
+ if test "$batch" = t; then
+ tex_mode='\nonstopmode'
+ else
+ tex_mode=
+ fi
+ $verbose "Running $tex $filename_input ..."
+ cmd="$tex $tex_mode \\input $filename_input"
+ $cmd
+
+ # Check if index files changed.
+ #
+ definite_index_files=
+ # Get list of new index files.
+ possible_index_files="`eval echo ${filename_noext}.?? ${filename_noext}.aux`"
+ for this_file in ${possible_index_files}; do
+ # If file is empty, forget it.
+ test -s "${this_file}" || continue
+
+ # Examine first character of file. If it's not a backslash or
+ # single quote, then it's definitely not an index or xref file.
+ # (Will have to check for @ when we switch to Texinfo syntax in
+ # all these files...)
+ first_character="`sed -n '1s/^\(.\).*$/\1/p;q' ${this_file}`"
+ if test "x${first_character}" = "x\\" \
+ || test "x${first_character}" = "x'"; then
+ definite_index_files="${definite_index_files} ${this_file}"
+ fi
+ done
+ new_index_files="${definite_index_files}"
+ new_index_files_sans_aux="`echo ${definite_index_files} \
+ | sed 's/'${filename_noext}'\.aux//;
+ s/^[ ]*//;s/[ ]*$//;'`"
+
+ # If old and new list don't at least have the same file list, then one
+ # file or another has definitely changed.
+ $verbose "Original index files =$orig_index_files"
+ $verbose "New index files =$new_index_files"
+ if test "z${orig_index_files}" != "z${new_index_files}"; then
+ index_files_changed_p=t
+ else
+ # File list is the same. We must compare each file until we find a
+ # difference.
+ index_files_changed_p=
+ for this_file in ${new_index_files}; do
+ $verbose "Comparing index file $this_file ..."
+ # cmp -s will return nonzero exit status if files differ.
+ cmp -s "${this_file}" "${this_file}${backup_extension}"
+ if test $? -ne 0; then
+ # We only need to keep comparing until we find *one* that
+ # differs, because we'll have to run texindex & tex no
+ # matter what.
+ index_files_changed_p=t
+ $verbose "Index file $this_file differed:"
+ test $verbose = echo \
+ && diff -c "${this_file}${backup_extension}" "${this_file}"
+ break
+ fi
+ done
+ fi
+
+ # If index files have changed since TeX has been run, or if the aux
+ # file wasn't present originally, run texindex and TeX again.
+ if test "${index_files_changed_p}"; then :; else
+ # Nothing changed. We're done with TeX.
+ break
+ fi
+ done
+
+ # If we were in clean mode, compilation was in a tmp directory.
+ # Copy the DVI file into the directory where the compilation
+ # has been done. (The temp dir is about to get removed anyway.)
+ # We also return to the original directory so that
+ # - the next file is processed in correct conditions
+ # - the temporary file can be removed
+ if test -n "$clean"; then
+ $verbose "Copying DVI file from `pwd` to $orig_pwd"
+ cp -p $filename_noext.dvi $orig_pwd
+ cd $orig_pwd || exit 1
+ fi
+
+ # Generate list of files to delete, then call rm once with the entire
+ # list. This is significantly faster than multiple executions of rm.
+ file_list=
+ for file in ${orig_index_files}; do
+ file_list="${file_list} ${file}${backup_extension}"
+ done
+ if test -n "${file_list}"; then
+ $verbose "Removing $file_list $tmp_dir $tmp_dir2 ..."
+ rm -f ${file_list}
+ rm -rf $tmp_dir $tmp_dir2
+ fi
+done
+
+$verbose "$0 done."
+true # exit successfully.
texi2dvi
Property changes :
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property