On Mon, 30 Jan 1995 09:34:53 CST Karl Eichwalder said:
>I am wondering what's the right way to tag source code.
>
>a) SGML and/or HTML files:
>
>There are examples in the *.P3X files:
>
> <eg><![ CDATA [
> ...
> ]]>
> </eg>
This is definitely what I personally would recommend for examples of
SGML encoding, whether HTML or other. The EG element (part of the
Tag Set Documentation) unfortunately has a name conflict with the
EG (example use of a word) element in the tag set for dictionaries,
but otherwise there is no reason not to define EG as an extension and
use it in the way that P3 itself does.
>b) C source and/or shell scripts:
>
>I do not know. I need something like \verbatim. Shuold one use <eg> as
>well?
Well, EG is a possibility here, but it may depend on what exactly you
want to do. If you are simply exhibiting a bit of code so that you can
discuss it in the accompanying prose, then I think EG is quite right.
If you are practicing 'literate programming', in which the code is
embedded in the documentation in an effort to make it easier to keep
the two in sync with each other, then you might prefer to have another
element with more clearly defined semantics. In an unfinished sketch
of an SGML tag set for literate programming I made a few months ago,
I used the generic identifier SCRAP for the fragments of code (the
term is borrowed from Preston Brigg's program nuweb, the only big
drawback of which is that it is not SGML-based).
If enough people use, or want to use, TEI encoding for production of
technical documentation, then it may make sense to define EG and a few
other tags as an additional tag set for technical documentation. For
now, though, there is no predefined tag set; those interested in having
one should (a) let the editors know and (b) experiment with tags they'd
like to have.
-C. M. Sperberg-McQueen
ACH / ACL / ALLC Text Encoding Initiative
University of Illinois at Chicago
[log in to unmask] / u35395@uicvm
|