summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/ref-file.opm
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-03-15 03:01:24 +0000
committerNorbert Preining <norbert@preining.info>2020-03-15 03:01:24 +0000
commit87cddce361c3b477029d13b27bdaa57190b2d74b (patch)
tree0b8f15ef416645c1438cdc4228a1ddb44691b17c /macros/luatex/optex/ref-file.opm
parent942e56ba7d147d18d379305e76f064cec0aade7d (diff)
CTAN sync 202003150301
Diffstat (limited to 'macros/luatex/optex/ref-file.opm')
-rw-r--r--macros/luatex/optex/ref-file.opm120
1 files changed, 87 insertions, 33 deletions
diff --git a/macros/luatex/optex/ref-file.opm b/macros/luatex/optex/ref-file.opm
index e16e89ab7b..ba76563ca0 100644
--- a/macros/luatex/optex/ref-file.opm
+++ b/macros/luatex/optex/ref-file.opm
@@ -1,19 +1,39 @@
%% This is part of OpTeX project, see http://petr.olsak.net/optex
-\_codedecl \_openref {references <2020-02-14>}
+\_codedecl \_openref {File for references <2020-02-14>}
-\_newwrite\_reffile
+ \_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.
+ \_cod --------------------------
-\_def\_wrefrelax#1#2{}
-\_let\_wref=\_wrefrelax
+\_newwrite\_reffile
\_def\_inputref {%
\_isfile{\_jobname.ref}\_iftrue
- \input {\jobname.ref}
- \_fnotenum=0 \_mnotenum=0
+ \_input {\jobname.ref}
+ \_gfnotenum=0 \_lfnotenum=0 \_mnotenum=0
\_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
+ such case.
+ \_cod --------------------------
+
+\_def\_wrefrelax#1#2{}
+\_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.
+ \_cod ---------------------
+
\_def\_openref {%
\_ifx \_wref\_wrefrelax \_openrefA{\_string\openref}\_fi
\_gdef\_openref{}%
@@ -21,41 +41,75 @@
\_def\_openrefA #1{%
\_immediate\_openout\_reffile="\_jobname.ref"\_relax
\_gdef\_wref ##1##2{\_write\_reffile{\_string##1##2}}%
- \_immediate\_write\_reffile {\_pcent\_pcent\_space OPTeX - REF file (#1)}%
- \_immediate\_wref \_Xrefversion{{\_REFversion}}%
+ \_immediate\_write\_reffile {\_pcent\_pcent\_space OPTeX <\_optexversion> - REF file (#1)}%
+ \_immediate\_wref \Xrefversion{{\_REFversion}}%
}
-\_def\_REFversion{3}
-\_def\_Xrefversion#1{\_ifnum #1=\_REFversion\_relax \_else \_endinput \_fi}
-\_def\_Xprocess#1{#1}
-\_public \Xrefversion ;
+ \_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
+ 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
+ the form
+ \begtt
+ \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.
+ \_cod ----------------------
-\_endcode % -------------------------------------
+\_def\_REFversion{3} % actual version of .ref files
+\_def\_Xrefversion#1{\_ifnum #1=\_REFversion\_relax \_else \_endinput \_fi}
+\_public \Xrefversion ; % we want to ignore .ref files generated by OPmac
-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.
+ \_doc -----------------------
+ You cannot define your special `.ref` macos 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
+ because we needn't to duplicate each `#` in the `.ref` file.
+ \_cod \_fin -----------------
-If the file does not exists then it is not created. 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 unusable in
-such case.
+\_def\_refdecl{\bgroup \catcode`\#=12 \_refdeclA}
+\_def\_refdeclA #1{\egroup\_openref
+ \_immediate\_write\_reffile {\_pcent\_space \_string \refdecl:}%
+ \_immediate\_write\_reffile {\_detokenize{#1}}%
+}
+\_public \refdecl ;
-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.
+\_endcode % ================================================
-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
-of such macros then we don't want to read the REF files produced by an
-old version of \OpTeX/. So first line of REF line is in the form
-\begtt
-\_Xrefversion{<version>}
-\endtt
+The REF file looks like:
-We can check the verion compatibility by this macro.
+\begtt
+\Xrefversion{<ref-version>}
+\_Xpage{<gpageno>}{<pageno>}
+\_Xtoc{<level>}{<type>}{<text>}{<title>}
+\_Xlabel{<label>}{<text>}
+\_Xlabel{<label>}{<text>}
+...
+\_Xpage{<gpageno>}{<pageno>}
+\_Xlabel{<label>}{<text>}
+...
+\endtt
-User can write the `\_openref\_wref\_Xpocess{<comething>}` at beginning of
-the document if he/she needs to define a macros used in REF file later.
+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
+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.