CTAN sync 202106040302

1 files changed, 115 insertions, 35 deletions

diff --git a/macros/optex/base/doc.opm b/macros/optex/base/doc.opm
index ce571a9e81..643a283e7c 100644
--- a/macros/optex/base/doc.opm
+++ b/macros/optex/base/doc.opm
@@ -1,6 +1,6 @@
 %% This is part of the OpTeX project, see http://petr.olsak.net/optex
 
-\_codedecl \printdoc {Macros for documentation printing <2020-04-28>}
+\_codedecl \printdoc {Macros for documentation printing <2021-05-15>} % loaded on demand by \load[doc]
 
    \_doc -----------------------------
    General decalarations.
@@ -34,6 +34,8 @@
    \_doc -----------------------------
    The listing mode is implemented here. The \`\maxlines`
    is maximal lines of code printed in the listing mode.
+   The \`\_catcodedot` sets dot as letter in listngs (for package
+   documentation where `\.foo` sequeces exist).
    \_cod -----------------------------
 
 \_newcount \_maxlines   \_maxlines=100000
@@ -45,9 +47,10 @@
    \_typosize[8/10]
    \_let\_printverbline=\_printcodeline
    \_ttline=\_inputlineno
-   \_setverb
+   \_setverb \_catcodedot
    \_ifnum\_ttline<0 \_let\_printverblinenum=\_relax \_else \_initverblinenum \_fi
    \_adef{ }{\ }\_adef\^^I{\t}\_parindent=\_ttindent \_parskip=0pt
+   \_def\t{\_hskip \_dimexpr\_tabspaces em/2\_relax}%
    \_relax \_ttfont
    \_endlinechar=`^^J
    \_def\_tmpb{\_start}%
@@ -57,27 +60,38 @@
    \_def\_tmpa{\_empty#1}%
    \_let\_next=\_readverbline
    \_ea\_isinlist\_ea\_tmpa\_ea{\_Doc}\_iftrue \_let\_next=\_processinput \_fi
-   \_ea\_isinlist\_ea\_tmpa\_ea{\_Endcode}\_iftrue \_endinput \_let\_next=\_processinput \_fi
+   \_ea\_isinlist\_ea\_tmpa\_ea{\_Doctab}\_iftrue \_let\_next=\_processinput \_fi
+   \_ea\_isinlist\_ea\_tmpa\_ea{\_Endcode}\_iftrue \_def\_next{\_processinput\_endinput}\_fi
    \_ifx\_next\_readverbline \_addto\_tmpb{#1^^J}\_fi
    \_next
 }
 {\_catcode`\ =13 \_gdef\_aspace{ }}\_def\_asp{\_ea\_noexpand\_aspace}
 \_edef\_Doc{\_asp\_asp\_bslash _doc}
+\_bgroup \_lccode`~=`\^^I \_lowercase{\_egroup\_edef\_Doctab{\_noexpand~\_bslash _doc}}
 \_edef\_Endcode{\_noexpand\_empty\_bslash _endcode}
+\_def\_catcodedot{\_catcode`\.=11 }
 
    \_doc -----------------------------
-   The scanner of the control sequences in the listing mode.
+   The scanner of the control sequences in the listing mode replaces all
+   occurrences of `\` by \`\_makecs`. This macro reads next tokens and
+   accumulates them to `\_tmpa` as long as they have category 11. It
+   means that `\_tmpa` includes the name of the following control sequence
+   when \fw\`\_makecsF` is run. The printing form of the control
+   sequence is set to `\_tmpb` and the test of existence `\,<csname>`is
+   performed. If it is true then active hyperlink is created. If not, then
+   the first `_` or `.` is removed from `\_tmpa` and the test is repeated.
    \_cod -----------------------------
 
-\_def\_makecs{\_def\_tmp{}\_futurelet\_next\_makecsA}
+\_def\_makecs{\_def\_tmpa{}\_futurelet\_next\_makecsA}
 \_def\_makecsA{\_ifcat a\_noexpand\_next \_ea\_makecsB \_else \_ea\_makecsF \_fi}
-\_def\_makecsB#1{\_addto\_tmp{#1}\_futurelet\_next\_makecsA}
-\_def\_makecsF{\_ifx\_tmp\_empty \_csstring\\%
-       \_else \_ifcsname ,\_tmp\_endcsname \_link[cs:\_tmp]{\Blue}{\_csstring\\\_tmp}%
-       \_else \_let\_next=\_tmp \_remfirstunderscore\_next
-              \_ifx\_next\_empty \_let\_next=\_tmp \_fi
-              \_ifcsname ,\_next\_endcsname \_link[cs:\_next]{\Blue}{\_csstring\\\_tmp}%
-       \_else \_csstring\\\_tmp \_fi\_fi\_fi
+\_def\_makecsB#1{\_addto\_tmpa{#1}\_futurelet\_next\_makecsA}
+\_def\_makecsF{\_let\_tmpb=\_tmpa
+       \_ifx\_tmpa\_empty \_csstring\\%
+       \_else \_ifcsname ,\_tmpa\_endcsname \_trycs{el:\_tmpa}{\_intlink}%
+       \_else \_remfirstunderscoreordot\_tmpa
+              \_ifx\_tmpa\_empty \_let\_tmpa=\_tmpb \_fi
+              \_ifcsname ,\_tmpa\_endcsname \_trycs{el:\_tmpa}{\_intlink}%
+       \_else \_csstring\\\_tmpb \_fi\_fi\_fi
 }
 \_def\_processinput{%
    \_let\_start=\_relax
@@ -96,8 +110,18 @@
    \_endgroup \_ttskip
    \_isnextchar\_par{}{\_noindent}%
 }
-\_def\_remfirstunderscore#1{\_ea\_remfirstunderscoreA#1\_relax#1}
-\_def\_remfirstunderscoreA#1#2\_relax#3{\_if _#1\_def#3{#2}\_fi}
+\_def\_remfirstunderscoreordot#1{\_ea\_remfirstuordotA#1\_relax#1}
+\_def\_remfirstuordotA#1#2\_relax#3{\_if _#1\_def#3{#2}\_fi \_if\_string#1.\_def#3{#2}\_fi}
+
+   \_doc -----------------------------
+   By default the internal link is created by \`\_intlink` inside listing
+   mode. But you can define `\el:<csname>` which has precedence and it can
+   create an external link. The `\_tmpa` includes the name used in the link
+   and `\_tmpb` is the name to be printed. See \^`\_makecsF` above and the
+   example at the beginning of this section.
+   \_cod -----------------------------
+
+\_def\_intlink{\_link[cs:\_tmpa]{\Blue}{\_csstring\\\_tmpb}}
 
    \_doc -----------------------------
    The lines in the listing mode have a yellow background.
@@ -167,6 +191,16 @@
    \_bf\_llaptoclink{#1}{#2}\_hfill \_pgn{#3}\_tocpar\_medskip}
 
    \_doc -----------------------------
+   If this macro is loaded by \^`\load` then we need to initialize
+   catcodes using the `\_afteroad` macro.
+   \_cod -----------------------------
+
+\_def\_afterload{\_catcode`\<=13 \_catcode`\`=13 \_catcode`\.=11
+   \_wlog {doc.opm: catcodes of < and ` activated, catcode of . is letter.}%
+}
+\_catcode`.=11
+
+   \_doc -----------------------------
    The \code{<something>} will be print as <something>.
    \_cod -----------------------------
 
@@ -177,20 +211,11 @@
 \_everyintt{\_catcode`\<=13 }
 
    \_doc -----------------------------
-   If this macro is loaded by \^`\load` then we need to initialize
-   catcodes using the `\_afteroad` macro.
-   \_cod -----------------------------
-
-\_def\_afterload{\_catcode`\<=13 \_catcode`\`=13 }
-
-   \_doc -----------------------------
    Main documentation points and hyperlinks to/from it.
    Main documentation point: \code{\\`\\foo`}.
-   User-level documentation point: \code{\\^`\\foo}, first occurence only.
+   User documentation point: \code{\\^`\\foo}, first occurence only.
    The next occurrences are only links to the main documentation point.
-   Link to user-level documentation point: \code{\\~`\\foo}.
-   If user-level documentation point follows the main documentation point
-   then use \code{\\_forwardlink\\`\\foo`}.
+   Link to user documentation point: \code{\\~`\\foo}.
    \_cod -----------------------------
 
 \_verbchar`
@@ -202,8 +227,6 @@
             \_link[cs:^\_tmp]{\Red}{\_tt\_csstring\\\_tmp}\_else
             {\_tt\Red\_csstring\\\_tmp}\_fi}%
 }
-\_def\_forwardlink\`#1`{{\_slet{cs:^\_csstring#1}{relax}\`#1`}}
-
 \_def\^`#1{\_leavevmode\_edef\_tmp{\_csstring#1}\_iindex{\_tmp}%
    \_hbox{\_ifcsname cs:^\_tmp\_endcsname \_else \_dest[cs:^\_tmp]\_sxdef{cs:^\_tmp}{}\_fi
          \_link[cs:\_tmp]{\Blue}{\_tt\_string#1}}%
@@ -216,6 +239,14 @@
    \_futurelet\_next\_cslinkA
 }
 
+   \_doc -----------------------------
+   The \`\fw` macro for forward links to user documentation point (given later)
+   is defined here.
+   \_cod -----------------------------
+
+\_def\_fw\`#1`{{\_slet{cs:^\_csstring#1}{}\`#1`}}
+\_public \fw ;
+
 \_endcode %-------------------------------------------
 
 \noindent
@@ -225,12 +256,13 @@ commands are defined after the file `doc.opm` is load by \^`\load`~`[doc]`.
 The `\printcoc` starts reading of given `<filename>` from the second line.
 The file is read in {\em the listing mode}.
 The `\prindoctail` starts reading given `<filename>` from the
-first occurrence of the `\_encode`. The file is read
+first occurrence of the `\_endcode`. The file is read
 in normal mode (like `\input <filename>`).
 
 The {\em listing mode} prints the lines as a listing of a code. This mode is
 finished when first {\visiblesp`  \_doc`} occurs or first `\_endcode`
-occurs. At least two spaces must precede before such `\_doc`. On the other
+occurs. At least two spaces or one tab
+character must precede before such `\_doc`. On the other
 hand, the `\_encode` must be at the left edge of the line without spaces.
 If this rule is not met then the listing mode continues.
 
@@ -255,10 +287,6 @@ applied, the reading of the file opened by `\printdoc` is finished.
 You cannot reach the end of the file (without `\_endcode`) in the listing
 mode.
 
-The listing mode creates all control sequences which are listed in the
-index as an active link to the main documentation point of such control sequence
-and prints them in blue. Another text is printed in black.
-
 The main documentation point is denoted by \code{\\`\\}`<sequence>`\code{`}
 in red, for example \code{\\`\\foo`}.
 The user documentation point is the first occurrence of
@@ -266,11 +294,63 @@ The user documentation point is the first occurrence of
 There can be more such markups, all of them are hyperlinks to the main
 documentation point.
 And main documentation point is a hyperlink to the user documentation point
-if this point exists. Finally, the
+if this point precedes. Finally, the
 \code{\\~`\\}`<sequence>`\code{`} (for example \code{\\~`\\foo`}) are
 hyperlinks to the user documentation point.
 
+By default, the hyperink from main documentation point to the user
+documentation point is active only if it is backward link, i.e.\
+the main documentation point is given later. The reason is that we don't
+know if such user documentation point will exist when creating
+main documentation point and we don't want
+broken links. If you are sure that user documentation point will
+follow then use prefix \^`\fw` before~\code{\\`}, for example
+\code{\\fw\\`\\foo`} is main documentation point where the user
+documentation point is given later and forward hyperlink is created here.
+
+Control sequences and their page positions of main documentation points and user
+documentation points are saved to the index.
+
+The listing mode creates all control sequences which are listed in the
+index as an active link to the main documentation point of such control sequence
+and prints them in blue. Moreower, active links are control sequneces of the
+type `\_foo` or `\.foo` although the documentation mentions only `\foo`.
+Another text is printed in black.
+
+The listing mode is able to generate external links to another \OpTeX/-like
+documentation, if the macros `\,<csname>` and `\el:<csname>` are defined.
+The second macro should create a hyperlink using `\_tmpa`
+where the link name of the <csname> is saved and `\_tmpb` where the name of
+the <csname> to be printed is saved (`\tmpb` can include preceding `_` or
+`.` unlike `\_tmpa`). For example, suppose, that we have created
+`optex-doc.eref` file by:
+\begtt
+TEXINPUTS='.;$TEXMF/{doc,tex}//' optex optex-doc
+grep Xindex optex-doc.ref > optex-doc.eref
+\endtt
+The `.eref` file includes only `\_Xindex{<csname>}{}` lines from
+`optex-doc.ref` file. Then we can use following macros:
+\begtt
+\def\_Xindex#1#2{\sdef{,#1}{}\slet{el:#1}{optexdoclink}}
+\def\optexdoclink{%
+   \edef\extlink{url:\optexdocurl\csstring\#cs:\_tmpa}%
+   \_ea\_urlactive\_ea[\extlink]{\Cyan}{\csstring\\\_tmpb}}
+\def\optexdocurl{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf}
+\isfile{optex-doc.eref}\iftrue \input{optex-doc.eref}\fi
+\endtt
+All `\el:<csname>`, where <csname> is from `optex-doc.ref`,
+have the same meaning: `\optexdoclink` in this example. And
+`\optexdoclink` creates the external link in `\Cyan` color.
+
+\secc Implementation
+
 \endinput
 
+2021-05-15 \_endinput shifted after \_processinput when \_endcode is scanned.
+2021-05-14 \_catcodedot, \_Doctab introduced.
+2021-05-13 \def\t added, bug fixed.
+2021-05-03 External links fom listing mode allowed.
+2021-05-02 \_forwadlink replaced by \_fw, to be more consistent.
+2021-05-02 \fw introduced, \.foo -> \foo allowed.
 2020-04-28 \levevmode in \^ macros added (bug fixed)
-2020-04-22 released
\ No newline at end of file
+2020-04-22 released