Since we're debating literate programming and embedded documentation,
I wonder what is the point, what are we trying to achieve?
Is it to
a) write books or papers containing pieces of code?
b) add some formatting and functionality to comment blocks?
c) make source code easier to navigate and understand?
d) embed man-pages or similar documentation in the source code?
e) something else entirely?
Anyway, I'd suggest using the existing syntax, with some simple
conventions:
Using POD as a basis, let's instead use {- and -} to delimit our
comment blocks. Then, allow a few tags for markup in there, I'd
suggest we need to label headings, labels and references, and a few
pretty-printing tricks, like emphasis.
Syntax-wise, I'd suggest using the \style{LaTeX}, since these kind of
tags tend IMHO to be more readable than <style>XML/HTML</style>, and
since backslash and curly brackets tend to interfere less with text.
(Also a point to consider, commenting away existing code.) It'd also
be easy to transit to LaTeX-lhs using the \begin{code}-\end{code}.
This should at least partly address b), c) and d), provide an upgrade
path to a), while being completely backwards compatible with existing
tools. Existing source would also be forward compatible, since plain
text in comments would still be fine. Conversion to HTML or
postscript should be straightforward, as well as man page generation.
I've probably not thought things thoroughly through, but at least at
first sight this seems to be a reasonable way to go. Anything I'm
missing?
-kzm
--
If I haven't seen further, it is by standing in the footprints of giants
