RE: [boost] Reference documentation: one approach

From: David Bergman (davidb_at_[hidden])
Date: 2002-10-30 21:52:57

What do we mean by "literate programming"?

I see three distinct interpretations:

1. (Real) Literate Programming - where documentation is default; one
needs to escape into code mode (by "\begin{code}", "<code-snippet>" or
similar). The benefits is that you tend to document the code a lot more,
but the tools (e.g. compiler) needs to either understand this literately
lifted format or have the source preprocessed. See the LHS format in
Haskell for an example of this.

2. Extended Comments -  where one introduces special tags in comments,
often just before members (methods or variables) or classes. See Javadoc
and Doxygen (?) for examples.

3. Documentation Macros - where one uses a high-level macro package in a
documentation tool to embed source code in a uniform way. There exist a
lot of programming macro libraries for LaTeX.

(1) and (2) does not require an additional document, and thus avoid
inconsistencies between specification and code, but (3) is more powerful
solution in that it does not obfuscate the code with specification
information and extensive documentation.

Whatever the alternative, there seems to be two different uses of this
"literate conglomerate of specification and code":

A. Create human-readable documentation, often in conjunction with other
document parts generated by hand in the same format as either the source
format or some intermediate format.

B. Intra- and cross-referencing. The latter form of referencing should
be highly valuable to Boost, to have an automated Super Indexer, in
essence making all the documents one document (it could even be
generated as one single document, in the abstract sense, i.e, document
<> file).

The "conjunction" part of (A) requires that there exist an
(intermediate) format that is fairly easy to read and create for humans
(even though we are developers, I like to classify us as humans...).
Such intermediate formats include LaTeX and HTML. I argue that a more
structured (than XHTML, that is) XML format is not easy to read or
create.

The (B) use, on the other hand, favors XML-like structures, since the
less visual, the easier to reference...

The balance act is to find intermediate formats that satisfies both (A)
and (B) using one (or many) of the approaches (1), (2) and (3). And, all
this while not extending the transformation chain beyond sustainability
(automation and platform independence).

One way to achieve a (2) + (3) + (A) + (B) is to:

1. Use Doxygen tags in code

2. Use Doxygen to generate LaTeX style (.sty)

3. Find and/or write a C++ macro package for LaTeX which must be
"compatible" with (2) (only once...)

4. Use the macros in (3) in extending the deliverable from (2) 

5. Use Doxygen to generate HTML

6. Use a quite shallow XSLT specification to create an index from (5)
(one might need to use a tool like Tidy to actually get to XHTML...)

(4) will give us a complete specification document in LaTeX and (5) will
give us a browsable documentation. 

I admit that this process might not be straight-forward, and that a pure
XML solution would handle (B) much better, and also allow for other
automated cross-referencing.

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of David Bergman
Sent: Wednesday, October 30, 2002 8:35 PM
To: 'Boost mailing list'
Subject: RE: [boost] Reference documentation: one approach

Hi, all.

I used to do *a lot of* LaTeX macroing back then, and can probably catch
up if noone else volunteers ;-)

Does anyone have an idea of what macros we would need (the actual
enumeration could be stolen from some existing C++ "literation" system,
such as Doxygen(?))?

Such a (wish) list would be helpful anyway. Of course, the list should
be in a highly abstract syntax (i.e., no "\begin{classheader}[3]{}...")
so we can either (1) implement the list (in LaTeX or other) or (2) check
the presence of those constructs in an existing macro package (again,
Doxygen?)

I would prefer naming the list "Tag List" to not confuse it with the
programming macro facilities found in C++.

In the absence of such a list, I would probably steal some common tags
from Javadoc and Doxygen and add some other template-specific tags. One
important note, from Bill and others, is that a "literate programming
system" should enable inserting documentation tags in the middle of
methods, which affect the set of tags in the "Tag List".

It feels terrible referring to Doxygen when I have never touched it. I
just hope it is as close to Javadoc as I extrapolate from the
discussion...

David "Why Develop When You Can Document" Bergman

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of Douglas Gregor
Sent: Wednesday, October 30, 2002 7:47 PM
To: Boost mailing list
Subject: Re: [boost] Reference documentation: one approach

On Wednesday 30 October 2002 05:38 am, Anthony Williams wrote:
> I found it remarkably easy to learn to _write document_ using LaTeX
> --- it is learning to write macros that is tricky, and thankfully, we 
> should only have to do that once at the beginning (to write a boost 
> LaTeX class), and then small maintenance issues as people want to add 
> more stuff.

Do we have a volunteer to prototype a little bit of this system so we
can 
determine if it is feasible? My own encounters with writing LaTeX macros
have 
been less than satisfying, though actually writing documents in LaTeX is
a 
joy (read: I'm not volunteering to write the macros, but I wouldn't mind

using a LaTeX-based system if that turns out for the best).

        Doug
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost

_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost