summaryrefslogtreecommitdiff
path: root/macros/optex/base/doc.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/optex/base/doc.opm')
-rw-r--r--macros/optex/base/doc.opm150
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