SGML and literate programming
William Hesse
I may well have missed discussions about this, but I though I would submit
my 2 cents worth:
I have been looking at literate programming. like web, cweb, etc. I
haven't actually worked in any of them yet - I am looking for one that I
want to use. It seems to me that an SGML DTD for literate programming
could be very easily worked out. The worst problem I can see is that of
using < (or &lt; for those using newsreaders that understand
entities) instead of < in code text. That way the web could be woven for
HTML, for typesetting, etc. from the same source, and the web would
probably be easier to write and clearer.
Also, it seems to me that essay form may be best for documenting
algorithms, but that object-oreinted programming is probably best
documented with a hypertext form. Systems would be novels, I guess.
Is anyone working on a DTD (document type definition) for literate
programming?
--
William Hesse
Research Analyst
Connecticut Department of Economic and Community Development
(860) 258-4233
willia...@po.state.ct.us
-<{([|])}>-
bi...@bmorgan.com
I have been working with OS/2's Hyperwise editor along these lines. It can
export as an HTML file and it has the ability to do hypertext like links.
Putting real code into an unstructured list makes the code available to
via a filter for later steps.
As I understand HTML, straight HTML is almost close enough. Actual
code can be placed within <code> </code> or <listing> </listing>.
Things like: < and > can be handled with a sed script, as well
as link info, e.g.:
# litpgm.sed...
/<a/{
s/<a.*'>//
s/<\/a>//
}
s/</</
s/>/>/
/<pre>/, /<\/pre>/p
sed -n -f litpgm.sed < exported.html > almost source code
I have looked at cweb et al. off and on but could never really get into it.
Maybe with HTML aware editors this will make it easier. I started
working with WordPerfect because of it's SGML support but I thought
of using HTML before I figured out how to work with CALS tables. :-)
=================================================
Bill Morgan
Bill Morgan Software Inc.
4653 Park Sutton Place
San Jose, Ca. 95136
(408) 629 - 0129
(408) 225 - 5816 (fax)
Marc van Leeuwen
In article <01bc0a3c$091c5ae0$6aa085d0@bill>, "William Hesse"
<whe...@ct2.nai.net> writes:
|> It seems to me that an SGML DTD for literate programming
|> could be very easily worked out. The worst problem I can see is that of
|> using < (or &lt; for those using newsreaders that understand
|> entities) instead of < in code text. That way the web could be woven for
|> HTML, for typesetting, etc. from the same source, and the web would
|> probably be easier to write and clearer.
I agree that this is the right way to go for those wanting multiple output
formats (it seems though that there are exactly two formats of interest:
LaTeX and HTML). Certainly, it would allow support of the least common
multiple of the output formats rather that their greatest common divisor (as
seems to be the case for most current multi-output systems). Of course, each
output format would have to suppress any information in the source document
that it cannot cope with. But designing the DTD properly would not be an
easy task, since it would have to incorporate a rich language for
representing technical text; maybe not all ground covered by LaTeX, but at
least those features one could conceivably wish to use in a literate
program, which is quite a lot.
--
Marc van Leeuwen | What has man wrought
CWI, Amsterdam | for the year naughty-naught?
http://www.cwi.nl/~maavl/ | '00-programming will get its revenge!
Dave Love
>>>>> "William" == William Hesse <whe...@ct2.nai.net> writes:
William> It seems to me that an SGML DTD for literate programming
William> could be very easily worked out.
Qwertz (possibly propagated to Linuxdoc?) and Wittenberger's `sdc'
system have support for the sort of literate programming that doesn't
provide `flexible order of elaboration', IIRC.
William> The worst problem I can see is that of using < (or
William> &lt; for those using newsreaders that understand
William> entities)
Huh??
William> instead of < in code text.
With the right sort of content model for the code parts can't you
avoid most such complication?
William> That way the web could be woven for HTML, for typesetting,
William> etc. from the same source, and the web would probably be
William> easier to write and clearer.
An SGML backend for noweb could get you the multiple-format output,
but I don't know of a good DTD to target -- one with not only the
appropriate richness (Docbook+maths?) but also good free formatting
support available. (Linuxdoc doesn't seem good enough to me.)
Jens Lippmann
In article <5cedeo$9...@masters0.InterNex.Net>, bi...@bmorgan.com writes:
|> I have been working with OS/2's Hyperwise editor along these lines. It can
|> export as an HTML file and it has the ability to do hypertext like links.
|> Putting real code into an unstructured list makes the code available to
|> via a filter for later steps.
|>
|> As I understand HTML, straight HTML is almost close enough. Actual
|> code can be placed within <code> </code> or <listing> </listing>.
[...]
|> I have looked at cweb et al. off and on but could never really get into it.
|> Maybe with HTML aware editors this will make it easier. I started
|> working with WordPerfect because of it's SGML support but I thought
|> of using HTML before I figured out how to work with CALS tables. :-)
I find that with using HTML, you currently get a fatal loss in quality
if you are used to pretty-printed documents.
For that flavour of literate programs it wouldn't really make sense to
program the document parts in HTML directly.
Eg., how long will it take until math classes are integrated in future
DTD's?
On the other hand I find HTML crucial to literate software development,
not only because of intra-document hyperbility, but also because of the
possibiltiy to connect to the world outside the document.
An approach to combine both requirements could be to present the program
in a less hyperized, but high print-quality state, as well as a full
hyperized one with low quality.
In particular I'd speak of LaTeX in the first, and HTML in the second case.
This approach requires two steps: you program the document parts in LaTeX
to be able to get high quality, and use an HTML converter later to produce
low quality presentations from it.
I find that NOWEB supports this approach quite well.
For the last monthes, I announced a CWEB2HTML package which enables you to
produce HTML from the LaTeX document.
Well, I'm currently working on my master thesis which leaves me no time to
care for support.
But for anyone interested I will send an archive, and if anyone wants to
integrate it somewhere else or develop it further: it's free.
There are much more possibilities to realize that approach.
I don't speak only of LaTeX here.
The need is a powerful hardcopy-oriented-documentation to HTML converter.
To program the doc parts right in HTML currently seems not to yield enough
quality to me.
Kind regards,
Jens Lippmann.
--
# Jens Lippmann http://www-jb.cs.uni-sb.de/~www/people/lippmann
# lipp...@cdc.informatik.th-darmstadt.de
#
# Technische Hochschule Darmstadt http://www.th-darmstadt.de
--
,-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-.
|Jens Lippmann http://www-jb.cs.uni-sb.de/~www/people/lippmann|
Dave Love
>>>>> "Jens" == Jens Lippmann <lipp...@crypt3.cs.uni-sb.de> writes:
Jens> On the other hand I find HTML crucial to literate software
Jens> development, not only because of intra-document hyperbility,
Jens> but also because of the possibiltiy to connect to the world
Jens> outside the document.
You can do that with LaTeX output (perhaps derived from SGML) if you
want. See the current hyperTeX TeXnology, though at least two systems
were doing so under NeWS (RIP, sigh) probably before HTML had escaped
from CERN. [HTML plus current browsers seems an impoverished
hypertext environment to me, apart from the mentioned lack of
typesetting quality and facilities.]
Jens Lippmann
In article <5cedeo$9...@masters0.InterNex.Net>, bi...@bmorgan.com writes:
|> I have been working with OS/2's Hyperwise editor along these lines. It can
|> export as an HTML file and it has the ability to do hypertext like links.
|> Putting real code into an unstructured list makes the code available to
|> via a filter for later steps.
|>
|> As I understand HTML, straight HTML is almost close enough. Actual
|> code can be placed within <code> </code> or <listing> </listing>.
[...]
|> I have looked at cweb et al. off and on but could never really get into it.
|> Maybe with HTML aware editors this will make it easier. I started
|> working with WordPerfect because of it's SGML support but I thought
|> of using HTML before I figured out how to work with CALS tables. :-)
I find that with using HTML, you currently get a fatal loss in quality
if you are used to pretty-printed documents.
For that flavour of literate programs it wouldn't really make sense to
program the document parts in HTML directly.
Eg., how long will it take until math classes are integrated in future
DTD's?
On the other hand I find HTML crucial to literate software development,
not only because of intra-document hyperbility, but also because of the
possibility to connect to the world outside the document.
An approach to combine both requirements could be to present the program
in a less hyperized, but high print-quality state, as well as a full
hyperized one with low quality and small size to get downloaded quickly.
In particular I'd speak of LaTeX in the first, and HTML in the second case.
This approach requires two steps: you program the document parts in LaTeX
to be able to get high quality, and use an HTML converter later to produce
low quality presentations from it.
I find that NOWEB supports this approach quite well.
For the last months, I announced a CWEB2HTML package which enables you to
produce HTML from the LaTeX document.
The package is mainly finished, but I'm currently working on my master thesis
which leaves me no time to care for support and enhancements.
But for anyone interested I will send an archive, and if anyone wants to
integrate it somewhere else or develop it further: it's free.
There are much more possibilities to realize that approach.
I don't speak only of LaTeX here.
The need is a powerful hardcopy-oriented-documentation to HTML converter.
To program the doc parts right in HTML currently seems not to yield enough
quality to me, as it is currently.