diff options
author | Karl Berry <karl@freefriends.org> | 2021-06-03 20:53:13 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-06-03 20:53:13 +0000 |
commit | 18e1463358450e5d5fd2bcf5529954ed47d4a5f0 (patch) | |
tree | 76f3b3fadb39e52734f5129c35edfedf908bea02 /Master/texmf-dist/tex/optex/base/doc.opm | |
parent | 01945ee778f661b15c72ca982b7f19293042057b (diff) |
optex (3jun21)
git-svn-id: svn://tug.org/texlive/trunk@59458 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/tex/optex/base/doc.opm')
-rw-r--r-- | Master/texmf-dist/tex/optex/base/doc.opm | 150 |
1 files changed, 115 insertions, 35 deletions
diff --git a/Master/texmf-dist/tex/optex/base/doc.opm b/Master/texmf-dist/tex/optex/base/doc.opm index ce571a9e812..643a283e7ca 100644 --- a/Master/texmf-dist/tex/optex/base/doc.opm +++ b/Master/texmf-dist/tex/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 |