From c2c9833536fa0937fe30f59d2d1f162585eb9e9d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 26 Aug 2021 21:26:41 +0000 Subject: optex (26aug21) git-svn-id: svn://tug.org/texlive/trunk@60332 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/tex/optex/base/ref-file.opm | 135 ++++++++++++++------------ 1 file changed, 72 insertions(+), 63 deletions(-) (limited to 'Master/texmf-dist/tex/optex/base/ref-file.opm') diff --git a/Master/texmf-dist/tex/optex/base/ref-file.opm b/Master/texmf-dist/tex/optex/base/ref-file.opm index 8c459f7de56..95e960bc12a 100644 --- a/Master/texmf-dist/tex/optex/base/ref-file.opm +++ b/Master/texmf-dist/tex/optex/base/ref-file.opm @@ -1,85 +1,97 @@ %% This is part of the OpTeX project, see http://petr.olsak.net/optex -\_codedecl \openref {File for references <2021-04-13>} % preloaded in format +\_codedecl \openref {File for references <2021-07-19>} % preloaded in format \_doc -------------------------- - 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. + The \`\_inputref` macro is executed in `\everyjob`. It reads the + `\jobname.ref` file, if it exists. After the file is read then it is removed + and opened for writing. \_cod -------------------------- \_newwrite\_reffile \_def\_inputref {% \_isfile{\_jobname.ref}\_iftrue - \_input {\_jobname.ref} + \_input {\_jobname.ref}% + \_edef\_prevrefhash{\_mdfive{\_jobname.ref}}% \_gfnotenum=0 \_lfnotenum=0 \_mnotenum=0 - \_openrefA{\_string\_inputref}% + \_openref \_fi } \_doc -------------------------- - If the file does not exist then it is not created by default. It means that if you + \`\_mdfive``{}` expands to the MD5 hash of a given file. + We use it to do consistency checking of the `.ref` file. First, we read the MD5 hash + of `.ref` file from previous \TeX/ run before it is removed and opened for + writing again in the \^`\_inputref` macro. The hash is saved to \`\_prevrefhash`. + Second, we read the MD5 hash in the \^`\_byehook` macro again and if + these hashes differ, warning that \"ref file has changed" is + printed. Try running `optex op-demo` twice to see the effect. + \_cod -------------------------- + +\_def\_mdfive#1{\_directlua{mdfive("#1")}} +\_def\_prevrefhash{} + + \_doc -------------------------- + If the `.ref` file does not exist, then it is not created by default. This 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 a dummy in - this case. + file is created (it would be unusable). The \^`\_wref` macro is a dummy in + that case. \_cod -------------------------- \_def\_wrefrelax#1#2{} \_let\_wref=\_wrefrelax \_doc --------------------- - If a macro needs to create and to use `.ref` file then such macro must use - \`\openref`. When the file is created (using internal \`\_openrefA`) then - the \`\_wref` `\{}` is redefined in order to - save the line `\` to the `.ref` file using asynchronous - `\write` primitive. Finally, the `\_openref` destroys itself, because we - need not open the file again.\nl - The `\_wref``{}` does exactly `\write\_reffile{\string}` - in this case and \`\_ewref``{}` does + If a macro needs to create and use the `.ref` file, then such macro must + first use \`\openref`. It creates the file and redefines + \`\_wref` `\{}` so that it + saves the line `\` to the `.ref` file using the asynchronous + `\write` primitive. Finally, `\_openref` destroys itself, because we + don't need to open the file again.\nl + `\_wref``{}` in fact does `\write\_reffile{\string}` + and similarly \`\_ewref``{}` does `\write\_reffile{\string}`. \_cod --------------------- \_def\_openref {% - \_ifx \_wref\_wrefrelax \_openrefA{\_string\openref}\_fi - \_gdef\_openref{}% -} -\_def\_openrefA #1{% \_immediate\_openout\_reffile="\_jobname.ref"\_relax \_gdef\_wref ##1##2{\_write\_reffile{\_bslash\_csstring##1##2}}% - \_immediate\_write\_reffile {\_pcent\_pcent\_space OPTeX <\_optexversion> - REF file (#1)}% + \_immediate\_write\_reffile {\_pcent\_pcent\_space OpTeX <\_optexversion> - REF file}% \_immediate\_wref \Xrefversion{{\_REFversion}}% + \_gdef\_openref{}% } \_def\_ewref #1#2{\_edef\_ewrefA{#2}\_ea\_wref\_ea#1\_ea{\_ewrefA}} \_def\openref{\_openref} \_doc ---------------------- We are using the convention that the macros used in `.ref` file are named - `\_X`. If there is a new version of \OpTeX/ with a 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 the first line of `.ref` file is in - the form + `\_X`. + We don't want to read `.ref` files from old, incompatible versions of + \OpTeX/ (and OPmac). This is ensured by using a version number and the + \`\Xrefversion` macro at the beginning of the `.ref` file: \begtt \catcode`\<=13 \Xrefversion{} \endtt - We can check the version compatibility by this macro. + The macro checks the version compatibility. Because OPmac does not understand `\_Xrefversion` we use - \`\Xrefversion` (with a different number of `` form OPmac) here. - The result: OPmac skips the `.ref` files produced by \OpTeX/ and vice + `\Xrefversion` (with a different number of `` than OPmac) here. + The result: OPmac skips `.ref` files produced by \OpTeX/ and vice versa. \_cod ---------------------- -\_def\_REFversion{6} % actual version of .ref files in OpTeX +\_def\_REFversion{6} % current 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` macros before `.ref` file is read - because it is read in `\everyjob`. But you can define such macros using + You cannot define your own `.ref` macros before `.ref` file is read + because it is read in `\everyjob`. But you can define such macros by using \`\refdecl``{}`. - This command sends to `.ref` file your `` - immediately. Next lines in `.ref` file should include our macros. Example - from CTUstyle2: + This command immediately writes `` to the + `.ref` file. Then the next lines written to the `.ref` file can include + your macros. + An example from CTUstyle2: \begtt \refdecl{% \def\totlist{} \def\toflist{}^^J @@ -87,8 +99,8 @@ \def\Xfig#1#2#3{\addto\toflist{\tofline{#1}{#2}{#3}}} } \endtt - We must read `` when the catcode of `#` is 12 - because we needn't duplicate each `#` in the `.ref` file. + We must read `` while `#` has the catcode 12, + because we don't want to duplicate each `#` in the `.ref` file. \_cod \_fin ----------------- \_def\_refdecl{\_bgroup \_catcode`\#=12 \_refdeclA} @@ -100,13 +112,11 @@ \_endcode % ================================================ - -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: +A so called `.ref` (`\jobname.ref`) file is used to store data that will be +needed in the next \TeX/ run (information about references, TOC lines, etc.). +If it exists it is read by `\everyjob`, when processing of the document starts, +but it is not created at all if the document doesn't need any forward +references. Here are the typical contents of a `.ref` file: \begtt \catcode`\<=13 \Xrefversion{} @@ -119,29 +129,28 @@ The `.ref` file looks like: \_Xlabel{