optex (26apr20)

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

1 files changed, 52 insertions, 31 deletions

diff --git a/Master/texmf-dist/tex/luatex/optex/ref-file.opm b/Master/texmf-dist/tex/luatex/optex/ref-file.opm
index 5f2b50f06d2..01363ef9a97 100644
--- a/Master/texmf-dist/tex/luatex/optex/ref-file.opm
+++ b/Master/texmf-dist/tex/luatex/optex/ref-file.opm
@@ -3,7 +3,7 @@
 \_codedecl \openref {File for references <2020-02-14>} % preloaded in format
 
    \_doc --------------------------
-   The `\_inputref` macro is used in `\everyjob`. It reads `\jobname.ref` file
+   The \`\_inputref` macro is used in `\everyjob`. It reads `\jobname.ref` file
    if it exists. After the file is read then it is removed and opened to write
    a new contents to this file.
    \_cod --------------------------
@@ -14,14 +14,14 @@
   \_isfile{\_jobname.ref}\_iftrue
      \_input {\jobname.ref}
      \_gfnotenum=0 \_lfnotenum=0 \_mnotenum=0 
-     \_openrefA{\_string\inputref}%
+     \_openrefA{\_string\_inputref}%
   \_fi
 }
 
    \_doc --------------------------
    If the file does not exists then it is not created by default. It means that if you
    process a document without any forward references then no `\jobname.ref`
-   file is created because it is unusable. The `\_wref` macro is dummy in
+   file is created because it is unusable. The \^`\_wref` macro is dummy in
    such case.
    \_cod --------------------------
 
@@ -29,9 +29,12 @@
 \_let\_wref=\_wrefrelax
 
    \_doc ---------------------
-   If a macro needs to ceate and to use `.ref` file then such file must be created by
-   `\_openref`. When the file is created (using internal `\_openrefA`) then
-   `\_opneref` destroys itself, because we need not to open the file again.
+   If a macro needs to ceate and to use `.ref` file then such macro must use
+   \`\openref`. When the file is created (using internal \`\_openrefA`) then
+   the \`\_wref` `\<macro>{<data>}` is redefined in order to 
+   save the line `\<macro><data>` to the `.ref` file using asynchronous
+   `\write` primitive. Finally, the `\_openref` destroys itself, because we 
+   need not to open the file again.
    \_cod ---------------------
 
 \_def\_openref {%
@@ -47,31 +50,40 @@
 \def\openref{\_openref}
 
    \_doc ----------------------
-   We are using a convention that the macros used in `.ref` file are named
-   `\_X<foo>`. If there is a new wersion of \OpTeX/ with different collection
+   We are using convention that the macros used in `.ref` file are named
+   `\_X<foo>`. If there is a new version of \OpTeX/ with different collection
    of such macros then we don't want to read the `.ref` files produced by an 
-   old version of \OpTeX/ or by OPmac. So first line of `.ref` line is in 
+   old version of \OpTeX/ or by OPmac. So first line of `.ref` file is in 
    the form
-   \begtt
+   \begtt \catcode`\<=13
    \Xrefversion{<version>}
    \endtt 
    We can check the version compatibility by this macro.
    Because OPmac does not understand `\_Xrefversion` we use 
-   `\Xrefversion` (different form OPmac) here.
+   \`\Xrefversion` (with different number of `<version>` form OPmac) here.
+   The result: OPmac skips the `.ref` files produced by \OpTeX/ and vice
+   versa.
    \_cod ----------------------
 
-\_def\_REFversion{3} % actual version of .ref files
+\_def\_REFversion{3} % actual version of .ref files in OpTeX
 \_def\_Xrefversion#1{\_ifnum #1=\_REFversion\_relax \_else \_endinput \_fi}
 \_public \Xrefversion ; % we want to ignore .ref files generated by OPmac
 
    \_doc -----------------------
-   You cannot define your special `.ref` macos before `.ref` file is read
+   You cannot define your special `.ref` macros before `.ref` file is read
    because it is read in `\everyjob`. But you can define such macros using
-   `\refdecl{<definitions of your ref macros>}`.
-   This command sends to `.ref` file your <definitions of your ref macros>
-   immediately. Next lines in `.ref` file should include our macros.
-   
-   We must read <definition of your ref macros> when catcode of `#` is 12
+   \`\refdecl``{<definitions of your ref macros>}`.
+   This command sends to `.ref` file your `<definitions of your ref macros>`
+   immediately. Next lines in `.ref` file should include our macros. Example
+   from CTUstyle2:
+   \begtt
+   \refdecl{%
+      \def\totlist{} \def\toflist{}^^J
+      \def\Xtab#1#2#3{\addto\totlist{\totline{#1}{#2}{#3}}}^^J
+      \def\Xfig#1#2#3{\addto\toflist{\tofline{#1}{#2}{#3}}}
+   }
+   \endtt
+   We must read `<definition of your ref macros>` when catcode of `#` is 12
    because we needn't to duplicate each `#` in the `.ref` file.
    \_cod \_fin -----------------
 
@@ -85,9 +97,14 @@
 \_endcode % ================================================
 
 
-The REF file looks like:
+The `.ref` file has the name `\jobname.ref` and 
+it saves information about references, TOC lines, etc. 
+All data needed in next \TeX/ run are saved here.
+\OpTeX/ reads this file at the beginning of the document 
+(using `\everyjob`) if such file exists.
+The `.ref` file looks like:
 
-\begtt
+\begtt \catcode`\<=13
 \Xrefversion{<ref-version>}
 \_Xpage{<gpageno>}{<pageno>}
 \_Xtoc{<level>}{<type>}{<text>}{<title>}
@@ -98,19 +115,23 @@ The REF file looks like:
 \_Xlabel{<label>}{<text>}
 ...
 \endtt
-
-where <gpageno> is internal page number numbered from one and <pageno> is
-a page number used in pagination. Each page begins with `\_Xpage`.
-The <label> is <label> used by user in `\label[<label>]` and <text> is a
-<text> which should be referenced (the number of section or table, for
-example `2.3.14`). The <title> is a tile of the chapter (<level>=1,
-<type>=`chap`), section (<level>=2, <type>=`sec`), subsection 
-(<level>=3, <type>=`secc`). The `\_Xpage` is written at begining of each
+%
+where <gpageno> is internal page number globally numbered from one and 
+`<pageno>` is a page number (`\the\pageno`) used in pagination (they may be differ). 
+Each page begins with `\_Xpage`.
+The `<label>` is a label used by user in `\label[<label>]` and `<text>` is a
+text which should be referenced (the number of section or table, for
+example `2.3.14`). The `<title>` is a title of the chapter (`<level>`=1,
+`<type>`=`chap`), section (`<level>`=2, `<type>`=`sec`), subsection 
+(`<level>`=3, `<type>`=`secc`). The `\_Xpage` is written at begining of each
 page, the `\_Xtoc` is written when chapter or section or subsection title
 exists on the page and `\_Xlabel` when labeled object prefixed by
 `\label[<label>]` exists on the page. 
 
 The `.ref` file is read when the processing of the document starts using
-`\everyjob`. It is removed and opened to writting immediately when it is read.
-But the `.ref` file should be missing. If none references are needed in the
-document then `.ref` file is not created.
+`\everyjob`. It is read, removed and opened to writing immediately.
+But the `.ref` file should be missing. If none forward references are needed 
+in the document then `.ref` file is not created. For example, you only want
+to test a simple plain \TeX/ macro, you create `test.tex` file, you do
+`optex test` and you don't need to see empty `test.ref` file in your directory. 
+