summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/transparent-io/README
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/contrib/transparent-io/README')
-rw-r--r--macros/plain/contrib/transparent-io/README86
1 files changed, 86 insertions, 0 deletions
diff --git a/macros/plain/contrib/transparent-io/README b/macros/plain/contrib/transparent-io/README
new file mode 100644
index 0000000000..bafccb3631
--- /dev/null
+++ b/macros/plain/contrib/transparent-io/README
@@ -0,0 +1,86 @@
+This package provides macros to make the file I/O in plain TeX more
+transparent. That is, every \input, \openin, and \openout operation by
+TeX is presented to the user who must check carefully what's going on
+and then has to enter several inputs including the repetition of the
+file name if the file I/O is accepted.
+
+The application of the macros requires concentration; don't execute
+TeX with an instrumented source file hastily. Moreover, to use the
+macros successfully you must have a non-beginner's knowledge of TeX.
+
+The macros are installed in an non-trivial process. The process is
+described in the manual for a UNIX-like system. You must be able to
+run sed and bash.
+
+
+>>> PACKAGE MAINTAINERS:
+This package cannot and should not be used from the TDS without an
+__individual__ installation by the user. The installation procedure
+renames the files and relocates them.
+
+
+I use the words package, program, TrIO macros, or TrIO when I refer to
+the program statements in the twelve files named either TrIO*.org (see
+below) or TrIO*.tex (six files, see below), openin.tex, openout.tex,
+TrIO*.sed (three files, see below), and TrIO.sh after the
+installation.
+
+ 1. TrIOmacros.org: main file to instrument a source file
+ 2. TrIOsupport.org: common macros to TrIOmacros.tex and TrIOauto.tex
+ 3. TrIOprivate.org: copies of control sequences and test routines
+ 4. TrIOinput.org: called for every \input
+ 5. TrIOopenin.org: entered by the user for every \openin
+ 6. TrIOopenout.org: entered by the user for every \openout
+
+ 7. TrIOextract.org: sed script to create TrIOnames.tex (see manual)
+ 8. TrIOlineno.org: another sed script to create TrIOnames.tex
+ 9. TrIOauto.org: replacement for TrIOmacros.tex in repeated executions
+10. TrIOopen.org: called for every I/O command in TrIOnames.tex
+
+11. TrIO.org: bash script to install the package
+12. TrIOinstall.org: sed script to set passwords and private messages
+
+The last two files are only used for the installation. They must be
+renamed and edited, see the manual. During their execution they will
+change and rename the other ten files.
+
+The first six files are renamed during the installation so that all
+have the extension .tex instead of .org; in the names of files 5 and 6
+the ``TrIO'' prefix is deleted too. Files 7--10 are also renamed: The
+first two become sed scripts the other two .tex files.
+
+
+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, version 3 of the License.
+
+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, see <http://www.gnu.org/licenses/>.
+
+
+The package consists of the following files:
+
+TrIO*.org -- 12 files (see above) that must be
+ customized to become an installation
+Transparent-IO-doc.pdf -- a manual that describes the installation
+ and the use of the TrIO macros
+Transparent-IO-doc.tex -- the source of the manual; it requires
+ plain TeX
+Transparent-IO-example.tex -- an example from the documentation
+Transparent-IO-eccentric.tex -- another example from the documentation
+Transparent-IO-hello.tex -- used in the above two examples
+Transparent-IO-TUGboat-danger.tex -- see the TUGboat article referenced in
+ the documentation for its relevance;
+ rename the file to ``danger.tex'' if
+ you want to run this example
+README -- this file
+
+Copyright (C) 2022 Udo Wermuth (author)
+ u dot wermuth (at) icloud dot com
+
+