several docs from the same noweb file?
Fernando Mato Mira
Would anybody care to give a short example of how
to write/use a noweb file to generate:
1. A reference manual (only function signatures / public
slots of stuctures appear in the doc + some description + short example)
2. A user's guide (no signatures, presentation follows a
different order, long examples).
3. An implementors' manual (like a refence manual, but with
discussion about caveats, etc.).
4. A classic literate program doc (need not include the examples).
I guess 2) should probably be written separately.
By the way, is it possible to `include' pure documentation
files into a noweb file?
a. Editing a file with correct code just do document seems a bad idea.
An error might be introduced accidentally.
b. A documentation might be cleaned-up by someone not authorized to change
the code.
c. Touching the file with the code is uncool with make et al.
d. Too much doc mixed with the code makes it unpractical for programming
(unless non-code sections can be hidden in Emacs).
PS: If what I want seems to point to some other system, please
note that I program in Lisp.
Thanks a lot,
--
F.D. Mato Mira http://ligwww.epfl.ch/matomira.html
Computer Graphics Lab mato...@epfl.ch
EPFL FAX: +41 (21) 693-5328
Norman Ramsey
Fernando Mato Mira <mato...@di.epfl.ch> wrote:
> Would anybody care to give a short example of how
>to write/use a noweb file to generate:
> 1. A reference manual (only function signatures / public
>slots of stuctures appear in the doc + some description + short example)
> 2. A user's guide (no signatures, presentation follows a
> different order, long examples).
> 3. An implementors' manual (like a refence manual, but with
> discussion about caveats, etc.).
> 4. A classic literate program doc (need not include the examples).
Don't even *think* about it. All the experiments I have tried along
these lines have ended in disaster. The problem is, how are you going
to edit and understand the source code for 4 different documents
simultaneously? Especially such different documents?
Slipping pieces of a reference manual into a document that is mostly a
classic literate program seems OK. That is, it's not too hard to get
the manual right, and the intercalated chunks aren't too disruptive.
But even that is a bit creaky.
>By the way, is it possible to `include' pure documentation
>files into a noweb file?
This question suggests that maybe you don't ``get'' the
literate-programming paradigm. I suggest you read some of Don Knuth's
papers, and also the Don Lindsay LP column from CACM, with special
attention to reviewer Harold Thimbleby's comments.
> a. Editing a file with correct code just do document seems a bad idea.
> An error might be introduced accidentally.
Leaving your documentation off in another file seems a bad idea. It
might get *way* out of date.
> b. A documentation might be cleaned-up by someone not authorized to change
> the code.
The literate document *is* the program. Someone not authorized to
touch it ought not to touch it.
> c. Touching the file with the code is uncool with make et al.
Use cpif.
> d. Too much doc mixed with the code makes it unpractical for programming
> (unless non-code sections can be hidden in Emacs).
If the documentation isn't helping you program it's not doing its job.
Joachim Schrod
> In article <383lcs$b...@blackice.winternet.com>, tra...@icicle.winternet.com (Barry Schwartz) writes:
> |> In article <37ut2d$9...@disunms.epfl.ch>
> |> mato...@di.epfl.ch (Fernando Mato Mira) writes:
> |>
> |> ] c. Touching the file with the code is uncool with make et al.
> |>
> |> The cpif program addresses this problem.
>
> This is now the second time that I hear about cpif. What is it?
cpif is part of the noweb distribution, it copies standard input to a
file only if the contents did not change. (Or did change, as you
want.)
---------------- snip snap ----------------------------------------
#!/bin/sh
# cpif [ -eq -ne ] file...
# copy standard input to each of the named files
# if new * old is true or old doesn't exist;
# * defaults to -ne
PATH=/bin:/usr/bin
# set -x
op=-ne
case "$1" in
-eq|-ne) op=$1; shift ;;
-*) echo 'Usage: '`basename $0`' [ -eq -ne ] file...' 1>&2; exit 2
esac
case $# in
0) echo 'Usage: '`basename $0`' [ -eq -ne ] file...' 1>&2; exit 2
esac
new=/tmp/$$
trap 'rm -f $new; exit 1' 1 2 15 # clean up files
cat >$new
for i
do
cmp -s $new $i
case $op$? in
-eq0|-ne1|*2) cp $new $i
esac
done
rm -f $new
---------------- snip snap ----------------------------------------
Actually, not long ago I needed to extend this to `real' file copy
operations, so here is my copyif. (E.g., I use it for parser
generators like PCCTS who create the scanner as an intermediate file
and would trigger spurious compilation of the scanner as it has
changed.)
As it's roughly upward compatible (as long as only one file is
`cpif'ed), I use it for noweb, too... :-)
---------------- snip snap ----------------------------------------
#!/bin/sh
# $ITI: copyif,v 1.1 1994/07/14 12:55:24 schrod Exp $
#----------------------------------------------------------------------
#
# copyif -- copy files if comparison succeeds
#
# (history at end)
# SYNOPSIS
#
# copyif [-eq | -ne] file
# copyif [-eq | -ne] file1 file2
# copyif [-eq | -ne] file ... dir
#
#
# copyif copies a file if a comparison succeeds or if the target file
# does not exist. The comparison is either a test if the contents is
# equal (-eq) or if it has changed (-ne). The default is -ne.
#
# The first call form copies standard input to <file>file</>. The second
# one copies <file>file1</> to <file>file2</>. The third copies all
# <file>files</>s into directory <file>dir</>.
#
# The source file(s) and also the target file/dir must be readable,
# and target must be writable.
#
# A typical usage is in Makefiles where a file shall only be copied if
# it has changed.
#
#
cmd=`basename $0`
usage()
{
cat <<_EOF_ >&2
usage:
$cmd: [-eq | -ne] file
$cmd: [-eq | -ne] file1 file2
$cmd: [-eq | -ne] file ... dir
_EOF_
exit $1
}
# parse options...
test $# = 0 -o "$1" = '-?' && usage 1
# default is -ne
case "$1" in
-ne|-eq) test=$1
shift
;;
*) test='-ne'
;;
esac
# one parameter => save source from stdin in $tmp_file
if [ $# = 1 ]
then tmp_file=/tmp/copyif$$
trap "rm -f $tmp_file" 0 1 2 3 15
cat >$tmp_file
src=$tmp_file
dest_file=$1
dest_dir=''
fi
# two parameter
if [ $# = 2 ]
then src=$1
# Target argument might be a directory, ie, this might be a
# call of form 3.
if [ -d "$2" ]
then dest_file=''
dest_dir=$2
else dest_file=$2
dest_dir=''
fi
fi
# n parameter
# $1 .. $n-1 are $src
# $n is $dest_dir
if [ $# -gt 2 ]
then # Split list of arguments on last blank and assign thereby the
# source files to $src.
src=`expr "$*" : '\(.*\) '`
dest_file=''
# Discard all source arguments
shift `expr $# - 1`
# Check if target argument is a directory, complain if not
if [ ! -d "$1" ]
then echo "$cmd: $1: not a directory." >&2
usage 2
else dest_dir=$1
fi
fi
# pre:
# $src is list of source files
# either $dest_dir is destination directory
# or $dest_dir is empty and $dest_file is destination file and
# $src is only one file
result_code=0
for file in $src
do test "$dest_dir" && dest_file=$dest_dir/$file
# now $dest_file holds the target file name
# check if it exists
if [ -f $dest_file ]
then cmp $file $dest_file >/dev/null
result="$test$?"
case "$result" in
*2) # error in cmp command, message was issued
exit 2
;;
-eq1|-ne0)
continue
;;
esac
fi
cp $file $dest_file
result_code=`expr $result_code + $?`
done
# If there was at least one error in cp, add 10 to the result code.
# This way we get a unique exit code that we can distinguish from
# internal errors.
test $result_code != 0 && result_code=`expr $result_code + 10`
exit $result_code
#======================================================================
#
# $ITIlog: copyif,v $
# Revision 1.1 1994/07/14 12:55:24 schrod
# Initial revision.
#
---------------- snip snap ----------------------------------------
Enjoy,
Joachim
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod Email: sch...@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
Barry Schwartz
]
] Would anybody care to give a short example of how
]to write/use a noweb file to generate:
] 1. A reference manual (only function signatures / public
]slots of stuctures appear in the doc + some description + short example)
] 2. A user's guide (no signatures, presentation follows a
] different order, long examples).
] 3. An implementors' manual (like a refence manual, but with
] discussion about caveats, etc.).
] 4. A classic literate program doc (need not include the examples).
I have argued (in this newsgroup, in fact) that there are literary
reasons not to do this. My argument is that the manuals are works of
literature on the same level as the literate program, and so should be
written separately. There can be information about how to use the
program written into the literate program itself, but good exposition
style dictates that this information be terse. Notice that I make
these arguments on grounds that come from expository writing and not
traditional programming practice; I believe that literate programming
is as much a task of expository writing as it is a task of producing a
working program. Actually I view all serious programming this way
(read "The Elements of Programming Style," by Kernighan and Plauger),
but literate programming gives you better tools to do the job.
An "implementor's manual" is an interesting thing to contemplate. The
code itself should be documented in the literate program, and so there
is no need for a separate manual. If you need one, then you haven't
written an adequate literate program; go back and edit it. Designs
present another obstacle, however. If the design is written in a
precise language (say a variant of Ada, which I believe is used by
IBM), then it should be possible to use noweb. Then you have at least
two literate programs, one for the design and one for the code.
Together, and along with the Requirements, they make up an
implementor's manual, as well as the working program.
]By the way, is it possible to `include' pure documentation
]files into a noweb file?
That's like asking if it is possible to love someone without
commitment. The question shouldn't be "is it possible," but "is it
valuable." "Is it valuable to love someone without commitment?" The
answer is No. Similarly, there is little value in including the
separate documentation within the noweb file. You might as well leave
it separate. If you want to attach the documentation to the code in
some secure way, you might as well put them together in a zip archive
or something like that. You will gain none of the benefits of
literate programming, of course.
] a. Editing a file with correct code just do document seems a bad idea.
] An error might be introduced accidentally.
Code is not really correct unless you can edit it without great fear
of breaking it. Most code has to be maintained, after all. Read "The
Elements of Programming Style," by Kernighan and Plauger.
] b. A documentation might be cleaned-up by someone not authorized to change
] the code.
This is a program configuration problem, not a problem with noweb. If
this can happen then there is something wrong with the quality
management process.
] c. Touching the file with the code is uncool with make et al.
The cpif program addresses this problem.
] d. Too much doc mixed with the code makes it unpractical for programming
] (unless non-code sections can be hidden in Emacs).
The last thing you want to do is ignore the explanation of what the
code does, when you go in to modify the code. In a literate program,
ideally the exposition and the code are an organic entity. This is
not like what you might imagine, the code as "sufficient explanation
of what's going on" and the documentation as "here's a few notes about
what I've written." The way I view things, you should have the plain
language notes there to keep you on course, and if you find something
is wrong you should update the plain language along with the code.
After all, the program is not correct unless both documentation and
code are correct. (Read "The Elements of Programming Style," by
Kernighan and Plauger.)
Furthermore, if you really find that mixing docs and code is
unpractical, then I think something is wrong, and I think I know what.
The only way I can imagine this happening is if the program has bad
modularity, in either the programming sense or the literate sense.
There is some question as to how well Emacs modes handle literate
programming, but that's an Emacs problem, not a literate-programming
problem.
]PS: If what I want seems to point to some other system, please
] note that I program in Lisp.
I agree with the view that a literate programming system should be
language-independent. Noweb is such a system. Lisp is no problem for
it.
--
Barry Schwartz at MedGraphics tra...@winternet.com
Kasper Osterbye
Norman> In article <37ut2d$9...@disunms.epfl.ch>, Fernando Mato
Norman> Mira <mato...@di.epfl.ch> wrote:
>> Would anybody care to give a short example of how to write/use
>> a noweb file to generate: 1. A reference manual (only function
>> signatures / public slots of stuctures appear in the doc + some
>> description + short example) 2. A user's guide (no signatures,
>> presentation follows a different order, long examples). 3. An
>> implementors' manual (like a refence manual, but with
>> discussion about caveats, etc.). 4. A classic literate program
>> doc (need not include the examples).
Norman> Don't even *think* about it. All the experiments I have
Norman> tried along these lines have ended in disaster. The
Norman> problem is, how are you going to edit and understand the
Norman> source code for 4 different documents simultaneously?
Norman> Especially such different documents?
Norman> Slipping pieces of a reference manual into a document that
Norman> is mostly a classic literate program seems OK. That is,
Norman> it's not too hard to get the manual right, and the
Norman> intercalated chunks aren't too disruptive. But even that
Norman> is a bit creaky.
Well, but the problem remains then. Literate programming is well
suited to make sure that the program and its low level exposition are
kept up to date, but how can we ensure that the other documents
Fernando mentions has the same quality? You say that you have
attempted it in many different ways - are there no hope to extend the
literate paradigm to include the apparently natual thing Fernando
wants to do?
-- Kasper
--
Kasper Osterbye Internet: kas...@iesd.auc.dk
Aalborg University FAX: +45 98 15 81 29
Fredrik Bajers vej 7E, 9220 Aalborg Phone: (W) +45 98 15 85 22
DENMARK. (H) +45 98 11 09 25
Sven Utcke
|> mato...@di.epfl.ch (Fernando Mato Mira) writes:
|>
|> ] c. Touching the file with the code is uncool with make et al.
|>
|> The cpif program addresses this problem.
This is now the second time that I hear about cpif. What is it? Can
it be used with, say, FWEB (the literate program of my choice)? If
so, where can I get it (ask archie, I suppose?)?
Thanks
Sven
Norman Ramsey
Kasper Osterbye <kas...@iesd.auc.dk> wrote:
>Well, but the problem remains then. Literate programming is well
>suited to make sure that the program and its low level exposition are
>kept up to date, but how can we ensure that the other documents
>Fernando mentions has the same quality? You say that you have
>attempted it in many different ways - are there no hope to extend the
>literate paradigm to include the apparently natual thing Fernando
>wants to do?
I think extending the literate paradigm is a misguided idea. Literate
programming is about writing documents that are also programs. The
mechanisms commonly used to create literate programs also appear to be
capable of combining multiple documents into a single source, but
that's an accident, and we shouldn't let it seduce us into insisting
on doing things that way. In fact, literate programming as practiced
today is really good only for producing single documents.
I know of two experiments that are not failures. One is one of mine,
which includes portions of a reference manual (as *code*) in a
document that is the implementation of the tool described in the
reference manual. This scheme is workable only because the size of
the reference-manual fragments is a tiny fraction of the whole
document, well under 10%. (The bulk of the manual lives in its own
source files anyway.) I would not call it a success, but it's not a
failiure, either. I'm not sure the benefit we get outweighs the
added difficulty of editing the source. I may be able to tell better
as we see how the implementation and reference manual evolve over
time. I certainly wouldn't advocate that other people do this except
as an experiment.
The one experiment I know of that was successful was that of Jon
Bentley and others at Bell Labs in describing the PRL5 language. In
that case:
- six or so documents were generated from the same source.
- there was no code involved, only documentation.
- the six documents had identical outlines (structures)
- (I believe) documents didn't share text
For this limited problem, they got good results using a custom little
language to generate the documents. I see no way of generalizing to
documents that have different structures.
I've seen claims for hypertext systems, but I'm not sure hypertext is
a 'document' in the sense I'm used to thinking of. I have found
hypertext useful for browsing to find bits of information, but much
less so for reading in bulk to get a coherent, in-depth understanding
of anything. I'm also not sure what it means to have *multiple*
documents if everything's connected together in a hypertext web.
As for where we go from here, I think people ought to be thinking
about new tools and techniques to support the creation of multiple
documents with different contents and structure but which have to be
kept consistent. It's a hard problem, and I'm not sure the skills of
the literate programmer are a great match for it.
Norman