[texhax] dual-use input/output macro

[Uwe Lück]

>Karl Berry :
>>Suppose I want to show both the TeX input and its corresponding output
>>as an example.  Not big files, but just small fragments.  As in:
>>
>>  \showme{hello, \relax there}
>>
>>and the typeset output could be, say, two lines:
>>
>>  hello, \relax there   % in typewriter
>>  hello, there          % in roman

1. Some of you may be pleased by a look at Matt Swift's

     CTAN/macros/latex/contrib/frankenstein/compsci.dvi

made from compsci.tex, explaining compsci.sty, both in the
same directory, on "macros for writing about macros".
Indeed, compsci.sty is an extension of doc.sty (unless
I have misunderstood something, as so often).

>Karl Berry :
>>I cannot think of any easy way to do this.  About all I can imagine is
>>changing all the catcodes to other before reading the argument, printing
>>the arg in tt, then writing the arg to an external file, and
>>reading it back with normal catcodes to get the normal output.
>>
>>Is there a simpler way?  Has anyone programmed the above?  I imagine
>>e-tex's \scantokens and \readfile (or something else?) might be useful,
>>but didn't see a quick application.
>>
>>I browsed through the fancyvrb, verbatim, etc., doc but nothing jumped
>>out at me.

At 21:54 17.11.05, Lars Madsen wrote:

>There is of course the way lshort does it, i.e. write the argument to an 
>external file, do a verbatim input and a normal input. I use the same 
>thing for internal examples i my LaTeX book.
>
>But there should be a rather exotic package by Peter Sabo (if it's spelled 
>like that), I've forgotten the name, but he gave a talk about it at 
>EuroTeX 2005.

2. I'd like to endorse the authors of lshort and the LaTeX
Companion to publish the macros they've used for their
examples in separate .sty files (or are they non-free?).

-- You may understand my previous recommendations
immediately or by looking at compsci.dvi[/tex] as above.
Otherwise, some further thoughts of my own ...

(i) doc.sty mainly supports using TeX for explaining
_implementation_. However, is this important?
What is rather important, and for what TeX really is useful,
is the _manual_ ("user guide") explaining the end-user
commands to these end-users.

[a] I am here thinking, in the first instance, of TUGboat etc.
(hello Karl!)

[b] Anyway, has anybody ever profited from TeXed
documentations of implementations? Often only trivia
like \Provides... are explained, not the tricky or critical
things concerning implementation. I may mostly have
profited from the section headings in the implementation
parts of .dtx's .

[c] ... summarizing these and further considerations:
Investing time in _manuals_ surely is worthwhile
-- but what about documentation of implementation?
Is TeXing the latter worthwhile?

At 15:30 18.11.05, Philip TAYLOR wrote:
>Having been a little bit dismissive of Phil Ratcliffe's *solution,
>I thought the least I could do was to post one of my own so that
>he could have his revenge :-)
>
>Here's my version, which satisfies Karl's demo example but which
>hasn't been verified for anything more complex --

(ii) Karl's tiny example that has been dealt with here
is just a nice introduction to what is needed in general.
In practice, code may be to be typeset within a normal
paragraph or, otherwise, in a display line, or in a
\parbox ... likewise for the outcome ... and both
independently from each other. Moreover,
it may be appropriate to let the code appear first and
the outcome afterwards ... or the other way round.
And you might want to arrange input/output in tables
(cf. .../frankenstein/lips.dvi, e.g.).

(iii) It would be nice if "meta-variables" could be
displayed in the "code" as well as (as the outcome
of their code) in the output example
(... know what I mean? seems to be done in
compsci.sty, at least partially).

(iv) Those verbatim things are always so difficult with
headings and footnotes etc., all those category codes ...

(v) Some macros are shorthands in the way that the
user rather wants to know which key-strokes they save
than what the final output is ... including "meta-variables" ...

(vi) ... so my idea was to load some "meta-code-description"
first and then let other macros produce some display
of code or outcome or ... from it ... Here, a "meta-code-decription"
consists of usual code -- no \catcode changes -- and a very
limited amount of macros like \cwd, \marg, \meta ...
depending on ...

(vii) I'll continue as soon as ... [good night ...]

(viii) Finally, here I report an example of how a mailing list
can be superior to Googling and FAQs:
I thought that I once should google or so before I would go on
with my ideas of TeXing macro descriptions. Nothing in the
list that I got help for explaining TeX macros.
But some package "lips" was listed, explained as something
concerning text ellipses with LaTeX. I had thought on text
ellipses much before, so I looked at that "lips" thing in
frankenstein, and there I took a look at the README...

... good night,
   Uwe.