from pet peeves to complainants about C++ in cweb

[mikolas]

I wrote some pieces of code using cweb with C++ being the programming language. Overall, I'm happy with the methodology and would like to continue using it. However, there are some deficiencies that seem to be hindering the use thereof significantly. I would appreciate any type of feedback on the following complaints and pet peeves. Would switching to noweb be a good idea? (I haven't tried noweb as it seems to be hard to install on Windows, which I have to use for a certain reason.)

So here we go, in no particular order.

1) Tool support is not great. Emacs does not give me syntax highlighting and altogether seems to be acting as a plain text editor. VI is a little better but still, word completion's not great.

2) Introducing "@s" directives for every type is very annoying (I'm also not sure how to reuse these directives between different files) .

3) Imports of the form "using bar::foo" are not typeset correctly.

4) Variable or argument declarations using templates are not typeset correctly (even if make_pair is used).

5) I'm quite unclear on how one goes about bundling up a bigger project. I'm putting each clause in a different ".w" file and eventually I will end up with a bunch of documents with no inter-linkage.

6) A meta-complaint. The lack of proper support makes me very suspicious about the number of people using the tools/approach.

[Aaron W. Hsu]

I use CWEB for C, not C++, so take the following comments with a grain of
salt or two.

1) Tool support is not great. Emacs does not give me syntax highlighting an=
d altogether seems to be acting as a plain text editor. VI is a little bett=
er but still, word completion's not great.

CWEB has a cweb mode that you can install and use. It is commented with
some explanation of how one uses it, but fundamentally I think it is
more of a TeX mode than a C/C++ mode. I have never been a big user of
word completion, so I cannot comment there. I also use NEdit most of the
time, or ed(1), and not Vi or Emacs. I have a custom set of highlightings
that I use for CWEB + C in NEdit that works quite well.

ot sure how to reuse these directives between different files) .

I do not know how it works for C++, but most of the types declared in
a C based CWEB document do not require @s directives. I only need @s
directives if I refer to a type long before I typedef it or the like.
Otherwise, my types get formatted correctly.

3) Imports of the form "using bar::foo" are not typeset correctly.

You may be able to use @s or another control code to set how you
want those forms typeset.

5) I'm quite unclear on how one goes about bundling up a bigger project. I'=
m putting each clause in a different ".w" file and eventually I will end up=
with a bunch of documents with no inter-linkage.

Most of the time I stick to putting most things into a single file. But
this is C code. For example, usually, I have a one executable/shared library
per file organization. You can use the @i code to break these out into
separate pieces if you find that having the one large file difficult to
navigate, though I find bookmarks or other jump points, and the PDF
enough to manage that.

You may also want to look at the @( code, which allows sending to
multiple files. I usually use it only for auxiliary files like header
files, and not main files, but you may find it suitable for auxiliary
class files or the like.

You can also use some TeX macro hackery to take files that would normally
weave into separate documents and combine them together into a single
document, once you understand the TeX output by CWEB. I've not needed to
do this before, but I am sure that it can be done.

6) A meta-complaint. The lack of proper support makes me very suspicious ab=
out the number of people using the tools/approach.

I suspect that most literate programming tools do not see nearly the use
of something like, say, JavaDocs, but you're also assuming that most people
would want "tool support" in the way you are talking. CWEB is a mostly
frozen program (like TeX), barring large and unforeseen bugs. However, it
is quite stable and usable. I use it in conjunction with my own ChezWEB on
mostly all my projects. It's a good tool, but it's design and its users
are likely more text editor hacker types; I know I am. I don't use large
IDEs most of the time, or extra features like word completion (though
I sometimes use some other macros to call up man pages or something
equivalent).

Knuth's own workflow is, I believe, an Emacs buffer in cweb.el mode, so
at least that is somewhat how the system was designed, but that is also
for a C workflow. I don't know how good CWEB is at handling C++ features.
You can checkout the Stanford GraphBase for an example of a set of multiple
files that correspond to multiple features in C. I am not aware of a good
example of CWEB use in C++; maybe someone else can recommend something?

[dtopham]

Post by Aaron W. Hsu
I use CWEB for C, not C++, so take the following comments with a grain of
salt or two.

1) Tool support is not great. Emacs does not give me syntax highlighting an=
d altogether seems to be acting as a plain text editor. VI is a little bett=
er but still, word completion's not great.

CWEB has a cweb mode that you can install and use. It is commented with
some explanation of how one uses it, but fundamentally I think it is
more of a TeX mode than a C/C++ mode. I have never been a big user of
word completion, so I cannot comment there. I also use NEdit most of the
time, or ed(1), and not Vi or Emacs. I have a custom set of highlightings
that I use for CWEB + C in NEdit that works quite well.

ot sure how to reuse these directives between different files) .

I do not know how it works for C++, but most of the types declared in
directives if I refer to a type long before I typedef it or the like.
Otherwise, my types get formatted correctly.

3) Imports of the form "using bar::foo" are not typeset correctly.

want those forms typeset.

5) I'm quite unclear on how one goes about bundling up a bigger project. I'=
m putting each clause in a different ".w" file and eventually I will end up=
with a bunch of documents with no inter-linkage.

Most of the time I stick to putting most things into a single file. But
this is C code. For example, usually, I have a one executable/shared library
separate pieces if you find that having the one large file difficult to
navigate, though I find bookmarks or other jump points, and the PDF
enough to manage that.
multiple files. I usually use it only for auxiliary files like header
files, and not main files, but you may find it suitable for auxiliary
class files or the like.
You can also use some TeX macro hackery to take files that would normally
weave into separate documents and combine them together into a single
document, once you understand the TeX output by CWEB. I've not needed to
do this before, but I am sure that it can be done.

6) A meta-complaint. The lack of proper support makes me very suspicious ab=
out the number of people using the tools/approach.

I suspect that most literate programming tools do not see nearly the use
of something like, say, JavaDocs, but you're also assuming that most people
would want "tool support" in the way you are talking. CWEB is a mostly
frozen program (like TeX), barring large and unforeseen bugs. However, it
is quite stable and usable. I use it in conjunction with my own ChezWEB on
mostly all my projects. It's a good tool, but it's design and its users
are likely more text editor hacker types; I know I am. I don't use large
IDEs most of the time, or extra features like word completion (though
I sometimes use some other macros to call up man pages or something
equivalent).
Knuth's own workflow is, I believe, an Emacs buffer in cweb.el mode, so
at least that is somewhat how the system was designed, but that is also
for a C workflow. I don't know how good CWEB is at handling C++ features.
You can checkout the Stanford GraphBase for an example of a set of multiple
files that correspond to multiple features in C. I am not aware of a good
example of CWEB use in C++; maybe someone else can recommend something?
--
Programming is just another word for the lost art of thinking.

You may wish to try nuweb; it is easy to compile on any platform being distributed in source code and only requiring a single C program to use.
I think it is effective for C++. Take a look at this excellent example:
http://www.cs.rpi.edu/~musser/gp/literate.html

-Dave

[Simon Wright]

Post by dtopham
You may wish to try nuweb; it is easy to compile on any platform being
distributed in source code and only requiring a single C program to
use.
http://www.cs.rpi.edu/~musser/gp/literate.html

The web for the Fast Generic Sequence matching Algorithm referenced in
the paper is at [1]. The PostScript output is at [2].

I've been helping to maintain nuweb at SourceForge [3]. In spite of it's
being developed in nuweb, there are some aspects of the code that are
quite hard to understand, so (to satisfy an itch) I've been working on a
Python version, latest at [4]. The pdflatex output from [1] using [4] is
at [5] (after slight alteration to the source; it specified
\textheight=4.5in).

[1]
http://assassin.cs.rpi.edu/~musser/archive/2001/ap/gensearch/gensearch.w
[2] http://www.cs.rpi.edu/~musser/gp/gensearch.ps
[3] https://sourceforge.net/projects/nuweb/
[4] http://goo.gl/Y0zOU
[5] http://dl.dropbox.com/u/34783908/Non-Ada/gensearch.pdf

[Aaron W. Hsu]

Post by dtopham
You may wish to try nuweb; it is easy to compile on any platform being distributed in source code and only requiring a single C program to use.
http://www.cs.rpi.edu/~musser/gp/literate.html

Was this directed at me or to the OP? I looked at nuweb, and it is on my
list of programs to keep around, but I had trouble understanding its very
bad HTML output and the TeX output did not seem much better. CWEB's output,
and that of ChezWEB's is easier for me to understand and work with, despite
targeting only TeX. I have yet to find a really nice means to targeting
multiple output languages and still getting the level of typesetting clarity
that I want from my literate programs.

[Simon Wright]

Post by Aaron W. Hsu
Was this directed at me or to the OP? I looked at nuweb, and it is on
my list of programs to keep around, but I had trouble understanding
its very bad HTML output and the TeX output did not seem much
better. CWEB's output, and that of ChezWEB's is easier for me to
understand and work with, despite targeting only TeX. I have yet to
find a really nice means to targeting multiple output languages and
still getting the level of typesetting clarity that I want from my
literate programs.

Is your difficulty with the (La)TeX output viewed as a text file or with
its presentation after processing?

I've only ever looked at the .tex to sort out problems in nuweb.

I agree about the latex2html output; pdflatex (with the hyperref
package) suits me fine (perhaps I'm not very demanding).

[Aaron W. Hsu]

Post by Simon Wright
Is your difficulty with the (La)TeX output viewed as a text file or with
its presentation after processing?
I've only ever looked at the .tex to sort out problems in nuweb.

My main issue is with my ability to get really quality typesetting
from nuweb. Admittedly, I only examined it for a short time, and I did
not get too far. The output of nuweb was too generic. In other words,
there were not enough elements that were actually embedded into the
language that allowed me to get control over what I wanted. Pretty
printing seemed right out, and especially getting good control over
the presentation of the code. above that, however, was the ability
to get a good level of formatting in the source document to be used
in the woven result. I could have done post-processing on the TeX file
that nuweb produced, but this defeats the purpose. Nuweb's structure
seemed to lend itself to a more agnostic approach, which is fine, and
has a lot of advantages, but these seemed to get in the way of
doing my own well controlled formatting. As an example, I used the
then current version of ChezWEB to produce an academic paper on
ChezWEB, the woven result, which was published, you can see here:

http://www.schemeworkshop.org/2011/papers/Hsu2011.pdf

I would have had trouble formatting the paper like this in some of
the other systems. I really like the output of CWEB, and its style
is good, but more than that, I understand how the produced results are
actually rendered using TeX, which allows me to make suitably understandable
modifications to the TeX macro file for custom results. I have found
this harder to do on systems that insist on using LaTeX, or at
least, do not have a TeX version with good reasonable defaults,
because they often do not put enough information into the TeX file,
meaning that much of the work I have to do for myself there.

In other words, I find it easier to work with the traditional web macros
than other approaches I have seen. Others would disagree with me.
The best other approach I have seen is one that uses XML with DocBook
to get results, but I haven't been able to get a good workflow going
with those, so I have been mostly sticking with WEB style systems.

Right now I hope to have an APL pretty printer for WEB style systems
by the start of next year, which will allow me to have a really nice
APLWEB for my HPAPL language that I am writing.

[dtopham]

Post by Aaron W. Hsu

Post by dtopham
You may wish to try nuweb; it is easy to compile on any platform being distributed in source code and only requiring a single C program to use.
http://www.cs.rpi.edu/~musser/gp/literate.html

Was this directed at me or to the OP?

Mostly to mikolas, but really just a general comment since I am interested and don't find too much discussion about LP tools anywhere so I am happy to take part in any! My goals are perhaps different than many programmers because I am an educator looking for ways to get students to write about code as well as write the code itself. I believe it helps to learn if you have to explain in English and has the added benefit of being able to include graphics, screen images, test results, etc. all in one place. So far, I am completely sold on the idea. The only difficulty is that beginning students are already struggling with learning a new language (C++) and now I also ask them to learn nuweb, and latex (but limited subsets). I think it is worth it.

[Aaron W. Hsu]

Mostly to mikolas, but really just a general comment since I am interested =
and don't find too much discussion about LP tools anywhere so I am happy to=
take part in any! My goals are perhaps different than many programmers be=
cause I am an educator looking for ways to get students to write about code=
as well as write the code itself. I believe it helps to learn if you have =
to explain in English and has the added benefit of being able to include gr=
aphics, screen images, test results, etc. all in one place. So far, I am co=
mpletely sold on the idea. The only difficulty is that beginning students a=
re already struggling with learning a new language (C++) and now I also ask=
them to learn nuweb, and latex (but limited subsets). I think it is worth =
it.

I actually used literate programming as a means to delivering code to
students in an A.I. course. The libraries that they were to use were
delivered as literate programs so that they could learn from the code
as well as understand how to use it. This seems to have worked quite
well, and I hope that continued refinements will continue to result
in better student understanding.