diff options
author | Norbert Preining <norbert@preining.info> | 2020-03-15 03:01:24 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2020-03-15 03:01:24 +0000 |
commit | 87cddce361c3b477029d13b27bdaa57190b2d74b (patch) | |
tree | 0b8f15ef416645c1438cdc4228a1ddb44691b17c /macros/luatex/optex/ref-file.opm | |
parent | 942e56ba7d147d18d379305e76f064cec0aade7d (diff) |
CTAN sync 202003150301
Diffstat (limited to 'macros/luatex/optex/ref-file.opm')
-rw-r--r-- | macros/luatex/optex/ref-file.opm | 120 |
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. |