summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/protex/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/protex/README')
-rw-r--r--Master/texmf-dist/doc/latex/protex/README615
1 files changed, 613 insertions, 2 deletions
diff --git a/Master/texmf-dist/doc/latex/protex/README b/Master/texmf-dist/doc/latex/protex/README
index 3dc877b8979..bcbfaa67a0b 100644
--- a/Master/texmf-dist/doc/latex/protex/README
+++ b/Master/texmf-dist/doc/latex/protex/README
@@ -1,2 +1,613 @@
-Documentation can be found at
- http://www.cse.ohio-state.edu/~gurari/systems.html \ No newline at end of file
+ \ifx\documentstyle\UnDef\else\documentstyle{report}\begin{document}\fi
+ \input ProTex.sty \def\CodeDel{{<<<-}{->>>}}
+ \AlProTex{tex,<<<>>>,|,title,ClearCode} \<\><<<-
+
+ProTex is Eitan Gurari's literate programming environment for TeX.
+His monumental tex4ht package (http://ctan.org/pkg/tex4ht) uses it.
+
+FILES
+=====
+ProTex.sty -- Basic environment for literate programming
+AlProTex.sty -- Adjustments to ProTeX
+README -- Introduction and examples for main features
+ of (Al)ProTeX (this file)
+
+MANUAL
+======
+Eitan Gurari, TeX and LaTeX: Drawing and Literate Programming.
+ McGraw-Hill, 1994. ISBN 0-07-025208-4 / 0-07-911616-7
+The dratex package described there is at http://ctan.org/pkg/dratex.
+Various ProTex examples are in that package's file Examples.tex.
+
+Table of Contents
+=================
+A. A Basic Literate Programming Environment
+B. Other Basic Literate Programming Environments
+C. Environments for Multi-Module Programs
+D. Code and Documentation Produced from Same Specification
+E. Examples B, C, D
+F. License
+
+ The code for the examples can be extracted from this file
+ by renaming this file to LitProg.tex and compiling the
+ file with TeX or LaTeX (the Makefiles for Example C, however,
+ must be extracted mannually). The compilation puts the code
+ in files progA.tex, progB.tex, progC.tex, main.tex,
+ aux.tex, macros.tex, progC.sty, and progD.tex.
+
+A. A Basic Literate Programming Environment
+===========================================
+
+ \input ProTex.sty
+ \AlProTex{EXT,<<<>>>,title,list,[],`}
+
+This environment adds to (La)TeX the following commands for handling code.
+
+a. Definitions of code fragments \<code title\><<<
+ code fragment>>>
+
+b. References to code segments `<code title`>
+
+c. Output files of code \OutputCode[EXTENSION]\<code title\>
+ `[EXTENSION]' is optional
+ when EXTENSION = EXT
+
+d. References to the character `
+ within code fragments ``
+
+Warning: Do not use 2 or more consecutive blank characters
+ in `<code title`>
+
+------- Example A: Single-Module C Program ----------------------------------
+------- Put in file progA.tex and compile with LaTeX ------%->>>\<progA\><<<-
+
+\documentstyle{book}
+
+\input ProTex.sty
+\AlProTex{c,<<<>>>,title,list,[],`}
+
+\begin{document}
+
+\<body\><<<
+printf("\n ``hello everybody``");
+>>>
+
+\<prog A\><<<
+`<include`>
+main()
+{
+ `<body`>
+}
+>>>
+
+\<include\><<<
+#include <stdio.h>
+>>>
+
+\<body\><<<
+printf("\n");
+>>>
+
+\OutputCode\<prog A\> \end{document}
+
+------------ End Example A -----------------%->>>\OutputCode\<progA\>\<\><<<-
+
+
+B. Other Basic Literate Programming Environments
+================================================
+
+a. Framing of code fragments can be requested with the option [[]]
+ in \AlProTex, e.g.,
+
+ \AlProTex{EXT,<<<>>>,title,list,[],`,[[]]}
+
+b. Framing of code titles can be avoided by removing the option []
+ from \AlProTex, e.g,
+
+ \AlProTex{EXT,<<<>>>,title,list,`}
+
+c. The characters @, |, and ? can also act as escape characters within
+ code fragments (e.g., replace all appearances of ` with @ in Example A).
+
+d. Line breaks within listing of code can be obtained with the command `NL%
+
+e. Comments within listing of code can be obtained with commands of
+ the form `%...`%
+
+f. The choice of code-delimiters <<< and >>> can be changed by placing
+ a command of the form \def\CodeDel{{open delimiter}{close delimiter}}
+ before \AlProTex.
+
+g. The following command requests that future \OutputCode commands identify
+ the titles of the different code fragments. (Other information, like
+ page numbers in documents and line numbers in source files, can also
+ be incorporated.)
+
+ \Comment{open-comment delimiter}{close-comment delimiter}
+
+PLEASE EXAMINE AND RUN EXAMPLE B
+
+
+C. Environments for Multi-Module Programs
+=========================================
+
+Multi-module programs can be divided into independent (La)TeX files
+that can be compiled either separately or together. For instance,
+in Example C
+
+1. Three modules (main, aux, and macros) are defined independently
+ (in main.tex, aux.tex, macros.tex) and are connected through a
+ joint root file (progC.tex). The different files import a
+ common style file (progC.sty).
+
+ progC.tex Root file
+ main.tex LaTeX file for first module
+ aux.tex LaTeX file for second Module
+ macros.tex LaTeX file for third module
+ progC.sty Style file (imported by each of the above files)
+ make files Unix management programs
+
+2. The files can be compiled separately (latex main.tex, latex aux.main,
+ latex macros.tex) or jointly (latex progC.tex).
+
+3. To allow quick generation, compilation, and linkage of C-code files
+ (see, e.g., the make files), joint compilations do not revise code
+ files.
+
+4. Separate compilations use chapter/section/subsection/subsubsection/page
+ numbers that are collected in joint compilations.
+
+5. In joint compilations, each module ends with an index to its code titles.
+
+6. To allow nonrelated identical titles in different modules, and to
+ save on memory, previous definitions of code fragments are deleted at
+ the start of each module.
+
+PLEASE RUN AND EXAMINE EXAMPLE C
+
+D. Code and Documentation Produced from Same Specification
+==========================================================
+
+Example D demonstrates how math formulas and their code can be generated
+from joint specifications.
+
+PLEASE EXAMINE AND RUN EXAMPLE D
+
+
+
+E. Examples B, C, D
+===================
+
+------- Example B: Variant of Example A -------------------------------------
+------- Put in file progB.tex and compile with LaTeX ------%->>>\<progB\><<<-
+
+\documentstyle{book}
+
+ \input ProTex.sty
+\def\CodeDel{{}{////}}
+\Comment{
+/*}{*/
+}
+ \AlProTex{c,<<<>>>,title,list,[],`}
+
+\begin{document}
+
+\<body\>
+printf("\n ``hello everybody`` within a long`NL% line of text");
+////
+
+\<prog B\>
+`<include`>
+main()
+{
+ `<body`> `%a comment`%
+}
+////
+
+\<include\>
+#include <stdio.h>
+////
+
+\<body\>
+printf("\n");
+////
+
+\OutputCode\<prog B\> \end{document}
+------------ End Example B -----------------%->>>\OutputCode\<progB\>\<\><<<-
+
+
+
+------------ Example C: Multi-Module C Program ------------------------------
+............ File progC.tex ...............................%->>>\<progC\><<<-
+
+\def\Root{}
+\input progC.sty
+
+\INPUT{main} % import first module
+
+\INPUT{aux} % import second module
+
+\INPUT{macros} % import third module
+
+\end{document}
+............ End file progC.tex .............%->>>\OutputCode\<progC\>\<\><<<-
+
+............ File main.tex ..................................%->>>\<main\><<<-
+\input progC.sty
+
+\<include files\><<<
+#include "aux.h"
+#include "macros.h"
+#include <stdio.h>
+>>>
+
+\chapter{Outline}
+
+All the code in this module is included in file main.c.
+
+\section{The Main Program}
+
+This program does not handle the case in which the input consists just
+of one 0.
+
+\<main.c\><<<
+int main()
+{
+ `<main's vars`>
+ `<read input values, count them, and record their sum`>
+ `<compute and output the average of the input values`>
+ exit(0);
+}
+>>>
+
+\chapter{The Actual Actions}
+
+\section{Process the Input Values}
+
+The input must end with 0.
+
+\<read input values, count them, and record their sum\><<<
+initialize_sum_count();
+WHILE TRUE DO
+ printf("\n Value (0 to stop)? ");
+ scanf("%d", &value);
+ IF value == 0 THEN break; FI
+ add_value(value);
+END
+>>>
+
+\<main's vars\><<<
+int value;
+>>>
+
+\section{Find the Result and Print It Out}
+
+\<compute and output the average of the input values\><<<
+result = get_average();
+printf("\n Average = %f\n", result);
+>>>
+
+\<main's vars\><<<
+double result;
+>>>
+
+\BYE{ \OutputCodE\<main.c\> }
+............ End file main.tex ..............%->>>\OutputCode\<main\>\<\><<<-
+
+............ File aux.tex ...................................%->>>\<aux\><<<-
+\input progC.sty
+
+\chapter{Reusable Functions}
+
+\section{Shared Variable}
+
+The following code is included in reusable.c.
+
+\<vars\><<<
+int count;
+double sum;
+>>>
+
+\section{Setting Initial Conditions}
+
+The following code is included in reusable.h.
+
+\<export functions\><<<
+void initialize_sum_count();
+>>>
+
+The following code is included in reusable.c.
+
+\<functions\><<<
+void initialize_sum_count()
+{
+ count = 0;
+ sum = 0.0;
+}
+>>>
+
+\section{Processing New Values}
+
+\<export functions\><<<
+void add_value();
+>>>
+
+
+\<functions\><<<
+void add_value(value)
+{
+ count++;
+ sum += value;
+}
+>>>
+
+
+\section{Computing the Average}
+
+\<export functions\><<<
+double get_average();
+>>>
+
+\<functions\><<<
+double get_average()
+{
+ return sum / count;
+}
+>>>
+
+Old files reusable.h and reusable.c are replaced when this
+file (i.e., reusable.tex) is compiled, but not when progC.tex is compiled.
+
+\BYE{ \OutputCodE\<aux.h\>
+ \OutputCodE\<aux.c\> }
+............ End file aux.tex ................%->>>\OutputCode\<aux\>\<\><<<-
+
+............ File macros.tex .............................%->>>\<macros\><<<-
+\input progC.sty
+
+\chapter{C Macros}
+
+Algol-oriented flavor.
+
+\<macros.h\><<<
+#define TRUE 1
+#define IF if (
+#define THEN ) {
+#define ELSE }else{
+#define ELSEIF }else if(
+#define FI }
+#define WHILE while(
+#define FOR for(
+#define WITH ;
+#define STEP ;
+#define DO ){
+#define BEGIN {
+#define END }
+#define CASE switch(
+#define OF ){
+>>>
+
+\BYE{ \OutputCodE\<macros.h\> }
+............ End file macros.tex ..........%->>>\OutputCode\<macros\>\<\><<<-
+
+............ File progC.sty .....................%->>>\ClearCode\<progC\><<<-
+\ifx\Code\undefined
+
+ \hbadness=10000 \vbadness=10000 \hfuzz=99in \vfuzz=99in
+ \ifx \documentstyle\UnDef
+ %load private style
+ \else
+ \documentstyle{book}
+ \let\cleardoublepage=\clearpage
+ \begin{document}
+ \fi
+ \input ProTex.sty
+
+ \ifx \Root\UnDef
+ \AlProTex{c,<<<>>>,[],list,title,`,_^,ClearCode}
+ \else
+ \AlProTex{c,<<<>>>,[],list,title,`,_^,ClearCode,ShowIndex}
+ \let\SvShowIndex=\ShowIndex
+ \def\ShowIndex{\let\ShowIndex=\SvShowIndex}
+ \fi
+ \def\CodeId#1#2{#1.#2-pg:\the\pageno-ln:\the\inputlineno}
+
+ \let\FileName=\jobname
+ \def\INPUT#1{
+ \def\FileName{#1}
+ \immediate\openout15=#1.pg
+ \immediate\write15{%
+ \string \pageno=\the\pageno\string \relax
+ \string \csname\space c@page\string \endcsname =
+ \expandafter\the\csname c@page\endcsname\string \relax
+ \string \csname\space c@chapter\string \endcsname =
+ \expandafter\the\csname c@chapter\endcsname\string \relax
+ \string \csname\space c@section\string \endcsname =
+ \expandafter\the\csname c@section\endcsname\string \relax
+ \string \csname\space c@subsection\string \endcsname =
+ \expandafter\the\csname c@subsection\endcsname\noexpand\relax
+ \string \csname\space c@subsubsection\string \endcsname =
+ \expandafter\the\csname c@subsubsection\endcsname\noexpand\relax
+ }
+ \immediate\closeout15
+ \input #1
+ }
+
+ \ifx \documentstyle\UnDef \errmessage{--- This is a LaTeX file ---}\fi
+ \title{Averaging Numbers}
+ \date{2 October 1994}
+ \maketitle
+ \tableofcontents
+
+ \openin15=\jobname.pg
+ \ifeof15 \else \input \jobname.pg \fi
+ \closein15
+ \def\OutputCodE\<#1.#2\>{%
+ \csname :DoName\endcsname\def{#1}{\<#1.#2\>}%
+ \OutputCode[#2]\<#1\>}
+ \let\xxxOutputCode=\OutputCodE
+ \def\xxOutputCode\<#1.#2\>{%
+ \openin15=#1.#2
+ \ifeof15 \xxxOutputCode\<#1.#2\>\fi
+ \closein15 }
+\fi
+
+\ifx \BYE\undefined \def\BYE#1{#1\end{document}}
+\else \def\BYE#1{{\let\OutputCodE=\xxOutputCode #1}%
+ \ShowIndex\ClearCode}\fi
+
+ \ifx\Root\NotDef
+\vfill\break\noindent\hfil\underbar{\bf INPUT FILE: \FileName .tex}
+
+\<\FileName.h\><<<
+`<export define`>
+`<export types`>
+`<export vars`>
+`<export functions`>
+>>>
+
+\<\FileName.c\><<<
+`<include files`>
+`<define`>
+`<types`>
+`<header functions`>
+`<vars`>
+`<functions`>
+>>>
+
+ \else \let\Root=\NotDef \fi
+
+\Comment{
+/*}{*/
+}
+
+............ End file progC.sty ........%->>>\OutputCode[sty]\<progC\>\<\><<<-
+
+............ Make file 1 .....................................................
+# make -fS make.1
+# call LaTeX and C for revised files
+
+all : progC
+ progC
+
+main.c: main.tex
+ rm -f main.llog
+ latex main > main.llog
+
+aux.c: aux.tex
+ rm -f aux.llog
+ latex aux > aux.llog
+
+aux.h: aux.tex
+ rm -f aux.llog
+ latex aux > aux.llog
+
+macros.h: macros.tex
+ rm -f macros.llog
+ latex macros > macros.llog
+
+aux.o: aux.c aux.h macros.h
+ cc -c aux.c
+
+main.o: main.c aux.h macros.h
+ cc -c main.c
+
+progC : main.o aux.o
+ cc -o progC main.o aux.o
+
+............ End make file 1 ................................................
+............ Make file 2 ....................................................
+# make -fS make.2
+# call LaTeX in background for revised files
+
+all : main.c aux.c macros.h
+
+main.c: main.tex
+ rm -f main.llog
+ latex main > main.llog &
+
+aux.c: aux.tex
+ rm -f aux.llog
+ latex aux > aux.llog &
+
+macros.h: macros.tex
+ rm -f macros.llog
+ latex macros > macros.llog &
+
+............ End make file 2 .................................................
+------------ End Example C -------------------------------------------------
+
+
+
+------------ Example D: Joint Specification --------------%->>>\<progD\><<<-
+\documentstyle{report}
+\input ProTex.sty
+\AlProTex{code,<<<>>>,[],title,list}
+%......................................................................
+\def\Formula#1#2{\ifx#1\UnDefined\else\immediate\write16
+ {--- warning --- Redefine equation for \string#1 ---}\fi
+ \gdef#1{%
+ \expandafter\ifx \csname :Tb\endcsname\relax
+ \ifmmode \InMath #2
+ \else \vskip\smallskipamount\noindent\hfil
+ $ \let\InText=\relax \InMath #2 $%
+ \vskip\smallskipamount
+ \fi
+ \else #2\fi}%
+}
+\let\PrevModifyShowCode=\ModifyShowCode
+\def\ModifyShowCode{\InCode \PrevModifyShowCode }
+\let\PrevModifyOutputCode=\ModifyOutputCode
+\def\ModifyOutputCode{\InCode \PrevModifyOutputCode }
+\def\InCode{%
+ \def\divide##1##2{((##1) / (##2))}%
+ \def\sqrt##1{SQRT(##1)}%
+ \def\cdot{ * }%
+ \def\sin##1{(sin(##1))}%
+ \def\power##1##2{(##1)**(##2)}%
+ \def\NewLn{\csname :Ln\endcsname}%
+ }
+\def\InMath{%
+ \def\divide##1##2{\ifx\LaTeX\undefined{##1\over##2}\else
+ {\frac{##1}{##2}}\fi}%
+ \def\power##1##2{##1^{##2}}%
+ \def\NewLn{\ifinner
+ \ifx\InText\realx \else \hfil\break\null\hfil \fi
+ \else $$$$\InMath \fi}%
+ }
+%......................................................................
+\begin{document}
+
+Metalanguage: {\tt\string\divide}, {\tt\string\sqrt}, {\tt\string\cdot},
+{\tt\string\sin}, {\tt\string\power}, {\tt\string\NewLn}.
+
+\Formula\f{\divide{x}{\sqrt{1+\power{x}{2}}}\cdot
+ \NewLn \sin{\divide{y}{x}}}
+
+Formula \f{} and its code
+
+\<formula\><<<
+w = \f
+>>>
+
+Same formula in math modes $\f$ and $$\f$$.
+
+\OutputCode\<formula\> \end{document}
+
+------------ End Example D -----------%->>>\OutputCode\<progD\>\end{document}
+
+F. License
+==========
+% Copyright 2016 TeX Users Group
+% Copyright 1990-1999 Eitan M. Gurari
+%
+% This program can redistributed and/or modified under
+% the terms of the LaTeX Project Public License
+% Distributed from CTAN archives in directory
+% macros/latex/base/lppl.txt; either version 1 of the
+% License, or (at your option) any later version.
+%
+% This work has the LPPL maintenance status "maintained".
+%
+% The Current Maintainer of this work
+% is the TeX4ht Project <http://tug.org/tex4ht>.