diff options
author | Karl Berry <karl@freefriends.org> | 2012-07-23 17:15:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-07-23 17:15:00 +0000 |
commit | 134349701bddf7cbbacf6030c6b9f9838aff96fa (patch) | |
tree | ec1140c46e1c0347a671a6fa3cf8af5a79e95f93 /Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx | |
parent | f7855c12c18bb97b7b9e49ab685ee558d8c0b47b (diff) |
l3kernel 3990 (17jul12)
git-svn-id: svn://tug.org/texlive/trunk@27108 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx b/Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx new file mode 100644 index 00000000000..5e2ba0a5e63 --- /dev/null +++ b/Master/texmf-dist/source/latex/l3kernel/l3docstrip.dtx @@ -0,0 +1,277 @@ +% \iffalse +% +%% File l3dosctrip.dtx Copyright (C) 2012 The LaTeX3 Project +%% +%% It may be distributed and/or modified under the conditions of the +%% LaTeX Project Public License (LPPL), either version 1.3c of this +%% license or (at your option) any later version. The latest version +%% of this license is in the file +%% +%% http://www.latex-project.org/lppl.txt +%% +%% This file is part of the "l3kernel bundle" (The Work in LPPL) +%% and all files in that bundle must be distributed together. +%% +%% The released version of this bundle is available from CTAN. +%% +%% ----------------------------------------------------------------------- +%% +%% The development version of the bundle can be found at +%% +%% http://www.latex-project.org/svnroot/experimental/trunk/ +%% +%% for those people who are interested. +%% +%%%%%%%%%%% +%% NOTE: %% +%%%%%%%%%%% +%% +%% Snapshots taken from the repository represent work in progress and may +%% not work or may contain conflicting material! We therefore ask +%% people _not_ to put them into distributions, archives, etc. without +%% prior consultation with the LaTeX Project Team. +%% +%% ----------------------------------------------------------------------- +%% +% +%<*driver|program> +\def\ExplFileDate{2012/06/08} +\def\ExplFileName{l3docstrip} +\def\ExplFileVersion{3787} +%</driver|program> +%<*driver> +% The same approach as used in \textsf{DocStrip}: if \cs{documentclass} +% is undefined then skip the driver, allowing the file to be used to extract +% \texttt{l3docstrip.tex} from \texttt{l3docstrip.dtx} directly. This works +% as the \cs{fi} is only seen if \LaTeX{} is not in use. The odd \cs{jobname} +% business allows the extraction to work with \LaTeX{} provided an appropriate +% \texttt{.ins} file is set up. +%<*gobble> +\ifx\jobname\relax\let\documentclass\undefined\fi +\ifx\documentclass\undefined +\else \csname fi\endcsname +%</gobble> + \def\filename{docstrip.dtx} + \documentclass[full]{l3doc} + \begin{document} + \DocInput{\jobname.dtx} + \end{document} +%<*gobble> +\fi +%</gobble> +%</driver> +% \fi +% +% \title{^^A +% The \pkg{l3docstrip} package\\ Code extraction and manipulation^^A +% \thanks{This file describes v\ExplFileVersion, +% last revised \ExplFileDate.}^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released \ExplFileDate} +% +% \maketitle +% +% \begin{documentation} +% +% \section{Extending \textsf{DocStrip}} +% +% The \pkg{l3docstrip} module adds \LaTeX3 extensions to the \textsf{DocStrip} +% program for extracting code from \texttt{.dtx}. As such, this documentation +% should be read along with that for \textsf{DocStrip}. +% +% \section{Internal functions and variables} +% +% An important consideration for \LaTeX3 development is separating out public +% and internal functions. Functions and variables which are private to one +% module should not be used or modified by any other module. As \TeX{} does +% not have any formal namespacing system, this requires a convention for +% indicating which functions in a code-level module are public and which are +% private. +% +% Using \pkg{l3docstrip} allows internal functions to be indicated using a +% \enquote{two part} system. Within the \texttt{.dtx} file, internal functions +% may be indicated using |@@| in place of the module name, for example +% \begin{verbatim} +% \cs_new_protected:Npn \@@_some_function:nn #1#2 +% { +% % Some code here +% } +% \tl_new:N \l_@@_internal_tl +% \end{verbatim} +% +% To extract the code using \pkg{l3docstrip}, the \enquote{guard} concept +% used by \textsf{DocStrip} is extended by introduction of the syntax +% \texttt{\%<@@=\meta{module}}. The \meta{module} name will be used when the +% code is extracted to replace the |@@|, so that +% \begin{verbatim} +% %<*package> +% %<@@=foo> +% \cs_new_protected:Npn \@@_some_function:nn #1#2 +% { +% % Some code here +% } +% \tl_new:N \l_@@_internal_tl +% %</package> +% \end{verbatim} +% will be extracted as +% \begin{verbatim} +% \cs_new_protected:Npn \__foo_some_function:nn #1#2 +% { +% % Some code here +% } +% \tl_new:N \l__foo_internal_tl +% \end{verbatim} +% where the |__| indicates that the functions and variables are internal +% to the \texttt{foo} module. +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3docstrip} implementation} +% +% \begin{macrocode} +%<*program> +% \end{macrocode} +% +% We start by loading the existing \textsf{DocStrip} code using the \TeX{} +% input convention. +% \begin{macrocode} +\input docstrip % +% \end{macrocode} +% +% \begin{macro}{\checkOption} +% The \cs{checkOption} macro is defined by \textsf{DocStrip} and is redefined +% here to accommodate the new \texttt{\%<@} syntax. +% +% When the macros that process a line have found that the line starts with +% \enquote{\texttt{\%<}}, a guard line has been encountered. The first +% character of a guard can be an asterisk (\texttt{*}), a slash (\texttt{/}), +% a plus (\texttt{+}), a minus (\texttt{-}), a less-than sign (\texttt{<}) +% starting verbatim mode, a commercial at (\texttt{@}) or any other character +% that can be found in an option name. This means that we have to peek at the +% next token and decide what kind of guard we have. We reinsert |#1| as it +% may be needed by \cs{doOption}. +% \begin{macrocode} +\def\checkOption<#1{% + \ifcase + \ifx*#10\else \ifx/#11\else + \ifx+#12\else \ifx-#13\else + \ifx<#14\else \ifx @#15\else 6\fi\fi\fi\fi\fi\fi\relax + \expandafter\starOption\or + \expandafter\slashOption\or + \expandafter\plusOption\or + \expandafter\minusOption\or + \expandafter\verbOption\or + \expandafter\moduleOption\or + \expandafter\doOption\fi + #1% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\moduleOption} +% In the case where the line starts |%<@|: the defined syntax requires that +% this continues to |%<@@=|. At the moment, we assume that the syntax will +% be correct and |#1| here is the module name for substitution into any +% internal functions in the extracted material. +% \begin{macrocode} +\def\moduleOption @@=#1>#2\endLine{% + \maybeMsg{<@@=#1>}% + \prepareActiveModule{#1}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\prepareActiveModule} +% \begin{macro}{\replaceModuleInLine} +% Here, we set up to do the search-and-replace when doing the extraction. +% The argument (|#1|) is the replacement text to use, or if empty an +% indicator that no replacement should be done. The search material is +% one of |__@@|, |_@@| or |@@|, done in order such that all three will end +% up the same in the output. The replacement function is initialised as a +% do-nothing for the case where |%<@@=| is never seen. +% \begin{macrocode} +\begingroup + \catcode`\_ = 12 % + \long\gdef\prepareActiveModule#1{% + \ifx\relax#1\relax + \let\replaceModuleInLine\empty + \else + \def\replaceModuleInLine{% + \replaceAllIn\inLine{__@@}{__#1}% + \replaceAllIn\inLine{_@@}{__#1}% + \replaceAllIn\inLine{@@}{__#1}% + }% + \fi + } +\endgroup +\let\replaceModuleInLine\empty +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\replaceAllIn} +% \begin{macro}{\replaceAllInAuxI} +% \begin{macro}{\replaceAllInAuxII} +% \begin{macro}{\replaceAllInAuxIII} +% The code here is a simple search-and-replace routine for a macro |#1|, +% replacing |#2| by |#3|. As set up here, there is an assumption that nothing +% is going to be expandable, which is reasonable as \pkg{l3docstrip} deals +% with \enquote{string} material. +% \begin{macrocode} +\long\def\replaceAllIn#1#2#3{% + \long\def\tempa##1##2#2{% + ##2\qMark\replaceAllInAuxIII#3##1% + }% + \edef#1{\expandafter\replaceAllInAuxI#1\qMark#2\qStop}% +} +\def\replaceAllInAuxI{% + \expandafter\replaceAllInAuxII\tempa\replaceAllInAuxI\empty +} +\long\def\replaceAllInAuxII#1\qMark#2{#1} +\long\def\replaceAllInAuxIII#1\qStop{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\normalLine} +% The \cs{normalLine} macro is present in \textsf{DocStrip} but is modified +% here to include the search-and-replace macro \cs{replaceModuleInLine}. The +% macro \cs{normalLine} writes its argument (which has to be delimited with +% |\endLine|) on all active output files, i.e.~those with off-counters equal +% to zero. The counter \cs{codeLinesPassed} is incremented by~$1$ for +% statistics (the guards for this used in \textsf{DocStrip} are retained). +% \begin{macrocode} +\def\normalLine#1\endLine{% +%<*stats> + \advance\codeLinesPassed\@ne +%</stats> + \maybeMsg{.}% + \def\inLine{#1}% + \replaceModuleInLine + \let\do\putline@do + \activefiles +} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</program> +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex
\ No newline at end of file |