[latex3-commits] [l3svn] r6689 - Add command to print help about star and TF notations

[noreply at latex-project.org]

Author: bruno
Date: 2016-08-19 22:29:02 +0200 (Fri, 19 Aug 2016)
New Revision: 6689

Modified:
   trunk/l3experimental/l3sort/l3sort.dtx
   trunk/l3kernel/l3doc.dtx
   trunk/l3kernel/source3body.tex
Log:
Add command to print help about star and TF notations

In l3doc, expandable functions are marked with a star, restricted
expandable with a hollow star and TF conditionals also have a
special notation.  When typesetting source3, every star and TF were
links to the explanation, but for other packages these links failed.
Now third-party packages can use \CodedocExplain, or the more specific
\CodedocExplainEXP, REXP, or TF, to have the explanation.  As an
example I've put that in l3sort in a footnote.


Modified: trunk/l3experimental/l3sort/l3sort.dtx
===================================================================
--- trunk/l3experimental/l3sort/l3sort.dtx	2016-08-19 19:21:48 UTC (rev 6688)
+++ trunk/l3experimental/l3sort/l3sort.dtx	2016-08-19 20:29:02 UTC (rev 6689)
@@ -147,6 +147,8 @@
 %   \meta{clist var}.
 % \end{function}
 %
+% {\renewcommand{\thefootnote}{}\footnotetext{\CodedocExplainEXP}}
+%
 % \begin{function}[EXP]{\tl_sort:nN}
 %   \begin{syntax}
 %     \cs{tl_sort:nN} \Arg{token list} \meta{conditional}

Modified: trunk/l3kernel/l3doc.dtx
===================================================================
--- trunk/l3kernel/l3doc.dtx	2016-08-19 19:21:48 UTC (rev 6688)
+++ trunk/l3kernel/l3doc.dtx	2016-08-19 20:29:02 UTC (rev 6689)
@@ -1555,7 +1555,7 @@
   { \@@_meta:n {#1} }
 %    \end{macrocode}
 % \end{macro}
-
+%
 % \begin{macro}[aux]
 %   {
 %     \@@_pdfstring_cmd:w,
@@ -1727,6 +1727,39 @@
 %    \end{macrocode}
 % \end{environment}
 %
+% \begin{macro}{\CodedocExplain, \CodedocExplainEXP, \CodedocExplainREXP, \CodedocExplainTF}
+%   Explanation of stars and |TF| notations, for use in third-party
+%   packages.
+%    \begin{macrocode}
+\NewDocumentCommand { \CodedocExplain } { }
+  { \CodedocExplainEXP \ \CodedocExplainREXP \ \CodedocExplainTF }
+\NewDocumentCommand { \CodedocExplainEXP } { }
+  {
+    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{expstar}{}}%
+    \@@_typeset_exp:\ indicates~fully~expandable~functions,~which~
+    can~be~used~within~an~\texttt{x}-type~argument~(in~plain~
+    \TeX{}~terms,~inside~an~\cs{edef}),~as~well~as~within~an~
+    \texttt{f}-type~argument.
+  }
+\NewDocumentCommand { \CodedocExplainREXP } { }
+  {
+    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{rexpstar}{}}%
+    \@@_typeset_rexp:\ indicates~
+    restricted~expandable~functions,~which~can~be~used~within~an~
+    \texttt{x}-type~argument~but~cannot~be~fully~expanded~within~an~
+    \texttt{f}-type~argument.
+  }
+\NewDocumentCommand { \CodedocExplainTF } { }
+  {
+    \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{explTF}{}}%
+    \@@_typeset_TF:\ indicates~conditional~(\texttt{if})~functions~
+    whose~variants~with~\texttt{T},~\texttt{F}~and~\texttt{TF}~
+    argument~specifiers~expect~different~
+    \enquote{true}/\enquote{false}~branches.
+  }
+%    \end{macrocode}
+% \end{macro}
+%
 % \subsection{Implementing text markup}
 %
 % Keys for \cs{cmd}, \cs{cs} and \cs{tn}.
@@ -1849,10 +1882,18 @@
 %
 % \subsubsection{Common between \env{macro} and \env{function}}
 %
-% \begin{macro}{\@@_typeset_TF:, \@@_typeset_aux:n}
+% \begin{macro}
+%   {
+%     \@@_typeset_exp:, \@@_typeset_rexp:,
+%     \@@_typeset_TF:, \@@_typeset_aux:n
+%   }
 %   Used by \cs{@@_macro_single:nNN} and in the \env{function} environment
 %   to typeset conditionals and auxiliary functions.
 %    \begin{macrocode}
+\cs_new_protected:Npn \@@_typeset_exp:
+  { \hyperlink{expstar} {$\star$} }
+\cs_new_protected:Npn \@@_typeset_rexp:
+  { \hyperlink{rexpstar} {\ding{73}} } % hollow star
 \cs_new_protected:Npn \@@_typeset_TF:
   {
     \hyperlink{explTF}
@@ -2321,7 +2362,7 @@
     \small\ttfamily
     \HD at target
     \Hy at MakeCurrentHref { HD. \int_use:N \c at HD@hypercount }
-    \begin{tabular} [t] { @{} l @{} r @{} }
+    \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} }
       \toprule
       \@@_function_extra_labels:
       \@@_names_typeset:
@@ -2364,16 +2405,8 @@
 \cs_new_protected:Npn \@@_typeset_expandability:
   {
     &
-    \bool_if:NT \l_@@_macro_EXP_bool
-      {
-        \hspace{\tabcolsep}
-        \hyperlink{expstar} {$\star$}
-      }
-    \bool_if:NT \l_@@_macro_rEXP_bool
-      {
-        \hspace{\tabcolsep}
-        \hyperlink{rexpstar} {\ding{73}} % hollow star
-      }
+    \bool_if:NT \l_@@_macro_EXP_bool  { \@@_typeset_exp: }
+    \bool_if:NT \l_@@_macro_rEXP_bool { \@@_typeset_rexp: }
   }
 %    \end{macrocode}
 %

Modified: trunk/l3kernel/source3body.tex
===================================================================
--- trunk/l3kernel/source3body.tex	2016-08-19 19:21:48 UTC (rev 6688)
+++ trunk/l3kernel/source3body.tex	2016-08-19 20:29:02 UTC (rev 6689)
@@ -309,7 +309,7 @@
 
 \paragraph{Fully expandable functions}
 \hypertarget{expstar}{Some functions are fully expandable},
-which allows it to be used within
+which allows them to be used within
 an \texttt{x}-type argument (in plain \TeX{} terms, inside an \cs{edef}),
 as well as within an \texttt{f}-type argument.
 These fully expandable functions are indicated in the documentation by