summaryrefslogtreecommitdiff
path: root/macros/optex/base/ref-file.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/optex/base/ref-file.opm')
-rw-r--r--macros/optex/base/ref-file.opm135
1 files changed, 72 insertions, 63 deletions
diff --git a/macros/optex/base/ref-file.opm b/macros/optex/base/ref-file.opm
index 8c459f7de5..95e960bc12 100644
--- a/macros/optex/base/ref-file.opm
+++ b/macros/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``{<file>}` 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` `\<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 open the file again.\nl
- The `\_wref``<csname>{<params>}` does exactly `\write\_reffile{\string<csname><params>}`
- in this case and \`\_ewref``<csname>{<params>}` 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` `\<macro>{<data>}` so that it
+ saves the line `\<macro><data>` 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``<csname>{<params>}` in fact does `\write\_reffile{\string<csname><params>}`
+ and similarly \`\_ewref``<csname>{<params>}` does
`\write\_reffile{\string<csname><expanded-params>}`.
\_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<foo>`. 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<foo>`.
+ 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{<version>}
\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 `<version>` form OPmac) here.
- The result: OPmac skips the `.ref` files produced by \OpTeX/ and vice
+ `\Xrefversion` (with a different number of `<version>` 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``{<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:
+ This command immediately writes `<definitions of your ref macros>` 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 `<definition of your ref macros>` when the catcode of `#` is 12
- because we needn't duplicate each `#` in the `.ref` file.
+ We must read `<definitions of your ref macros>` 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{<ref-version>}
@@ -119,29 +129,28 @@ The `.ref` file looks like:
\_Xlabel{<label>}{<text>}
...
\endtt
-%
-where <gpageno> is internal page number globally numbered from one and
-`<pageno>` is a page number (`\the\pageno`) used in pagination (they may 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 the title of the chapter (`<level>`=1,
-`<type>`=`chap`), section (`<level>`=2, `<type>`=`sec`), subsection
-(`<level>`=3, `<type>`=`secc`). The \^`\_Xpage` is written at the beginning 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 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 an empty `test.ref` file in your directory.
+
+\begitems
+* \^`\_Xpage` corresponds to the beginning of a page. <gpageno> is an internal
+page number, globally numbered from one. `<pageno>` is the page number
+(`\the\pageno`) used in pagination (they may differ).
+
+* \^`\_Xtoc` corresponds to a chapter, section or subsection title on a page.
+`<title>` is the title of the chapter (`<level>`=1, `<type>`=`chap`), section
+(`<level>`=2, `<type>`=`sec`) or subsection (`<level>`=3, `<type>`=`secc`).
+
+* \^`\_Xlabel` corresponds to a labelled object on a page. `<label>` is the
+label provided by the user in \^`\label[<label>]`, while `<text>` is the text
+which should be used for the reference (section or table number, for example
+`2.3.14`).
+\enditems
+
\_endinput
History:
+2021-07-19 \openrefA merged to \openref
+2021-07-18 ref file consistency checking added
2021-04-13 \Xrefversion incremented (6), new format of \_Xbib
2021-02-05 \_ewref introduced
2020-02-14 released