diff options
author | Karl Berry <karl@freefriends.org> | 2020-03-12 17:55:08 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2020-03-12 17:55:08 +0000 |
commit | 45660c4e98d81bf195433c8564d4f8cecb697e83 (patch) | |
tree | 28e67ceb1d488d2eedcc71a112cb221b64716cbf /Build/source/texk/web2c/doc/web2c.texi | |
parent | 120cf5399822b372ff1c7b4edee612374b8c8a79 (diff) |
\input{...} doc, other \input filename details
git-svn-id: svn://tug.org/texlive/trunk@54255 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/doc/web2c.texi')
-rw-r--r-- | Build/source/texk/web2c/doc/web2c.texi | 134 |
1 files changed, 97 insertions, 37 deletions
diff --git a/Build/source/texk/web2c/doc/web2c.texi b/Build/source/texk/web2c/doc/web2c.texi index 046086606fa..d44a2e480b2 100644 --- a/Build/source/texk/web2c/doc/web2c.texi +++ b/Build/source/texk/web2c/doc/web2c.texi @@ -12,7 +12,7 @@ The latest version is available from ftp://ftp.tug.org/tex/texinfo.tex.} @end tex @set version 2020 -@set month-year January 2020 +@set month-year March 2020 @c Define new indices for commands in auxiliary files, filenames, and options. @defcodeindex cm @@ -63,7 +63,7 @@ This file documents the installation and use of the programs in Web2c, an implementation of Donald Knuth's TeX system. Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -2004, 2005, 2007, 2008, 2009 Karl Berry & Olaf Weber. +2004, 2005, 2007, 2008, 2009, 2010-2020 Karl Berry & Olaf Weber. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -88,7 +88,6 @@ except that this permission notice may be stated in a translation @titlepage - @title Web2c @subtitle for version @value{version} @subtitle @value{month-year} @@ -525,7 +524,7 @@ control some array sizes and other features are described in * Initial and virgin:: Making memory dumps vs. production runs. * Memory dumps:: .fmt/.base files for fast startup. * Editor invocation:: The `e' response at errors. -* \input filenames:: ~ and $ expansion in TeX/MF/MP. +* \input filenames:: Filename delimiters and Kpathsea expansion. @end menu @@ -808,9 +807,42 @@ Metafont and MetaPost, the statement terminator @samp{;} also works. @code{\input} that allow different notation; here we are concerned only with the primitive operation.) -As of Web2c version 7.5.3, double-quote characters can be used to -include spaces or other special cases. In typical use, the @samp{"} -characters surround the entire filename: +As (allowed) extensions to standard @TeX{}, Web2c also supports +specifying the filename in double quotes (@code{"some name"}) and in +braces (@code{@{"some name"@}}), which is convenient for filenames +containing spaces or other special characters, as described in the +sections below. + +In all cases, space tokens are ignored after the filename is read. + +@cindex @code{"} character, ignored in filenames +@cindex double quote character, ignored in filenames +Also, double quote (@code{"}) characters are ignored within the +filename; there is no way to read files whose names contain a @code{"}. + +@cindex portable filenames +However, for maximal portability of your document across systems, use +only the characters @samp{a}--@samp{z}, @samp{0}--@samp{9}, and +@samp{.}. Do not use anything but simple filenames, since directory +separators vary among systems; instead, add the necessary directories +to the appropriate search path. + +@menu +* Quotes: \input quoted filename. \input "some name" +* Braces: \input braced filename. \input @{some name@} +* Caveats: \input filename caveats. Tokenization, nulls, Kpathsea expansion. +@end menu + + +@node \input quoted filename +@subsubsection @code{\input} quoted filename: @code{\input "some name"} + +@cindex @code{\input} quoted filename +@cindex quoted filename for @code{\input} + +As of Web2c version 7.5.3 (2004), double-quote characters can be used +to include spaces or other special characters. In typical use, the +@samp{"} characters surround the entire filename: @example \input "filename with spaces" @end example @@ -821,16 +853,57 @@ can enclose any characters, as in: \input filename" "with" "spaces @end example -One more point. In @LaTeX{}, the quotes are needed inside the braces, thus +One more point. In @LaTeX{}, the quotes are needed inside the braces +of its @code{\input} macro, thus: @example \input@{a b@} % fails \input@{"a b"@} % ok @end example -This quoting mechanism comes into play @emph{after} @TeX{} has -tokenized and expanded the input. So, multiple spaces and tabs may be -seen as a single space, active characters such as @samp{~} are -expanded first, and so on. (See below.) +There is no way to quote the quote character. + + +@node \input braced filename +@subsubsection @code{\input} braced filename: @code{\input@{some name@}} + +@cindex @code{\input} braced (grouped) filename +@cindex braced filename for @code{\input} +@cindex group-delimited filename for @code{\input} + +As of Web2c 2020, @code{\input} filenames in @TeX{} engines (this does +not apply in Metafont and MetaPost) can also be specified within a +@TeX{} group, typically curly braces. For example: +@example +\input@{filename with spaces@} +@end example + +As always with @TeX{}, the brace characters are not hardwired; what +counts is the category code: the first token after the @code{\input} +must be of catcode@tie{}1 (begin group), and it is matched with the +next character of catcode@tie{}2 (end group). + +Within the group-delimited filename, braces are treated as normal +characters. + +As with all forms of filenames, following spaces are ignored (after +the end group), and double quote (@code{"}) characters are ignored +within the filename. + + +@node \input filename caveats +@subsubsection @code{\input} filename caveats + +@cindex @code{\input} filename caveats +@cindex caveats for @code{\input} filenames +@cindex tokenization, and @code{\input} filenames +@cindex expansion, and @code{\input} filenames +@cindex multiple spaces, and @code{\input} filenames +@cindex tabs, and @code{\input} filenames +The quoting mechanisms just described come into play @emph{after} +@TeX{} has tokenized and expanded the input. So, multiple spaces and +tabs will generally be seen as a single space, active characters such +as @samp{~} are expanded first (generally causing an error), and so +on. More examples below. @cindex NUL, not allowed in filenames @cindex eight-bit characters in filenames @@ -839,42 +912,29 @@ On the other hand, various C library routines and Unix itself use the null byte (character code zero, ASCII NUL) to terminate strings. So filenames in Web2c cannot contain nulls, even though @TeX{} itself does not treat NUL specially. -In addition, some older Unix variants do not allow eight-bit characters -(codes 128--255) in filenames. - -@cindex portable filenames -For maximal portability of your document across systems, use only the -characters @samp{a}--@samp{z}, @samp{0}--@samp{9}, and @samp{.}, and -restrict your filenames to at most eight characters (not including the -extension), and at most a three-character extension. Do not use -anything but simple filenames, since directory separators vary among -systems; instead, add the necessary directories to the appropriate -search path. @kindex ~ @r{expansion in filenames} @kindex $ @r{expansion in filenames} Finally, the present Web2c implementation does @samp{~} and @samp{$} -expansion on @var{name}, unlike Knuth's original implementation and -older versions of Web2c. Thus: +expansion on @var{name}, unlike Knuth's original implementation. +Thus: @example \input ~jsmith/$foo.bar @end example -will dereference the environment variable or Kpathsea config file value -@samp{foo} and read that file extended with @samp{.bar} in user -@samp{jsmith}'s home directory. You can also use braces, as in -@samp{$@{foo@}bar}, if you want to follow the variable name with a letter, -numeral, or @samp{_}. +will dereference the environment variable or Kpathsea config file +value @samp{foo} and read that file, extended with @samp{.bar}, in +user @samp{jsmith}'s home directory. You can also use braces in the +variable expansion, as in @samp{$@{foo@}bar}, if you want to follow +the variable name with a letter, numeral, or @samp{_}. (So another way to get a program to read a filename containing whitespace is to define an environment variable and dereference it.) -@findex \string -In all the common @TeX{} formats (plain @TeX{}, @LaTeX{}, AMS@TeX{}), -the characters @samp{~} and @samp{$} have special category codes, so to -actually use these in a document you have to change their catcodes or -use @code{\string}. (The result is unportable anyway, see the -suggestions above.) The place where they are most likely to be useful -is when typing interactively. +@findex \string@r{, and @code{\input filenames}} +In all the common @TeX{} formats (plain @TeX{}, @LaTeX{}, Con@TeX{}t, +AMS@TeX{}, @dots{}), the characters @samp{~} and @samp{$} have special +category codes, so to actually use these in a document you have to +change their catcodes or use @code{\string}. @node TeX |