%% This is part of OpTeX project, see http://petr.olsak.net/optex \_codedecl \openref {File for references <2020-02-14>} % 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. \_cod -------------------------- \_newwrite\_reffile \_def\_inputref {% \_isfile{\_jobname.ref}\_iftrue \_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{}% } \_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 <\_optexversion> - REF file (#1)}% \_immediate\_wref \Xrefversion{{\_REFversion}}% } \def\openref{\_openref} \_doc ---------------------- We are using a convention that the macros used in `.ref` file are named `\_X`. 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{} \endtt We can check the version compatibility by this macro. Because OPmac does not understand `\_Xrefversion` we use `\Xrefversion` (different form OPmac) here. \_cod ---------------------- \_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 \_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{}`. This command sends to `.ref` file your immediately. Next lines in `.ref` file should include our macros. We must read when catcode of `#` is 12 because we needn't to duplicate each `#` in the `.ref` file. \_cod \_fin ----------------- \_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 ; \_endcode % ================================================ The REF file looks like: \begtt \Xrefversion{} \_Xpage{}{} \_Xtoc{}{}{}{} \_Xlabel{<label>}{<text>} \_Xlabel{<label>}{<text>} ... \_Xpage{<gpageno>}{<pageno>} \_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 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.