summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3doc.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-09-17 23:34:19 +0000
committerKarl Berry <karl@freefriends.org>2009-09-17 23:34:19 +0000
commit1684d0a29834ce566a114b73ca0d6a8cf38edc21 (patch)
treeb03c3db912ae6bb76fad634d7ba4a69ea098eb28 /Master/texmf-dist/source/latex/expl3/l3doc.dtx
parenta95d1a90845bf6c1c7f2ee629fbe10a20d5863ce (diff)
expl3 1543 (17sep09)
git-svn-id: svn://tug.org/texlive/trunk@15347 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3doc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3doc.dtx60
1 files changed, 34 insertions, 26 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3doc.dtx b/Master/texmf-dist/source/latex/expl3/l3doc.dtx
index e3802a53c91..197a6703a98 100644
--- a/Master/texmf-dist/source/latex/expl3/l3doc.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3doc.dtx
@@ -77,7 +77,7 @@ Do not distribute a modified version of this file.
% \end{macrocode}
%
%<*driver|class>
-\GetIdInfo$Id: l3doc.dtx 1451 2009-08-08 06:33:34Z joseph $
+\GetIdInfo$Id: l3doc.dtx 1538 2009-09-17 05:14:09Z will $
{L3 Experimental documentation class}
%</driver|class>
%
@@ -179,7 +179,7 @@ Do not distribute a modified version of this file.
%
% \section{Problems \& Todo}
%
-% Problems at the moment: (1)~not flexible in the types of things that can be documented; (2)~very nonstandard markup (using `"|"' as a delimiter and the odd `"/ (...)"' tags; (3)~no obvious link to the "\begin{macro}" function that's used analogously in the implementation.
+% Problems at the moment: (1)~not flexible in the types of things that can be documented; (2)~very nonstandard markup (using `"|"' as a delimiter and the odd `"/ (...)"' tags; (3)~no obvious link between the "\begin{function}" environment for documenting things to the "\begin{macro}" function that's used analogously in the implementation.
%
% The environments "function" and "macro" should probably
% be renamed to something like \env{funcdoc} and \env{funcimpl},
@@ -201,8 +201,9 @@ Do not distribute a modified version of this file.
% \item Something better to replace "\StopEventually"; I'm thinking two
% environments \env{documentation} and \env{implementation} that can
% conditionally typeset/ignore their material.
-% \item Hyperlink documentation and implementation of macros (also see
-% the \textsc{dtx} file of \pkg{svn-multi} v2).
+% (This has been implemented but needs further consideration.)
+% \item Hyperlink documentation and implementation of macros (see
+% the \textsc{dtx} file of \pkg{svn-multi} v2 as an example).
% \end{itemize}
%
% \section{Bugs}
@@ -284,7 +285,7 @@ Do not distribute a modified version of this file.
% \DescribeEnv{macro}
% The well-used environment from \LaTeXe\ for marking up the implementation
% of macros/functions remains the \env{macro} environment.
-% One major change in \pkg{l3doc}: it now accepts comma-separated lists
+% One change in \pkg{l3doc}: it now accepts comma-separated lists
% of functions, to avoid a very large number of consecutive "\end{macro}"
% statements.
% \begin{verbatim}
@@ -297,8 +298,8 @@ Do not distribute a modified version of this file.
%
% \DescribeEnv{arguments}
% Within a \env{macro} environment, you may use the \env{arguments} environment
-% to describe the arguments taken by the function(s). It behaves exactly
-% like a list environment.
+% to describe the arguments taken by the function(s). It behaves
+% like a modified enumerate environment.
% \begin{verbatim}
% % \begin{macro}{\foo:nn,\foo:VV}
% % \begin{arguments}
@@ -562,6 +563,8 @@ Do not distribute a modified version of this file.
% \end{environment}
%
% \begin{macro}{\tn}
+% As \cs{cs}. Use this to mark up all \TeX\ and \LaTeXe\ commands; they
+% then end up together in the index. TODO: hyperlinks in the index entries.
% \begin{macrocode}
\newcommand\tn[1]{
\texttt{\bslash #1}
@@ -727,18 +730,18 @@ Do not distribute a modified version of this file.
% \end{macro}
%
% \begin{macro}{\doc_showmacro_aux_ii:w}
-% This macro is passed one of:
+% This macro is passed arguments in the following ways:
% \begin{quote}
-% "\showexplmacro "^^A
+% "\doc_showmacro_aux_ii:w "^^A
% \makebox[\widthof{\texttt{123456}}]{\meta{name}}^^A
% " ::\q_stop" \\
-% "\showexplmacro \foo ::\q_stop" \\
-% "\showexplmacro \foo: ::\q_stop" \\
-% "\showexplmacro \foo:Z ::\q_stop" \\
+% "\doc_showmacro_aux_ii:w \foo ::\q_stop" \\
+% "\doc_showmacro_aux_ii:w \foo: ::\q_stop" \\
+% "\doc_showmacro_aux_ii:w \foo:Z ::\q_stop" \\
% \end{quote}
% Notice that for "\foo", "#2" and "#3" are empty,\\
-% for "\foo:", "#2" is empty,\\
-% and for both "\foo:" and "\foo:Z", "#3" is `":"' .
+% for "\foo:", "#2" is empty, and "#3" is `":"'\\
+% for "\foo:Z", "#2" is `"Z"' and "#3" is `":"' .
% \begin{arguments}
% \item Function name \item Possible arg.\ spec. \item Possible colon
% \end{arguments}
@@ -768,12 +771,14 @@ Do not distribute a modified version of this file.
% \begin{environment}{syntax}
% Syntax block placed next to the list of functions to illustrate their use.
% \begin{macrocode}
-\newenvironment{syntax}{%
- \minipage[b]{.7\textwidth}%
+\dim_new:N \g_doc_syntax_dim
+\dim_set:Nn \g_doc_syntax_dim {0.7\textwidth}
+\newenvironment{syntax}{
+ \minipage[b]{\g_doc_syntax_dim}
\cs_set_nopar:Npn \meta@font@select{\rmfamily\itshape} % (Will: I HATE italic cmtt!)
\small\ttfamily\raggedright
\obeyspaces\obeylines
-}{%
+}{
\endminipage
\hfil\break
\global\@ignoretrue
@@ -1052,11 +1057,11 @@ Do not distribute a modified version of this file.
%
% \begin{macrocode}
\newenvironment{TemplateInterfaceDescription}[1]
- {\subsection{The template type `#1'}%
+ {\subsection{The~template~type~`#1'}%
\begingroup
\@beginparpenalty\@M
\description
- \def\TemplateArgument##1##2{\item[Arg: ##1]##2\par}%
+ \def\TemplateArgument##1##2{\item[Arg:~##1]##2\par}%
\def\TemplateSemantics{\enddescription\endgroup
\subsubsection*{Semantics:}}%
}
@@ -1065,12 +1070,12 @@ Do not distribute a modified version of this file.
%
% \begin{macrocode}
\newenvironment{TemplateDescription}[2]
- {\subsection{The template `#2' (type #1)}%
+ {\subsection{The~template~`#2'~(type~#1)}%
\subsubsection*{Attributes:}%
\begingroup
\@beginparpenalty\@M
\description
- \def\TemplateKey##1##2##3##4{\item[##1 (##2)]##3%
+ \def\TemplateKey##1##2##3##4{\item[##1~(##2)]##3%
\ifx\TemplateKey##4\TemplateKey\else
% \hskip0ptplus3em\penalty-500\hskip 0pt plus 1filll Default:~##4%
\hfill\penalty500\hbox{}\hfill Default:~##4%
@@ -1078,21 +1083,21 @@ Do not distribute a modified version of this file.
\fi
\par}%
\def\TemplateSemantics{\enddescription\endgroup
- \subsubsection*{Semantics \& Comments:}}%
+ \subsubsection*{Semantics~\&~Comments:}}%
}
{\par\bigskip}
% \end{macrocode}
%
% \begin{macrocode}
\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx]
- {\subsubsection{The instance `#3' (template #2/#4)}%
- \subsubsection*{Attribute values:}%
+ {\subsubsection{The~instance~`#3'~(template~#2/#4)}%
+ \subsubsection*{Attribute~values:}%
\begingroup
\@beginparpenalty\@M
\def\InstanceKey##1##2{\>\textbf{##1}\>##2\\}%
\def\InstanceSemantics{\endtabbing\endgroup
\vskip-30pt\vskip0pt
- \subsubsection*{Layout description \& Comments:}}%
+ \subsubsection*{Layout~description~\&~Comments:}}%
\tabbing
xxxx\=#1\=\kill
}
@@ -1340,6 +1345,8 @@ Do not distribute a modified version of this file.
% Fix index (for now):
% \begin{macrocode}
\g@addto@macro\theindex{\MakePrivateLetters}
+\cs_set:Npn \verbatimchar {&}
+\cs_set:Npx \levelchar {\string#}
% \end{macrocode}
%
% \begin{macrocode}
@@ -1363,6 +1370,7 @@ Do not distribute a modified version of this file.
% \begin{macro}{\doc_special_main_index:n,\doc_special_main_index:o,\hdpgindex}
% Heiko's replacement to play nicely with |hypdoc|:
% \begin{macrocode}
+
\cs_set_nopar:Npn \doc_special_main_index:n #1 {
\index{
\@gobble#1
@@ -1526,7 +1534,7 @@ Do not distribute a modified version of this file.
%<*docist>
actual '='
quote '!'
-level '>'
+level '#'
preamble
"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
postamble