new texdoc.1 manpage for texlua version

git-svn-id: svn://tug.org/texlive/trunk@8052 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 220 insertions, 89 deletions

diff --git a/Master/texmf/doc/man/man1/texdoc.1 b/Master/texmf/doc/man/man1/texdoc.1
index 449ad1c2801..e2bbcdeca5b 100644
--- a/Master/texmf/doc/man/man1/texdoc.1
+++ b/Master/texmf/doc/man/man1/texdoc.1
@@ -1,94 +1,225 @@
-.\" EX and EE are used for displays that are pure code
-.de EX
-.nf
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
 .ft CW
-.in +5
+.nf
+.ne \\$1
 ..
-.de EE
-.in -5
+.de Ve \" End verbatim text
 .ft R
 .fi
 ..
-.TH "texdoc" "1" "September 2000" "teTeX" "teTeX" 
-.PP 
-.SH "NAME" 
-texdoc \- Utility to look up TeX documentation
-.PP 
-.SH "SYNOPSIS" 
-.PP 
-\fBtexdoc\fP [ \fIOPTION\fP \&.\&.\&. ]  \fINAME\fP [ \&.\&.\&. ]
-.PP 
-.SH "DESCRIPTION" 
-.PP 
-\fBtexdoc\fP searches for \fINAME\fP in the TeX documentation and
-starts an appropriate viewer\&.
-.PP 
-\fINAME\fP should be the name of a command or package in the teTeX
-distribution\&.
-.PP 
-.SH "OPTIONS" 
-.PP 
-.IP "\fB--help\fP" 
-Display a brief summary of options\&.
-.IP 
-.IP "\fB-l\fP" 
-List matching files\&.  Does not start a viewer\&.
-.IP "\fB-v\fP" 
-Sets verbose mode\&.  Shows the command being used to
-display the documentation\&.
-.PP 
-.SH "ENVIRONMENT" 
-.PP 
-.IP "\fB$TEXDOCVIEW_dvi\fP" 
-DVI viewer\&.  Defaults to \fBxdvi\fP(1)\&.
-.IP "\fB$TEXDOCVIEW_pdf\fP" 
-PDF viewer\&.  Defaults to \fBacroread\fP(1)\&.
-.IP "\fB$TEXDOCVIEW_ps\fP" 
-PostScript viewer\&.  Defaults to
-\fBghostview\fP(1)\&.
-.IP "\fB$TEXDOCVIEW_html\fP" 
-HTML viewer\&.  Defaults to \fBnetscape\fP(1)\&.
-.IP "\fB$TEXDOCVIEW_txt\fP" 
-Text viewer\&.  Defaults to \fB$PAGER-more\fP\&.
-.PP 
-The environment variables should be set with a ``%s\&'\&' as a placeholder
-for the name of the file\&.  For example,
-.PP 
-.EX 
-hostname% setenv TEXDOCVIEW_pdf "gv %s"
-.EE 
-.PP 
-or
-.PP 
-.EX 
-hostname$ TEXDOCVIEW_html="mozilla %s"
- 
-hostname$ export TEXDOCVIEW_html
-.EE 
-.PP 
-.SH "SEE ALSO" 
-.PP 
-\fBacroread\fP(1), \fBgv\fP(1), \fBkpsewhich\fP(1),
-\fBless\fP(1), \fBmore\fP(1), \fBxdvi\fP(1)
-.PP 
-Web page: <http://tug\&.org/teTeX/>
-.PP 
-.SH "BUGS" 
-.PP 
-None known, but report any bugs found to <tetex@dbs\&.uni-hannover\&.de> (mailing list)\&.
-.PP 
-.SH "AUTHOR" 
-.PP 
-\fBtexdoc\fP was written by Thomas Esser 
-<te@dbs\&.uni-hannover\&.de>, David Aspinall 
-<da@dcs\&.ed\&.ac\&.uk>, and
-Simon Wilkinson
-<sxw@dcs\&.ed\&.ac\&.uk> during 1998 and 1999\&.  \fBtexdoc\fP is in the public
-domain\&.
-.PP 
-This manual page was written by C\&.M\&. Connelly
-<c@eskimo\&.com>, for
-the Debian GNU/Linux system\&.  It may be used by other distributions
-without contacting the author\&.  Any mistakes or omissions in the
-manual page are my fault; inquiries about or corrections to this
-manual page should be directed to me (and not to the primary author)\&.
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "TEXDOC 1"
+.TH TEXDOC 1 "2007-06-05" "perl v5.8.8" "User Contributed Perl Documentation"
+.SH "NAME"
+texdoc \- Search for NAME in the TeX documentation and start a viewer.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBtexdoc\fR
+[\fB\-h|\-\-help\fR]
+[\fB\-v|\-\-verbose\fR]
+[\fB\-V|\-\-version\fR]
+[\fB\-l|\-\-list\fR]
+[\fB\-S|\-\-search\fR]
+[\fIname|pattern\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\fBtexdoc\fR is a script which attempts to find and display
+documentation for tex files.  Without any options, the file
+\fBname\fR\fI.ext\fR is displayed, where \fI.ext\fR is one of the
+extensions defined in the variable \s-1TEXDOCEXT\s0 in
+\&\fBtexmf.cnf\fR.  The viewer used for displaying the file can be
+customized.
+
+\fBtexdoc\fR accepts compressed files, too.  You can also specify the
+complete filename, e.g. to decide which of two files with equal
+basename you want., In this case, however, access to compressed files
+is not possible.
+.SH "OPTIONS"
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+Display a usage message
+.IP "\fB\-V\fR, \fB\-\-version\fR" 4
+Display version information and exit
+.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
+verbose mode: show viewer command
+.IP "\fB\-l\fR, \fB\-\-list\fR" 4
+Just list all files that match \fIname\fR, do not start a viewer.
+.IP "\fB\-S\fR, \fB\-\-search\fR \fIpattern\fR" 4
+\&\fIpattern\fR is treated as a lua pattern (similar to basic regular
+expressions, with `%' as escape character instead of `\\').  The output first lists all
+directory names which match \fIpattern\fR and then all files.
+Currently, directories without an ls-R file are ignored.
+.SH "VARIABLES"
+.RS 4
+.IP "TEXDOCS = .;$TEXMF/doc//"
+Specifies the directories where TeX documentation is stored
+.IP "\s-1TEXDOCEXT\s0 = {:.pdf:.ps:.dvi:.txt:.tex}{:.gz:.bz2}:.html" 4
+Recognized formats for documentation, the first match wins.  The
+default uses standard kpathsea brace notation.  `html' should be last
+in order to prevent the catalogue entry from being shown when other
+documentation exists.
+.IP "\s-1TEXDOC_VIEWER_\fBFORMAT\fR\s0 = (command %s) &" 4
+Defines the viewer to be used for \fBFORMAT\fR,
+e.g. \fITEXDOC_VIEWER_DVI\fR.  The filename (and tempfile cleanup
+commands, if needed after decompression) is substituted for `%s'.  If
+the viewer does not put itself in the background, the command must be
+enclosed in parentheses and the `&' sign appended, as shown in the
+example for \fIcommand\fR.
+.IP "\s-1TEXDOC_UNZIP_\fBFORMAT\fR\s0 = command -a -c " 4
+This variable specifies the command which is used to uncompress a file
+compressed as \fBFORMAT\fR.  It result must go to \fIstdout\fR.
+.IP "\s-1TEXDOC_FORMATS\s0 = pdf,dvi,ps,txt,tex" 4
+The formats for which a viewer is defined in \fItexmf.cnf\fR (order
+does not matter). 
+.IP "\s-1TEXDOC_ZIPFORMATS\s0 = gz,bz2" 4
+The compression formats for which a decompression command is defined
+in \fItexmf.cnf\fR.
+.IP "\s-1TEXDOC_RMFILE\s0 = rm -f" 4
+The command used to remove a file on the target system.  This is used
+for temporary files which are needed for viewing compressed documents.
+.IP "\s-1TEXDOC_RMDIR\s0 = rmdir" 4
+The command used to remove a directory on the target system.  This is
+used for temporary directories which are needed for viewing compressed
+documents.
+.SH "BUGS"
+Currently no bugs are known, but there are some limitations:
+.IP "Specifying the filename, complete with extension"
+This doesn't work for compressed files.
+.IP manpage
+The manpage has been written on a template created by pod2man, and its
+source contains a lot of (probably) useless cruft at the beginning.
+.SH "HISTORY"
+Original version by David Aspinall <da@dcs.ed.ac.uk>
+.Sp
+Rewritten for use with bash 2 and teTeX under Linux by Simon Wilkinson
+<sxw@dcs.ed.ac.uk>
+.Sp
+Changes for web2c\-7.2 resp. teTeX\-0.9 and portability fixes by
+Thomas Esser <te@dbs.uni\-hannover.de>, Jun 14 1998
+.Sp
+Support for compressed documentation implemented by adopting changes
+made by debian. Thomas Esser, Dec. 2004.
+.Sp
+Rewritten using texlua by Frank Küster <frank@kuesterei.ch>.  Changed
+the \-s option to use ls-R instead of \fIfind\fR, May/June 2007.
+
+