summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/morehype/use/blogexec.sty
blob: 0767561cc874340ae57362db99909814b61b508f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
\NeedsTeXFormat{LaTeX2e}[1994/12/01] %% \newcommand* etc. 
\ProvidesPackage{blogexec}[2012/12/20 v0.21
                           assignments with blog.sty (UL)] 
%% copyright (C) 2011 Uwe Lueck, 
%% http://www.contact-ednotes.sty.de.vu 
%% -- author-maintained in the sense of LPPL below.
%%
%% This file can be redistributed and/or modified under 
%% the terms of the LaTeX Project Public License; either 
%% version 1.3c of the License, or any later version.
%% The latest version of this license is in
%%     http://www.latex-project.org/lppl.txt
%% We did our best to help you, but there is NO WARRANTY. 
%%
%% Please report bugs, problems, and suggestions via 
%% 
%%   http://www.contact-ednotes.sty.de.vu 
%%
%% == Requirements == 
%% The \ctanpkgref{dowith} package is needed for managing 
%% and running lists of macros to be intercepted:
\RequirePackage{dowith}
%% Admittedly, `\do' and `\@elt' lists (as discussed in `dowith.pdf') 
%% would be faster than the 'dowith' method, which might be relevant 
%% here (TODO: how much?). I may abandon 'dowith' later, I just cannot 
%% afford removing it now (2011/11/05, TODO).
%% 
%% == Processing Source Files ==
%% With |\BlogInterceptExtra|, 'blog.sty'
%% deals with \emph{empty} input lines just like 
%% \[`\BlogCopyFile[<changes>]{<src-file>}'\] 
%% does; \emph{otherwise} the content of `\fdInputLine' is copied to 
%% |\fdOutputCode|. Before the latter is writen to the output file 
%% <output> (as determined by a recent `\ResultFile{<output>}'), 
%% |\BlogInterceptions| is run, its purpose is to extract assignment and other 
%% ``execution" commands and to turn `\fdOutputCode' into an 
%% expandable macro. We use `\def' because 'blog.sty' may have 
%% provided a preliminary definition earlier:
\def\blog@icl@xtra{%
    \let\BlogProcessLine\BlogAllowIntercepting
    \let\BlogInterceptions\AllBlogInterceptions}
\def\BlogInterceptExtra{\@ifstar@intercept@hash\blog@icl@xtra}
\def\@ifstar@intercept@hash#1{\@ifstar{#1\BlogInterceptHash}#1}
%% And this is the default setting (TODO!?):
\BlogInterceptExtra
%% Below, there are commands for restricted (faster---TODO: relevant? 
%% or less complex, to reduce danger) 
%% interception functionality. (Maybe the file should be restructured.) 
%% |\AllBlogInterceptions| first is nothing:
\InitializeListMacro\AllBlogInterceptions
%% ---and should become more below.
%% 
%% |\BlogAllowIntercepting| stores the difference to 'blog.sty': 
\newcommand*{\BlogAllowIntercepting}{%
    \let\fdOutputCode\fdInputLine
    \BlogInterceptions
%% When, after removing the intercepted command, the line is 
%% empty, it is \emph{not} written into output:
    \ifx\fdOutputCode\@empty \else 
        \WriteResult{%
            \ProcessExpandedWith\fdOutputCode\BlogOutputJob}%
%% ... enabling ``ligatures" with 'blog.sty' v0.7.  %% 2011/11/21
    \fi}
%% ... TODO: in 'fifinddo' with something like `\fdInterceptions'?
%%
%% Especially for storing file-specific macro definitions 
%% with `\EXECUTE' (below), a parameter character 
%% (usually hash mark) is needed. 
%% %% mod. 2011/11/20:
%% 'fifinddo.sty' (so far---2011/11/20) 
%% does not include it with `\BasicNormalCatCodes', 
%% and 'blog.sty' 
%% does not include it with `\BlogCodes'
%% ---the following |\BlogInterceptHash| does.
%% Moreover, |\MakeHashParameter| enables such definitions
%% when placed in a source file within the argument of a 
%% separate(!) `\EXECUTE'.
\providecommand*{\MakeHashParameter}{\catcode`\#6 }
\def\BlogInterceptHash{% 
    \ToListMacroAdd\BlogCodes\MakeHashParameter
    \MakeHashParameter}
%% TODO: default? 0-arg interception?
%%
%% == Intercepting Single-Parameter Commands ==
%% === The General Method              ===
%% Macros to be intercepted that have a single argument will be 
%% collected in |\blogOneArgInterceptions|: 
\InitializeListMacro\blogOneArgInterceptions
\ToListMacroAdd\AllBlogInterceptions{%
    \DoWithAllIn\blogTryOneArgCmd
                \blogOneArgInterceptions}
%% Here |\blogTryOneArgCmd{<cmd>}| creates a ``sandbox" for parsing 
%% in a similar way as 'fifinddo' does it, searching for <cmd>. 
%% The method there was made thinking of reading files with 
%% ``plain text" category codes, not aware of 'blog.sty'. 
%% Maybe this was a mistake, and I will reconsider it. 
%% There I also introduce a separate sandbox macro 
%% for each search pattern, thinking of different types of sandboxes. 
%% This is not done/needed here (strangely, TODO).---The sandbox 
%% starts with the parsing macro. The latter's name derives from 
%% <cmd> by prefixing something to its name.
%% |\StripEsc| is a little helper for removing the backslash 
%% from a macro name. 
\providecommand*{\StripEsc}{\expandafter\@gobble\string}
%% Name spaces:                                         %% 2012/08/29
\newcommand*{\blog@x}{\StripEsc\blogx}
\newcommand*{\blogTryOneArgCmd}[1]{%
    \csname \blog@x:\StripEsc#1\expandafter\endcsname
        \fdOutputCode \@gobble#1\@empty\@nil}
%% Here, `\@empty' is the dummy argument for <cmd>---this is what 
%% must be modified for <cmd> with more than one parameter.
%% At present (2011/11/05), that tail starting with `\@gobble' 
%% may stay at the end of `\fdOutputCode' for each interception per 
%% `\fdInputLine', until it expands to nothing in the `\write'.
%%
%% |\MakeBlogOneArgInterception{<cmd>}{<run>}{<write>}| \ \
%% says that when <cmd> is found in `\fdOutputCode', 
%% <run> should be executed, and `<cmd><arg>' should be replaced 
%% by <write> in `\fdOutputCode' where <arg> is the argument for 
%% <cmd> found in `\fdOutputCode'. Let <arc> be <arg> without 
%% delimiting braces if `<arg>' is `{<arc>}' 
%% (otherwise `<arc>' is the same as `<arg>'). 
%% Then use `#2' for referring to <arc> inside <run> and <write>. 
%% (Sorry, I cannot afford replacing `#2' by a more natural 
%%  placeholder right now.)
\begingroup 
  \catcode`\|\z@ |MakeOther|\%                  %% \z@ 2011/11/22
  |@ifdefinable|MakeBlogOneArgInterception{%
    |gdef|MakeBlogOneArgInterception#1#2#3{%
%% First we add <cmd> to `\blogOneArgInterceptions', 
%% unless it is already there:                      %% 2011/11/07
      |TestListMacroForToken|blogOneArgInterceptions#1%
      |ifin@ 
        |PackageWarning{blogexec}{Redeclaring |string#1.}%
      |else
        |ToListMacroAdd|blogOneArgInterceptions#1%
      |fi
%% Now the parsing macro is defined, together with the actions 
%% depending on the result: 
%%                          %% TODO csnames/namemod.sty 2011/11/22
      |@namedef{|blog@x:|StripEsc#1}##1#1##2##3|@nil{%
%% #3 will be empty if and only if <cmd> does \emph{not} occur 
%% in `\fdOutputCode'. A backslash made ``other" will not occur 
%% in `\fdOutputCode', therefore the following 
%% `\ifx' becomes true if and only if #3 is empty, i.e., 
%% <cmd> does \emph{not} occur in `\fdOutputCode':
          |ifx\##3\%
%% In this case we just do nothing.
          |else
%% Otherwise, we apply <run> and <write>:
              #2%
              |def|fdOutputCode{##1#3##3}%
          |fi}%
    }%
  }%
|endgroup
%%                                  %% was single `%' 2011/11/20
%% === &\EXECUTE                       ===
%% |\EXECUTE{<run>}| runs <run> and is removed from the 
%% output line:
\MakeBlogOneArgInterception\EXECUTE{#2}{}
%% You can \strong{store settings} <set> for processing a source 
%% file in this file by `\EXECUTE{<set>}' 
%% (e.g., shorthand macros only useful in this single file). 
%% You even can switch off the interception functionality 
%% after running the other settings <set> 
%% by `\EXECUTE{<set>\BlogCopyLines}'.
%%
%% `\EXECUTE{<run>}' may be a great relief thinking of pure 
%% expansion with 'blog.sty'. You may be happy enough with it 
%% and \emph{restrict} the interception functionality to `\EXECUTE'
%% by |\BlogInterceptExecute|. Its definition may be a 
%% redefinition of the preliminary macro in 'blog.sty'.
%% (TODO: option for stopping here, avoid 'dowith'.)
\def\blog@icl@exec{%
    \let\BlogProcessLine\BlogAllowIntercepting
    \def\BlogInterceptions{\blogTryOneArgCmd\EXECUTE}}
\def\BlogInterceptExecute{\@ifstar@intercept@hash\blog@icl@exec}
%%
%% === &\begin\ and &\end              === 
%% At present (2011/11/06), only |\begin{<env>}| will run   %% box 2012/08/28
%% settings. Macros `\<env>' and `\end<env>' will expand 
%% in the `.html' as with 'blog.sty' alone, not touched here. 
%% Settings to be \emph{run} must be stored in a macro 
%% `\blogx.b:<env>'. If this has not been done, only `\relax' 
%% (from `\csname') will be ``run."
\MakeBlogOneArgInterception\begin{%
%% Indeed, we have a ``modified selection" from \LaTeX's original `\begin':
    \@ifundefined{#2}%
      {\def\@tempa{\@latex@error{Environment #2 undefined}\@eha}}%
      {\def\@tempa{\def\@currenvir{#2}%
%        \edef\@currenvline{\on@line}%              %% not in source
       \csname \blog@x.b:#2\endcsname}}%  %% \StripEsc->: 2012/08/28
    \begingroup \@tempa}{%
    \csname #2\endcsname} 
%% % %% TODO single token!?                     %% rm. 2011/12/15
%% \[|\MakeBlogBeginRun{<env>}<args>{<begin-code>}|\] resembles 
%%  \[`\newenvironment*{<env>}<args>{<begin-code>}{<end-code>}'\] except that 
%% it does not have `{<end-code>}':
\newcommand*{\MakeBlogBeginRun}{\@makeblogbeginrun\newcommand}
%% v0.2 allows redefinition by 
%% \[|\ChangeBlogBeginRun{<env>}<args>{<begin-code>}|\]
\newcommand*{\@makeblogbeginrun}[2]{%
    \expandafter #1\expandafter *%
        \csname \blog@x.b:#2\endcsname}   %%  \StripEsc->: 2012/08/28
\newcommand*{\ChangeBlogBeginRun}{\@makeblogbeginrun\renewcommand}
%% Moreover, v0.2 allows copying that action by 
%% \[|\CopyBlogBeginRunTo{<env>}{<enw>}|\]
\newcommand*{\CopyBlogBeginRunTo}[2]{%
    \withcsname \let \blog@x.b:#2\expandafter\endcsname
                    \csname \blog@x.b:#1\endcsname}
%% |\end{<env>}|: 
\MakeBlogOneArgInterception\end{\@checkend{#2}\endgroup}{\end{#2}}
%    \expandafter\show\csname blogx:end\endcsname
%% \[|\BlogInterceptEnvironments|\] restricts interception functionality 
%% to `\EXECUTE', `\begin', and `\end':
\def\blog@icl@envs{%
    \BlogInterceptExecute
    \ToListMacroAdd\BlogInterceptions{%
        \blogTryOneArgCmd\begin\blogTryOneArgCmd\end}}
\def\BlogInterceptEnvironments{\@ifstar@intercept@hash\blog@icl@envs}
%% TODO: \ 1.~imitate \LaTeX's toggling with `\emph' 
%%       (redefine it in italic environments)
%%       \ 2.~code indenting (cf.~\ctanpkgref{inputtrc})
%% 
%% === Skipping Source Code            ===
%% The |{noblog}| environment ``suppresses" \TeX~source 
%% code in the sense that it does not produce \HTML~code---while
%% 'blog.sty''s `{commentlines}' produces an \HTML~comment.
\newenvironment*{noblog}{}{}    %% 2012/03/04 from ...
\MakeBlogBeginRun{noblog}{%
    \BlogInterceptEnvironments  %% 2012/06/22
    \let\WriteResult\@gobble} 
%% 
%% === A Comfortable Table Environment ===
%% As an application of |\MakeBlogBeginRun| for 'blog.sty''s
%% |{stdallrulestable}|, we provide \lq`|'\rq\ as an active character 
%% invoking 'blog.sty''s  `\endcell' (move to next cell) %% was \cr 2011/11/10
%% and an active character \lq`&'\rq\ for `\figurespace', 
%% i.e., a Unicode symbol for aligning figures. 
%% Indeed, we are \emph{not} going back to \LaTeX\ and Plain \TeX\ 
%% by using `&' for moving to the next cell, I consider the present 
%% choice more intuitive. 
\MakeBlogBeginRun{stdallrulestable}{%
    \MakeActiveDef\|{\endcell}\MakeActiveDef\&{\figurespace}}
%% I hope nobody will confuse `&' and `8'. A little drawback may be 
%% that you now can't use `&' for inserting \acro{HTML} entities. 
%% However, recall that these settings are restricted to the 
%% `{stdrulestable}' environment, and that you can use 
%% `\MakeBlogBeginRun{stdallrulestable}' again for your own choice 
%% of shorthands.
%% (TODO: `\MakeActiveLet')
%% 
%%
%% == Intercepting Two-Parameter Macros ==
%% Here especially I have a macro 
%% |\labelsection{<label>}{<title>}| \emph{in mind} 
%% (TODO).
%% It could be handled by the one-argument approach 
%% by storing the first argument and inserting another macro 
%% that reads the second argument. Therefore I am not sure ...
%% (2011/11/04)
%%
%% == Leaving and HISTORY ==
\endinput
%% \enlargethispage{2\baselineskip}                     %% 2012/08/28
      VERSION HISTORY 

v0.1    2011/11/04  started; arrived at \EXECUTE
        2011/11/05  rm. \blogx@dummy, corrected loop, 
                    \BlogInterceptExtra, \BlogInterceptExecute
        2011/11/06  \BlogAllowIntercepting, emptiness test 
                    with "other" backslash, \begin/\end
        2011/11/07  debugging (\catcode... in \@ifdefinable);
                    warning on reusing interceptor, 
                    \BlogInterceptEnvironments;
                    doc.: raise interception level in \EXECUTE
        2011/11/08  \BlogInterceptHash (understanding needed hours)
        2011/11/10  `v0.1' in \Provides..., doc. fix, 
                    removing experimental code, doc. all 1-arg 
                    interceptions in one section
        2011/11/20  \BlogInterceptHash improved
        2011/11/20  doc. `%' doubled
        2011/11/21  \BlogOutputJob
        2011/11/22  TODO + \z@ for \MakeBlogOne...
        2011/12/15  rm. TODO
v0.2    2012/08/28  \begin/\end revised (\StripEsc wrong)
        2012/08/29  \ChangeBlogBeginRun, \CopyBlogBeginRun, 
                    \blog@x
v0.21   2012/12/20  {noblog}