diff options
Diffstat (limited to 'macros/plain/contrib/transparent-io/Transparent-IO-doc.tex')
-rw-r--r-- | macros/plain/contrib/transparent-io/Transparent-IO-doc.tex | 832 |
1 files changed, 832 insertions, 0 deletions
diff --git a/macros/plain/contrib/transparent-io/Transparent-IO-doc.tex b/macros/plain/contrib/transparent-io/Transparent-IO-doc.tex new file mode 100644 index 0000000000..5dd564f93a --- /dev/null +++ b/macros/plain/contrib/transparent-io/Transparent-IO-doc.tex @@ -0,0 +1,832 @@ +% some \tt chars +\def\bs{\char"5C }\def\ocb{\char"7B }\def\ccb{\char"7D } +% simple \verbatim macros +\def\beginverbatim{\medskip\noindent\bgroup\frenchspacing\tt} +\def\parni{\par\noindent}\def\endverbatim{\egroup\goodbreak\medskip} +% for control sequences in text another macro is used +\def\cs#1{{\tt\string#1}} +% important instructions are formulated as rules: +\def\rule#1{\smallskip\def\par{\let\par=\endgraf\smallskip}{\parindent52pt \item{\rm#1. RULE:}}} +% macros to indent error messages +\def\fivespaces{\ \ \ \ \ }\def\tenspaces{\fivespaces\fivespaces} +\def\twentyspaces{\tenspaces\tenspaces}\def\fortyspaces{\twentyspaces\twentyspaces} +% macro to enter file names with descriptions +\def\filename #1. #2:{\item{#1.}\hbox to 100pt{{\tt#2}\hfil--}} +% +\hyphenation{TrIO-macros TrIO-support TrIO-private TrIO-input + TrIO-extract TrIO-lineno TrIO-auto TrIO-open TrIO-names + TrIO-install openin open-out} +\parskip=0pt + + + +\centerline{\bf TrIO: Transparent file I/O} +\smallskip +\centerline{\bf Version of 2022-04-30} +\smallskip +\centerline{Udo Wermuth} +\smallskip + +\noindent +The macros are written for the {\bf original \TeX} running with the +format {\bf plain.tex}. It assumes that a path to a file uses +directory names that are separated by slashes. Except letters, digits, +and the slash only a period is used to separate the main part of the +file name and its extension. + +The operation is done on a {\bf command line} and makes use of a {\bf +bash script} and the stream editor~{\bf sed}. The installation scripts +assume a {\bf UNIX-like operating system}. + +The application of the macros requires {\bf concentration}; don't +execute \TeX\ with an instrumented source file hastily. Moreover, to +use the macros successfully you must have a {\bf non-beginner's +knowledge} of~\TeX. Strictly speaking, {\bf the more you know about +plain \TeX\ the better}; see section~10. + +\smallskip +{\sl Note}: My article in {\sl TUGboat\/} 43:1 (2022), 59--72, +contains a lot of additional information, for example, about my +motivation to develop these macros. But it omits some parts like the +start message. I suggest to read the article and this manual if +you want to apply the macros. + +\beginsection \rm a) Meaning of ``transparent'' + +The word ``transparent'' means that the instrumented source cannot do +any \cs\input, \cs\openin, or \cs\openout\ without an approval of the +user. Well, {\tt\string\input} is an exception as it might be possible +to input a file without approval---{\sl might} because it depends on +your operating system and your \TeX\ program---but that a file is +input is always shown on the terminal and the user must stop the +processing. An evil-doer might try to circumvent the reporting of the +macros. In such a case the user must check the source carefully for +malicious code before it should be compiled again by~\TeX. + +\beginsection \rm b) Rules + +As indicated in the previous paragraph the application of the macros +requires that the user follows a couple of rules. Otherwise the macros +of this package might not do what is intended. + + \rule1 Create in the directory with the source that you want to test +a new subdirectory, say, {\tt trioo}, and redirect all \cs\openout\ +commands to this subdirectory. + + \rule2 Check that the bundle of the source files doesn't include a +file that carries a name that's identical to a file name of this +package. Otherwise rename such a source file. + + \rule3 Never approve that a file of this package is processed by the +source file. Enter the new name of a source file if you renamed one of +them because of rule~2. Otherwise stop the run and check the source. + + \rule4 Follow all terminal messages carefully; don't allow that the +source inputs a file without your approval. Otherwise stop the run and +check the source. (Maybe you need to apply an option; see section~4.) + + + +\beginsection 1. Files in the package + +The package contains the following files: + +\medskip +\filename 1. TrIOmacros.org: main file to instrument a source file +\filename 2. TrIOsupport.org: common macros to {\tt TrIOmacros.tex} and {\tt TrIOauto.tex} +\filename 3. TrIOprivate.org: copies of control sequences and test routines +\filename 4. TrIOinput.org: called for every \cs\input +\filename 5. TrIOopenin.org: entered by the user for every \cs\openin +\filename 6. TrIOopenout.org: entered by the user for every \cs\openout +\smallskip +\filename 7. TrIOextract.org: {\tt sed} script to create {\tt TrIOnames.tex} +\filename 8. TrIOlineno.org: another {\tt sed} script to create {\tt TrIOnames.tex} +\filename 9. TrIOauto.org: replacement for {\tt TrIOmacros.tex} in repeated executions +\filename 10. TrIOopen.org: called for every I/O command in {\tt TrIOnames.tex} +\smallskip +\filename 11. TrIO.org: {\tt bash} script to install the package +\filename 12. TrIOinstall.org: {\tt sed} script to set passwords and private messages +\filbreak\medskip + +The last two files are only used for the installation. They must be +renamed and edited, see section~2. The other files get a new extension +during the installation. + +The first six files are required to instrument a source; see +section~3. All are renamed during the installation so that all have +the extension {\tt tex} instead of {\tt org}; in the names of files 5 +and 6 the ``TrIO'' prefix is deleted too. Files 7--10 are needed for +repeated executions; see section~8. The first two become {\tt sed} +scripts the other two {\tt tex} files. + + + +\beginsection 2. Installation + +{\tt TrIOinstall.org} and {\tt TrIO.org} are used for the installation. + +The other files are changed during the installation. They must be +either moved into the directory that contains the source to be tested +or they are installed in a directory that is searched for input files +by the program \TeX. + +\beginsection Step 1: \rm Rename and edit {\tt TrIOinstall.org} + +{\tt TrIOinstall.org} must be copied to {\tt TrIOinstall.sed}. This +file must then be edited to have {\bf individual password-protected +macro names} and {\bf private messages}. Note there is no valid +default active. The macros fail to do what they should do if this file +isn't carefully edited. + +\beginsection \rm a) Passwords + +A password-protected name contains a string of at least six +letters. It must be a mix of lower- and uppercase, one letter should +be from the first and one from the last third of the alphabet. It +should be neither an English word nor one in your language. The +general idea is that this string cannot be guessed or computed by +someone else. A user hasn't to enter these password-protected macro +names (except one) so a user has not to remember them. Thus, they must +not be simple. + +One of the passwords occur in a command that is displayed together +with a private message. Although not required it would be nice to +recognize this password. A second password is part of a control word +that must be entered by the user into the source if the source +contains extremely weird constructions; see section~5. + +In total eight passwords must be created. {\tt TrIOinstall.sed} +contains lines like +\smallskip\noindent +{\tt s/aAmNzZ/new password/g} +\smallskip\noindent +and you have to replace ``{\tt new password}'' with the new password, +i.e., a string of at least six letters with the above mentioned +distribution. And please, never use the known default, i.e., the +string {\tt aAmNzZ}, etc. + +\beginsection \rm b) Private messages + +Next, you have to choose two private messages. The first one explains +what to do for \cs\openin\ or \cs\openout, the second signals that the +correct file for \cs\input\ was executed. + +\medskip +The rest of {\tt TrIOinstall.sed} can be ignored for the moment. These +lines must be used if the source uses {\tt TrIO} or {\tt TRIO} as a +prefix for its own macros; see c). Then one can change these prefixes +in the macros of this package. + +\beginsection \rm c) Optional: Prefix ``{\tt T[r|R]IO}'' + +The last lines in the installation script are used to change the +prefix ``{\tt TrIO}'' and the prefix ``{\tt TRIO}'' in the case that +some source uses one of them too. The macros detect if one of their +control sequences gets redefined by the source and reports that with +an error message: {\tt !\ TrIO ALERT !!!\ Don't trust the source +(<name of the redefined control word>).} + + \rule5 Stop the run if the ``{\tt TrIO ALERT}'' error message is +displayed. The source has redefined one of the control words that +occur in the macros of this package. Check the source carefully to +determine if that happens by accident or intentionally. +\smallskip + +Note, the easiest way to fix a single use of the prefix ``{\tt TrIO}'' +is to change the source. Otherwise a user can apply the installation +script and change the prefix for all macros of the package. The prefix +isn't private, i.e., the source might contain code that determines +which prefix is used by the macro package. + + +\beginsection Step 2: \rm Rename and edit {\tt TrIO.org}; then execute + +Rename {\tt TrIO.org} to {\tt TrIO.sh}. Make sure that the renamed +file can be executed, for example, apply {\tt chmod 744}. The file +must be edited too: Enter a valid path for {\tt inst\_dir}. + +The execution of the script {\tt TrIO.sh}, i.e., enter {\tt ./TrIO.sh} +on a command line in the directory of the {\tt TrIO*.org} files, +installs the files by default in this directory. This might be okay if +the package should be placed there. But if you use a \TeX\ +distribution the installation directory should probably be changed; +consult the documentation of your distribution to figure out where +configured packages should be stored. + +My suggestion: Use the current directory for experiments. If you like +the macros then install them in your \TeX\ file system and make sure +that the correct {\tt openin.tex} and {\tt openout.tex} are found as +these files carry quite generic names. (Maybe you must {\bf rename} +them in {\tt TrIO.sh}; see also section~9.) + + + + +\beginsection 3. Using {\tt TrIOmacros.tex} + +To activate the macros create a new first line in the main file of the +source that should be instrumented. Enter ``{\tt +<options> \cs\input\space TrIOmacros}''; where {\tt <options>} is a +combination of +\medskip +\item{i)} empty; +\item{ii)} {\tt\cs\let\cs\twonosubdirs=y}; +\item{iii)} {\tt\cs\let\cs\threenosubdirs=y}; +\item{iv)} {\tt\cs\let\cs\disablespecial=n}; +\item{v)} {\tt\cs\let\cs\disablespecial=y}. +\medskip\noindent +Note: here iii) beats ii) and v) beats iv). The options are explained +in the next section. + +\beginsection \rm a) An example + +Let's do a trial run with {\tt Transparent-IO-example.tex}; here with +line numbers. +\beginverbatim +1.\bs input TrIOmacros\parni +2.\parni +3.\bs input Transparent-IO-hello\parni +4.\parni +5.\bs openin0=Transparent-IO-hello\parni +6.\parni +7.\bs openout5=Transparent-IO-goodbye\parni +8.\parni +9.\bs bye\endverbatim + +After \TeX's banner line and the name of +the main file, \TeX\ inputs three files (I omit the license message): +\beginverbatim +(./TrIOmacros.tex (./TrIOsupport.tex) (./TrIOprivate.tex)\parni +<<< TrIO >>> \bs special: primitive\parni +<<< TrIO >>> \bs TrIOnosubdir: nosubdir/\endverbatim + +You should check that the correct files of section 1, items 1--3, are +input. Here I assume that the files are in the current directory +indicated by ``{\tt./}''. Then \TeX\ displays two lines about the +current values of control sequences that are influenced by +options. Here both show the default value: \cs\special\ is kept +as \TeX's primitive and \cs\TrIOnosubdir\ is a single directory +with the name {\tt nosubdir/}. + +Next, the macros inform the user that they are active. +\beginverbatim +! TrIO activated. Type h to get instructions.\parni +l.115 ...IO activated. Type h to get instructions\ccb\parni +\fortyspaces\tenspaces\bs endgroup\parni +? h\parni +File I/O ( \bs input \bs openin \bs openout ) is now under TrIO's control.\parni +Be alerted if a file is loaded without the proper TrIO message\parni +and follow always the instruction of this message.\parni +Make sure that the sequence number is incremented sequentially.\parni +? \parni +)\endverbatim + +The help text gives two important hints. Follow the instructions that +are displayed at every stop initiated by these macros. As above these +messages contain a combination of the word ``TrIO'' and three `{\tt<}' +or three `{\tt>}' symbols. The second hint defines a rule. + + \rule6 Check the counter for I/O commands. It must increase +sequentially; otherwise stop the run and check the source. +\smallskip + +The counter appears as soon as \TeX\ stops for an I/O +command. For \cs\input\ is looks like this. +\beginverbatim +<<<\parni +(./TrIOinput.tex\parni +>>> TRIO: Check passed!\parni +)\parni +TrIO >>> ( 1 ) Line 3: input\parni +>>> enter shown file name without `nosubdir/'.\parni +<<<\parni +! I can't find file `nosubdir/Transparent-IO-hello.tex'.\parni +l.3 \bs input Transparent-IO-hello\parni +\ \parni +Please type another input file name: \endverbatim + +The first four lines appear every time a file gets input. It contains +one of the private messages; here it's the default message ``{\tt>>> +TRIO: Check successful!}'' with an uppercase `R' in the word +``TRIO''. During the installation this message was changed and you +should always check that your private message is displayed. + + \rule7 Check that for every \cs\input\ the file {\tt +TrIOinput.tex} is input and that your private message +follows. Otherwise stop the run and check the source. +\smallskip + +Then the macros inform that an I/O command was found. It is the first +command in the file: It occurs in line~3, and it's the +command \cs\input. The stop of the run was initiated by an error +message that was intentionally raised through the use of an +nonexistent subdirectory in front of the file name. The source doesn't +contain this subdirectory; it is added by the macros. Thus \TeX\ +reports that it cannot find ``{\tt nosubdir/Transparent-IO-hello.tex}'' although the +source states ``{\tt\bs input Transparent-IO-hello}''. + +Next, the user has to enter a new file name. As the file {\tt +Transparent-IO-hello.tex} doesn't belong to the macro package (see rule~4) we follow +the instruction (see rule~4) and enter ``Transparent-IO-hello'' as new file name. +\beginverbatim +Please type another input file name: Transparent-IO-hello\parni +(./Transparent-IO-hello.tex)\endverbatim + +The next block shows a stop for the I/O command \cs\openin\ with +stream number~0. +\beginverbatim +<<<\parni +TrIO >>> ( 2 ) Line 5: openin 0\parni +>>> If you accept that the file (without nosubdir/) is read\parni +>>> enter `openin' and follow the instructions.\parni +<<<\parni +! I can't find file `nosubdir/Transparent-IO-hello.tex'.\parni +l.5 \bs openin0=Transparent-IO-hello\parni +\ \parni +Please type another input file name: \endverbatim + +After the check that the counter was increased we follow the +instruction and enter the file name of the package ({\tt openin.tex}) +and not the name that appears in the source (here: {\tt Transparent-IO-hello}). +\beginverbatim +Please type another input file name: openin\parni +(./openin.tex\parni +Enter 1> return 2> file name\ccb\bs TRIOgGKptTpausing=0=>\endverbatim + +This block shows the second private message and one of our private +passwords. Again, we follow the instructions, that is, we press +{\tt<return>} and at the next prompt we enter the name of the file +that should be opened: +\beginverbatim +\bs FilenameOPENIN=Transparent-IO-hello\parni +)\endverbatim + +The treatment of \cs\openout\ is similar to \cs\openin. +\beginverbatim +<<<\parni +TrIO >>> ( 3 ) Line 7: openout 5\parni +>>> If you accept that the file (without nosubdir/) is created\parni +>>> enter `openout' and follow the instructions.\parni +<<<\parni +! I can't find file `nosubdir/Transparent-IO-goodbye.tex'.\parni +l.7 \bs openout5=Transparent-IO-goodbye\parni +\ \parni +Please type another input file name: openout\parni +(./openout.tex\parni +Enter 1> return 2> file name\ccb\bs TRIOgGKptTpausing=0=>\parni +\ \parni +\bs FilenameOPENOUT=trioo/Transparent-IO-goodbye\parni +)\endverbatim + +There is one new technique based on rule~1. The file isn't created in +the current directory but in a special subdirectory called {\tt +trioo/} as seen in the second last line. Of course, one must remember +which files were redirected to this subdirectory as the source might +want to input it later again and then the name of the subdirectory +must be used too. + +Of course, \cs\immediate\ is handled by the macros too; the user sees +``immediate openout'' instead of ``openout'' in the {\tt TrIO >>>} +line. But someone who knows the macros can fake the occurrence +of \cs\immediate. Although there isn't much harm in a +wrong \cs\immediate\ it is recommended to follow this rule. + + \rule8 Always check that an \cs\immediate\ appears in front of +an \cs\openout\ if the macros report ``immediate openout''. Check the +source carefully and reject it if \cs\immediate\ doesn't appear. + + + +\beginsection 4. Options + +In section~3 the four options for the macros were introduced. + +\beginsection \rm a) Path with nonexistent directories + +As explained in section~3 a single nonexistent directory ``{\tt +nosubdir/}'' is used in the macros by default. But if the source +contains a file given with a path that starts with a move to the +parent directory, i.e., {\tt../}, then the effect of {\tt +nosubdir/../} might specify the current directory; this depends on +several factors, i.e., your \TeX\ might not do it. If it's done a file +in the current directory carrying the same name as the file that the +source wants to input from the parent directory is directly input +without a stop of the run. That violates rule~4. + +Therefore you should use either the option +{\tt\cs\let\cs\twonosubdirs=y} or {\tt\cs\let\cs\threenosubdirs=y}. In +the first case the single nonexistent directory is replaced by two +nonexistent directories and in the second there are three +nonexistent directories. The start message of the package shows how +many {\tt nosubdir/}'s are present. + + \rule9 Stop the processing if the source that failed with a single +nonexistent directory fails again at the same I/O command although the +number of nonexistent subdirectories was increased. The source reacts +on this number. + + +\beginsection \rm b) Treatment of \cs\special + +The second start message is about \cs\special. This command can be +dangerous as it writes arbitrary data to \TeX's main output file. The +macros don't check what is written to the DVI file and they assume +that a user switches on the safety features of the program that +display, prints, or transforms the DVI~file. Therefore \cs\special\ is +kept as primitive. + + \rule{10} The programs that interpret the DVI file can be the target +by with an untrusted source attacks your system. Thus switch on all +options to avoid that the DVI file executes unfriendly code if you +keep the primitive \cs\special\ active. + +The option {\tt\cs\let\cs\disablespecial=y} redirects all data of +a \cs\special\ into the LOG file of the \TeX\ run. That +is, \cs\special\ is no longer a primitive; nothing is written to the +DVI file. + +The option {\tt\cs\let\cs\disablespecial=n} tries to be a mixture of +the described behaviours. The primitive \cs\special\ is kept but its +data (or a part of it) is also written to the LOG file; the integer +parameters \cs\showboxdepth\ and \cs\showboxbreadth\ are increased. To +look at the data enter on a command-line the command ``{\tt grep +-e'\char"5E\bs.\bs.*\bs\bs special' <logfile>}''. + + + +\beginsection 5. Errors + +Errors in the original source are of course kept in the instrumented +source. But a few eccentric cases can occur that produce new errors +because of the fact that the I/O primitives are now macros. + +I don't mean a case where a source tests if the I/O commands are +macros or primitives. The source must do something after this test and +whatever it does I don't count this as an error. + +Here is the file {\tt Transparent-IO-eccentric.tex} that contains some +eccentric cases:\vskip-3pt +\beginverbatim +\bs input TrIOmacros\parni +\bs global\bs input Transparent-IO-hello\parni +\bs expandafter\bs show\bs input Transparent-IO-hello\parni +\bs edef\bs csone\ocb\bs input Transparent-IO-hello \ccb\parni +\bs expandafter\bs show\bs openin0=Transparent-IO-hello\parni +\bs bye\parni +\endverbatim + + +\beginsection \rm a) Command in front of \cs\input\ +meant for the first token of the file that is input + +Some errors happen with \cs\input\ in situations like this one +where \cs\global\ is applied to \cs\input. +\beginverbatim +! You can't use a prefix with `\bs begingroup'.\parni +<to be read again> \parni +\tenspaces\fivespaces\ \ \ \ \bs TRIObegingroup \parni +\bs input ->\bs TRIObegingroup \parni +\twentyspaces\fivespaces\bs TRIOafterassignment \bs TRIOnoexpand \bs TrIOempty \bs TRIO...\parni +l.2 \bs global\bs input\parni +\tenspaces\fivespaces\ \ \ Transparent-IO-hello\parni +? \endverbatim + +This is the typical picture for an error where \TeX\ wants to read +again the first token of the macro \cs\input. It is shown not only +for \cs\global\ but also for \cs\number\ and many other commands. + +The solution is to type {\tt42}---you have to remember this +number---and then to insert the command that appears in front +of \cs\input; here it's \cs\global. +\beginverbatim +? 42\parni +\ \parni +\bs input ...put.tex \bs TrIOinputmessage \bs TrIOendgroup \parni +\fortyspaces\tenspaces\bs TRIOinput \bs TrIOnosubdir \parni +l.2 \bs global\bs input\parni +\tenspaces\fivespaces\ \ \ Transparent-IO-hello\parni +? I\bs global\parni +! I can't find file `nosubdir/Transparent-IO-hello.tex'.\parni +l.2 \bs global\bs input Transparent-IO-hello\parni +\ \parni +Please type another input file name: \endverbatim + +Note this is a very strange use of \cs\input\ as the acceptance of the +command in front of \cs\input\ depends on the first token in the file +that's input. + + +\beginsection \rm b) \cs\input\ as second token after \cs\expandafter + +Another kind of error occurs if the commands in front of \cs\input\ digests +tokens. Here is an example. +\beginverbatim +> \bs TRIObegingroup=\bs begingroup.\parni +\bs input ->\bs TRIObegingroup \parni +\twentyspaces\fivespaces\bs TRIOafterassignment \bs TRIOnoexpand \bs TrIOempty \bs TRIO...\parni +l.3 \bs expandafter\bs show\bs input\parni +\twentyspaces\fivespaces\ \ \ Transparent-IO-hello\parni +? \endverbatim + +The solution is to type {\tt41} (as $42-1=41$) and then to insert the +two commands in front of \cs\input. +\beginverbatim +? 41\parni +\ \parni +\bs input ...put.tex \bs TrIOinputmessage \bs TrIOendgroup \parni +\fortyspaces\tenspaces\bs TRIOinput \bs TrIOnosubdir \parni +l.3 \bs expandafter\bs show\bs input\parni +\twentyspaces\fivespaces\ \ \ Transparent-IO-hello\parni +? I\bs expandafter\bs show\parni +! I can't find file `nosubdir/Transparent-IO-hello.tex'.\parni +l.3 \bs expandafter\bs show\bs input Transparent-IO-hello\parni +\ \parni +Please type another input file name: \endverbatim + + +\beginsection \rm c) Use of \cs\input\ in an \cs\edef + +Expansion in an \cs\edef\ or \cs\xdef\ generates a new kind of +error. This time the error message is the well-known {\tt !\ Undefined +control sequence}. This message is raised intentionally by a token +that explains what to do next. +\beginverbatim +! Undefined control sequence.\parni +\bs input ...y \bs TRIOdef \bs TrIOskipXXXVIinsTrIOfixedef \parni +\fortyspaces\tenspaces\bs TrIOempty \ocb\ccb\bs TrIOempty \bs T...\parni +l.4 \bs edef\bs csone\ocb\bs input\parni +\twentyspaces\ \ \ Transparent-IO-hello \ccb\parni +? \endverbatim + +The undefined control word states to skip {\tt36} tokens and then to +insert \cs\TrIOfixedef. You could also enter +first \cs\show\cs\TrIOfixedef\ and check that the macro wasn't changed. +\beginverbatim +? 36\parni +\ \parni +\bs input ...put.tex \bs TrIOinputmessage \bs TrIOendgroup \parni +\fortyspaces\tenspaces\bs TRIOinput \bs TrIOnosubdir \parni +l.4 \bs edef\bs csone\ocb\bs input\parni +\twentyspaces\ \ \ Transparent-IO-hello \ccb\parni +? I\bs TrIOfixedef\parni +! I can't find file `nosubdir/Transparent-IO-hello.tex'.\parni +l.4 \bs edef\bs csone\ocb\bs input Transparent-IO-hello \parni +\twentyspaces\tenspaces\ccb\parni +Please type another input file name: \endverbatim + +Note the source throws more errors as \cs\input\ cannot be used in +an \cs\edef\ except the file that's input ends with a certain +command. Again a unusual scenario. + + +\beginsection \rm d) Errors with \cs\openin\ and \cs\openout + +For \cs\openin\ and \cs\openout\ there is only one error situation. It +occurs with expansion if a sequence of tokens like the +nonsense \cs\expandafter \cs\show \cs\openin{\tt0=Transparent-IO-hello} appears in +the source. In this case the expansion of \cs\openin, which contains +two tokens, looses its first token (that's a \cs\the). One has to +insert this token to continue the processing. +\beginverbatim +> \bs TRIOthe=\bs the.\parni +\bs openin ->\bs TRIOthe \parni +\tenspaces\fivespaces\ \ \ \ \bs TrIOtropenin \parni +l.5 \bs expandafter\bs show\bs openin\parni +\twentyspaces\fivespaces\ \ \ \ 0=Transparent-IO-hello\parni +? \endverbatim + +Again, a very strange code pattern. Why would someone want to expand +an usually unexpandable token before \cs\show\ is applied? + + +\beginsection \rm Summary + +Most of the described cases don't occur in normal code. Some cases +represent a \TeX\ coding error, i.e., they throw one or more errors +during normal execution. These cases might be inserted by someone who +wants to fool you---maybe after the detection that {\tt TrIOmacros} is +used. Thus, I recommend to either inspect the code carefully in order +to find out why the unusual construction is used or to ignore the +source. + + \rule{11} Inspect the source carefully if an error occurs that involves +one of the I/O commands. These errors can only appear with weird code +without any valid use case. Consider to ignore the source. + + + +\beginsection 6. Permanent fixes for the errors + +Note that the interactive fixes of the errors in the previous section +have suppressed several messages, for example, the counter was not +shown and it was not increased. This generates a problem for {\tt +TrIOauto.tex} as we will see later. + +An \cs\expandafter\ with \cs\openin\ or \cs\openout\ can be deleted in +the source. Some constructions for \cs\input\ require a different +approach; to fix a \cs\global\cs\input\ permanently the source must be +edited too. + +The macros contain the password-protected control +sequence \cs\TrIOcCkPxXmove\ that has to be entered in front of the +commands that would occur after the {\tt ?I} in the interactive +fix. For example, the above case is permanently fixed with the +code \cs\TrIOcCkPxXmove\cs\global\cs\input. Of course, you must use +the control word that contains the password that you picked during the +installation; as mentioned above this is the only password one must +remember. + + \rule{12} Never return an edited source file to the author without +removing the first line and all appearances of \cs\TrIOcCkPxXmove. + + \rule{13} Never return a LOG file of your runs to the author of the +source. If you want to return it make sure that it contains no +information about your password-protected macro names, your private +messages, or any trace information of the TrIO macros. + + \rule{14} Never return the DVI file of your runs to the author of the +source. If you want to return it check the DVI output and make sure, +for example, by using the program {\tt dvitype} of the \TeX ware +collection, that it contains no information about your +password-protected macro names or your private messages. + + \rule{15} Create new passwords and private messages if you violate +one of the rules 12--14 by accident. + + + +\beginsection 7. An unsolvable problem + +There is one \TeX\ primitive that can create errors which cannot be +detected by the macros and, thus, which cannot be fixed. But the +macros can detect if the problematic primitive is active. +If the macros report this the user has to check the source carefully +in order to confirm that the activation is required and that it +happens in a way which doesn't influence the work of the macros.\goodbreak + +The problematic primitive is the integer +parameter \cs\globaldefs. Usually its value is 0 and the macros can do +their work without problems. If its value is less than 0 everything is +fine too. But a value greater than 0 makes any assignment global even +if it is not prefixed with \cs\global\ and this can lead to a problem. + +Our macros first reset the value to 0; this assignment is global. At +the end the macros set the value locally back to 1 or $-1$ depending +of the value of \cs\globaldefs\ when a macro is called. Thus code like +this doesn't work correctly: \cs\globaldefs{\tt=1 \ocb}\cs\input\ {\tt +Transparent-IO-hello \ccb}. In this case the value of \cs\globaldefs\ after the +closing brace is 0 not 1. But this case cannot be distinguished by the +macros from the good case {\tt\ocb}\cs\globaldefs{\tt=1} \cs\input\ +{\tt Transparent-IO-hello \ccb}. The macros can only detect if \cs\globaldefs\ has a +value greater than 0 and they report this finding. + + \rule{16} Stop the run if the macros report that \cs\globaldefs\ is +positive. Check the source carefully why this rarely used parameter +must be set. If it must have a value greater 0 check that only the +good case occurs. Otherwise reject the source. + + + +\beginsection 8. Using {\tt TrIOauto} + +If a run with {\tt TrIOmacros.tex} was successful, i.e., no interactive +fix was necessary, repeated executions of the source can be made +simpler. + +First, the LOG file of the successful run should be saved; copy it, for +example, and give it the extension {\tt trio}. Second, one of the two +{\tt sed} files must be applied to this copy. For example, {\tt sed -f +TrIOlineno.sed <triofile> > TrIOnames.tex} where {\tt<triofile>} is +the copy of the LOG file of the successful run. The last step is to +change {\tt TrIOmacros} in the first line of the instrumented source +by {\tt TrIOauto}. + +The file {\tt TrIOlineno.sed} makes stricter comparisons than {\tt +TrIOextract.sed}. You can always recreate {\tt TrIOnames.tex} if the +source file needs to be edited and a comparison of line numbers would +fail by using {\tt TrIOextract.sed} instead of {\tt TrIOlineno.sed} in +the above {\tt sed} command. + +\beginsection \rm a) Rerun of the example of section~3 + +A run with {\tt TrIOauto.tex} starts similar to a run with {\tt +TrIOmacros.tex} except that one more file is loaded but no information +about a nonexistent subdirectory is given. +\beginverbatim +(./TrIOauto.tex (./TrIOsupport.tex) (./TrIOprivate.tex) (./TrIOnames.tex)\parni +<<< TrIO >>> \bs special: primitive\parni +! TrIO auto-mode activated. Type h to get instructions.\parni +l.61 ...ode activated. Type h to get instructions\ccb\parni +\fortyspaces\tenspaces\bs endgroup\parni +? h\parni +File I/O ( \bs input \bs openin \bs openout ) is now under TrIO's control.\parni +Be alerted if a file is loaded without the proper TrIO message\parni +and check that the file name without extension that raises\parni +the font error matches the file name of the TrIO message.\parni +? \endverbatim + +The nonexistent subdirectory isn't required anymore as all I/O +commands are taken from the file {\tt TrIOnames.tex}. In this run a +user cannot change a file name used in the source; the macros use the +ones entered during the successful run. A surprise might be the text +about ``font errors'' in the help text. Although no file name has to +be entered the macros show the name of the successful run and the name +that they read in the current run. +\beginverbatim +(./TrIOopen.tex\parni +TrIO >>> ( 1 ) Line 3: input Transparent-IO-hello \parni +)\parni +! Font \bs TRIOunused=TrIO\char"5FTransparent-IO-hello not loadable: Metric (TFM) file not found.\parni +<to be read again> \parni +\tenspaces\fivespaces\ \ \ \ \bs par\parni +l.4 \parni +\ \parni +? \endverbatim +\noindent +Note that \TeX\ has the complete file name only after it sees the next +line which is empty. + +Although only approved file names are processed a user should still be +concentrated. + + \rule{17} With {\tt TrIOauto.tex} a user should check that {\tt +TrIOopen.tex} is loaded, the sequential counter is increased from stop +to stop, and that the main part of the file name in the line that +starts with ``{\tt TrIO >>>}'' agrees with the name that appears after +the underline in the error message (with \cs\openout\ the path is +replaced by {\tt trioo}, see rule~1). Otherwise the source operates +with varying file names; check the source carefully.\looseness=-1 + +Now press return to input {\tt Transparent-IO-hello.tex} and to go to the next I/O +command. The messages for \cs\openin\ and \cs\openout\ look similar. +\beginverbatim +(./TrIOopen.tex\parni +TrIO >>> ( 2 ) Line 5: openin 0 Transparent-IO-hello\parni +)\parni +! Font \bs TRIOunused=TrIO\char"5FTransparent-IO-hello not loadable: Metric (TFM) file not found.\parni +<to be read again> \parni +\tenspaces\fivespaces\ \ \ \ \bs par\parni +l.6 \parni +\ \parni +? \parni +(./TrIOopen.tex\parni +TrIO >>> ( 3 ) Line 7: openout 5 trioo/Transparent-IO-goodbye\parni +)\parni +! Font \bs TRIOunused=TrIO\char"5FTransparent-IO-goodbye not loadable: Metric (TFM) file not found.\parni +<to be read again> \parni +\tenspaces\fivespaces\ \ \ \ \bs par\parni +l.8 \parni +\ \parni +? \endverbatim + +You can see that the subdirectory {\tt trioo} (see rule~1) is +mentioned in the case of \cs\openout. Of course, +an \cs\immediate\cs\openout\ is signaled by ``immediate openout'' +instead of ``openout'' in the line that starts with {\tt TrIO >>>}. + + + + +\beginsection 9. Remarks about {\tt openin.tex} and {\tt openout.tex} + +The \TeX\ commands \cs\openin\ and \cs\openout\ are less verbose +than \cs\input\ with respect to the file name they have to process. As +they occur less frequently than \cs\input\ the macros implement a +two-step procedure to enter the file names for \cs\openin\ +and \cs\openout. This slow-down in the workflow gives the user a +chance to avoid hasty decisions. + +But I assume some users want to have a faster processing. Here are two +ideas how to speed-up the workflow. (1)~The file {\tt openin.tex} and +{\tt openout.tex} aren't called by other files of the package; they +are only entered by the user. Thus, a user can rename them to make the +names easier to type. (The names are used in messages (see {\tt +TrIOmacros.org}) so either change them there too or remember that you +have changed the file names.) (2)~The files stop with a private +message whereas {\tt TrIOinput.tex} just outputs such a message. If +you check all private messages carefully you can change the code in +{\tt openin.tex} and {\tt openout.tex} so that it displays the private +message on the terminal without using \cs\pausing\ to avoid to enter +{\tt<return>}.\looseness=-1 + + + + +\beginsection 10. Precautionary warning + +As you saw the macros cannot run without user interaction. This means, +your knowledge about plain \TeX\ is a crucial success factor if +problems occur. You must be able to distinguish if an error message is +based on TrIO's actions, or if it's an aggressive attempt to +circumvent TrIO, or if it's a simple error in the source. + +Above I wrote that you should have a non-beginner's knowledge of +plain \TeX. Now you should be aware that your knowledge about the +original \TeX, plain \TeX, the command {\tt\bs special} and its risks, +as well as tools like {\tt dvitype}, {\tt sed}, etc.\ are important. + +As soon as you don't understand what happens in the untrusted source +stop the execution by \TeX. Stop the execution in an error situation +if you don't understand what you have to do with TrIO. + +\bye |