It was interesting to read

Common Lisp: The Untold Story
Kent M. Pitman
HyperMeta Inc.
http://www.nhplace.com/kent/

His considerations of copyright and title 17 of the US code was
particularly interesting.

Julieta Shem <jshem@yaxenu.org> writes:

> It was interesting to read
>
> Common Lisp: The Untold Story
> Kent M. Pitman
> HyperMeta Inc.
> http://www.nhplace.com/kent/

Yes, thanks for the link. Since he mentioned subsetting the (huge)
language in another article,

https://nhplace.com/kent/PS/dpANS.html

I searched around for subsets (not very fruitful), but I did happen to
find one quite interesting online textbook (apart from the usual
suspects), "Learn Lisp the hard way":

https://llthw.common-lisp.dev/

Might be interesting for you as well. I seem to remember that you found
the classics (Seibel, Touretzky) very readable and enjoyed them (I
worked through the Touretzky years ago, but stalled on the Seibel,
perhaps due to lack of exercises). "On Lisp" and even more so "Let over
Lambda" are more advanced, while the above link seems to be more
"modern" in the sense of being written not in the 90s or early
2000s. Not that the language itself has changed, but the IT world has
changed a lot since then, and my hope is that this is reflected in
the approach. But I am still quite at the beginning.

Best regards

Axel

* Axel Reichert <87a5onolta.fsf @axel-reichert.de> :
Wrote on Mon, 29 Jan 2024 22:45:53 +0100:
> Julieta Shem <jshem@yaxenu.org> writes:
>> It was interesting to read
>> Common Lisp: The Untold Story
>> Kent M. Pitman
>> HyperMeta Inc.
>> http://www.nhplace.com/kent/
>
> Yes, thanks for the link. Since he mentioned subsetting the (huge)
> language in another article,
>
> https://nhplace.com/kent/PS/dpANS.html
>
> I searched around for subsets (not very fruitful), but I did happen to
> find one quite interesting online textbook (apart from the usual
> suspects), "Learn Lisp the hard way":
>
> https://llthw.common-lisp.dev/
>
> Might be interesting for you as well. I seem to remember that you found
> the classics (Seibel, Touretzky) very readable and enjoyed them (I
> worked through the Touretzky years ago, but stalled on the Seibel,
> perhaps due to lack of exercises). "On Lisp" and even more so "Let over
> Lambda" are more advanced, while the above link seems to be more
> "modern" in the sense of being written not in the 90s or early
> 2000s. Not that the language itself has changed, but the IT world has
> changed a lot since then, and my hope is that this is reflected in
> the approach. But I am still quite at the beginning.

I came across new introductory material in a personalised style, which
may appeal to some readers (or put some off)

"Rabbi Botton" The common Lisp Tutorial, Fast, Fun Practical Quickstart
(with CLOG), 2024

https://rabbibotton.github.io/clog/cltt.pdf

[I could excuse uncouth alien in cover pic but my aged eyes (brought up
on computer modern) couldn't abide with the typography, fonts, and
layout, which stinks of "modern css", grey on white sans fonts with css
tricks for code blocks, which makes it look like a cheap modern webpage

as with the other unreadable pdf material i've download, pdfinfo reveals
the same culprit: Creator: Chromium Producer: Skia/PDF m120 or Producer:
Skia/PDF m122 Google Docs Renderer etc]

Axel Reichert <mail@axel-reichert.de> writes:

> Julieta Shem <jshem@yaxenu.org> writes:
>
>> It was interesting to read
>>
>> Common Lisp: The Untold Story
>> Kent M. Pitman
>> HyperMeta Inc.
>> http://www.nhplace.com/kent/
>
> Yes, thanks for the link. Since he mentioned subsetting the (huge)
> language in another article,
>
> https://nhplace.com/kent/PS/dpANS.html

Thanks. Interesting read.

> I searched around for subsets (not very fruitful), but I did happen to
> find one quite interesting online textbook (apart from the usual
> suspects), "Learn Lisp the hard way":
>
> https://llthw.common-lisp.dev/

It's an in-progress draft. It's looking pretty good. I don't even
think a book to teach one how to use a language needs that much. But if
the author has that much energy, I think it's useful.

> Might be interesting for you as well. I seem to remember that you found
> the classics (Seibel, Touretzky) very readable and enjoyed them (I
> worked through the Touretzky years ago, but stalled on the Seibel,
> perhaps due to lack of exercises).

I did not read Touretzky.

> "On Lisp" and even more so "Let over Lambda" are more advanced,

I did not try to read ``Let over Lambda'', but ``On Lisp'' looks
readable---at least up to the first chapters on macrology.

Are you writing a program? I think that's super important. Do things
from beginning to the end. I'm very fond of literate programming, so I
always write it literate as well---I give myself the best lecture I can.
I often reread the work many times over the years, which seems very
healthy.

I wish we had a tool like CWEB but for Common Lisp. The stability of
Common Lisp seems promising. (I use Norman Ramsey's noweb. It produces
a beautiful document.)

> while the above link seems to be more "modern" in the sense of being
> written not in the 90s or early 2000s. Not that the language itself
> has changed, but the IT world has changed a lot since then, and my
> hope is that this is reflected in the approach. But I am still quite
> at the beginning.

On UNIX, for instance, I read The Unix Programming Environment by
Kernighan and Pike. It was published in 1984. I think it's still the
best book on presenting the system. The whole ``modern'' thing is
better called postmodern. :-)

What I have been reading is Gabriel and Steele's ``Evolution of Lisp'',
the uncut version. It's been fun to see the story of many things. To
me it often seems very useful to see the history of things. I need to
understand the names, for instance. Gabriel and Steele are helping very
much.

Madhu <enometh@meer.net> writes:

[...]

> I came across new introductory material in a personalised style, which
> may appeal to some readers (or put some off)

That's fine to me.

> "Rabbi Botton" The common Lisp Tutorial, Fast, Fun Practical Quickstart
> (with CLOG), 2024
>
> https://rabbibotton.github.io/clog/cltt.pdf
>
> [I could excuse uncouth alien in cover pic but my aged eyes (brought up
> on computer modern) couldn't abide with the typography, fonts, and
> layout, which stinks of "modern css", grey on white sans fonts with css
> tricks for code blocks, which makes it look like a cheap modern webpage
>
> as with the other unreadable pdf material i've download, pdfinfo reveals
> the same culprit: Creator: Chromium Producer: Skia/PDF m120 or Producer:
> Skia/PDF m122 Google Docs Renderer etc]

It's an interesting thing. I often wonder why people put a lot of text
on fonts sans serif. It seems they don't notice. I've only recently
looked into a bit of statistics of the effects, but I've pretty much
always noticed the difference.

On Tue, 30 Jan 2024 07:40:32 +0530, Madhu wrote:

> ... my aged eyes (brought up on computer modern) ...

My condolences.

On Tue, 30 Jan 2024 00:37:02 -0300
Julieta Shem <jshem@yaxenu.org> wrote:

> I wish we had a tool like CWEB but for Common Lisp. The stability of
> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
> produces a beautiful document.)

This paper presents LP/lisp, a literate programming tool for Common
Lisp:

Literate Programming in Lisp (LP/Lisp)
http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf

I don't know whether the code is available but it may be possible to
track down the author.

On Tue, 30 Jan 2024 09:15:26 +0100
Paolo Amoroso <info@paoloamoroso.com> wrote:

> http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf
>
> I don't know whether the code is available but it may be possible to
> track down the author.

I meant the machine readable version as the code itself is in the paper.

Julieta Shem <jshem@yaxenu.org> writes:

> Axel Reichert <mail@axel-reichert.de> writes:
>
>> https://llthw.common-lisp.dev/
>
> It's an in-progress draft. It's looking pretty good.

Yes, but so far (as I have found out by now) it has not been "completed"
beyond, say, "Numbers and Math".

> Are you writing a program? I think that's super important. Do things
> from beginning to the end.

Yes, and I agree. I try to refine my code when I learn fundamentally new
(to me) or interesting techniques. My goal is to end up with a DSL-like
code core, but that is still a long way to go.

> I'm very fond of literate programming

[...]

> I wish we had a tool like CWEB but for Common Lisp. The stability of
> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
> produces a beautiful document.)

Have you tried org-mode and org-babel in Emacs? Should be a nice
combination.

Best regards

Axel

On Tue, 30 Jan 2024 09:15:26 +0100, Paolo Amoroso wrote:

> This paper presents LP/lisp, a literate programming tool for Common
> Lisp:

Every time I hear “literate programming” nowadays, I think “why not use a
Jupyter notebook”?

On 2024-01-30, Paolo Amoroso wrote:

> On Tue, 30 Jan 2024 00:37:02 -0300
> Julieta Shem <jshem@yaxenu.org> wrote:
>
>> I wish we had a tool like CWEB but for Common Lisp. The stability of
>> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
>> produces a beautiful document.)
>
> This paper presents LP/lisp, a literate programming tool for Common
> Lisp:
>
> Literate Programming in Lisp (LP/Lisp)
> http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf
>
> I don't know whether the code is available but it may be possible to
> track down the author.

Could it be this?

http://mainesail.umcs.maine.edu/MaineSAIL/software/code/lplisp.lisp

(linked from http://mainesail.umcs.maine.edu/MaineSAIL/software/, but
also see http://mainesail.umcs.maine.edu/MaineSAIL/software/code/ for a
directory listing)

(Apologies if this isn't relevant, I was just having a quick glance at
web pages for lplisp, I haven't thoroughly read the PDF or the source
(yet?).)

--
Nuno Silva

Paolo Amoroso <info@paoloamoroso.com> writes:

> On Tue, 30 Jan 2024 00:37:02 -0300
> Julieta Shem <jshem@yaxenu.org> wrote:
>
>> I wish we had a tool like CWEB but for Common Lisp. The stability of
>> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
>> produces a beautiful document.)
>
> This paper presents LP/lisp, a literate programming tool for Common
> Lisp:
>
> Literate Programming in Lisp (LP/Lisp)
> http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf

Thanks! That was an interesting read. Glad to see there's this option.
I'm not sure I'd switch from noweb to lplisp, but I'm going to give it a
try. I'll report here what I find.

(*) On LP/Lisp and noweb

--8<---------------cut here---------------start------------->8---
Literate Programming in Lisp (LP/Lisp)
Roy M. Turner

You may ask, why another literate programming tool? Why not use
something like the excellent noweb package? Well, there are some
problems with using that model of literate programming for interpreted
languages like Lisp. For a compiled language, introducing another
step---translating from the literate programming “source” file to the
language’s source code---is not particularly problematic. However, the
typical Lisp programming model involves incremental development and,
most of all, interactive debugging. So the programmer usually writes the
code, then, when there is a bug, fixes the problem in an Emacs buffer,
evaluates the changed definition, and continues. With something like
noweb, this isn’t really practical. Changes to in the Lisp code don’t
migrate back to the noweb source code, and there are no tools I’m aware
of that support debugging and incremental evaluation directly from the
noweb source.
--8<---------------cut here---------------end--------------->8---

That's quite right. I patiently deal with this. I automate the file
generation with a Makefile, revert the buffer in EMACS and continue the
debugging. When I'm satisfied, I copy the new code to the NOWEB file
and continue.

This is unacceptable when what I'm doing is unimportant. But when I'm
more interested in what I'm doing, I don't mind thinking more before
trying to write the code, so I don't demand such a quick feedback.

However, what I would still like to have is---if the compiler complains
about a certain line number, I would like it to be the line number in
the NOWEB file. We get that with CWEB because of C compiler's
extensions such as #line directives---which seems to have been a pretty
good feature to connect the compiler to external tools. It seems that
noweb's weakness is precisely its design---to stay away from the
compiler so that it can be any language's web. I love it, but...

--8<---------------cut here---------------start------------->8---
We do lose some things, however. For example, unlike noweb, LP/Lisp does
not support splitting chunks of Lisp code and then reassembling them,
for obvious reasons, although as you will see, you can insert LATEX
source in the middle of Lisp functions as comments. And you can reorder
whole chunks of the source file in the typeset output, allowing such
things as introductory sections of the file to be squirreled away at
(e.g.) the end of the file and put at the right place for typesetting.
--8<---------------cut here---------------end--------------->8---

Apparently that isn't too big a loss. I think literate programming's
main idea is to really let us reorder everything arbitrarily, which
lplisp seems to do.

Finally, I believe that noweb's greatest cachet is the layout and the
cross-referencing. I can't say lplisp can't do the same.

"Nuno Silva" <nunojsilva@invalid.invalid> writes:

> On 2024-01-30, Paolo Amoroso wrote:
>
>> On Tue, 30 Jan 2024 00:37:02 -0300
>> Julieta Shem <jshem@yaxenu.org> wrote:
>>
>>> I wish we had a tool like CWEB but for Common Lisp. The stability of
>>> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
>>> produces a beautiful document.)
>>
>> This paper presents LP/lisp, a literate programming tool for Common
>> Lisp:
>>
>> Literate Programming in Lisp (LP/Lisp)
>> http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf
>>
>> I don't know whether the code is available but it may be possible to
>> track down the author.
>
> Could it be this?
>
> http://mainesail.umcs.maine.edu/MaineSAIL/software/code/lplisp.lisp" rel="nofollow" target="_blank">http://mainesail.umcs.maine.edu/MaineSAIL/software/code/lplisp.lisp
>
> (linked from http://mainesail.umcs.maine.edu/MaineSAIL/software/, but
> also see http://mainesail.umcs.maine.edu/MaineSAIL/software/code/ for a
> directory listing)

It seems to be it. Thanks!

Lawrence D'Oliveiro <ldo@nz.invalid> writes:

> On Tue, 30 Jan 2024 09:15:26 +0100, Paolo Amoroso wrote:
>
>> This paper presents LP/lisp, a literate programming tool for Common
>> Lisp:
>
> Every time I hear “literate programming” nowadays, I think “why not use a
> Jupyter notebook”?

My understanding is that these notebooks target interaction. Literate
programming targets presentation.

You might be thinking of literate programming as some kind of code and
documentation together. It's not that. Literate programming means
presentation first. For instance, you must have total freedom to decide
what comes first. You shouldn't have to worry about what the compiler
wants to see first. By striving to present it greatly, mystic forces
act and you do a better job.

It's interesting to notice that Knuth himself says that out of all of
his work on typography, literate programming happens to be the greatest
benefit to him.

In retrospect, I think the greatest benefit to me personally out of
all this work in typography was the idea of literate programming.
I decided to call it literate programming, which is a way of
treating computer programs as literature. A computer program is
something that human beings are supposed to read and you write it
for people to read rather than for a computer to read.

--- Donald Knuth: Literate programming (66/97)
Source: https://youtu.be/bTkXg2LZIMQ?t=13s

His enthusiasm in 1984:

[T]he impact of this new approach on my own style has been
profound, and my excitement has continued unabated for more than two
years. I enjoy the new methodology so much that it is hard for me
to refrain from going back to every program that I've ever written
and recasting it in `literate' form. I find myself unable to resist
working on programming tasks that I would ordinarily have assigned
to student research assistants; and why? Because it seems to me
that at last I'm able to write programs as they should be written.
My programs are not only explained better than ever before; they
also are better programs, because the new methodology encourages me
to do a better job.

--- Donald Knuth, ``Literate programming.''
The Computer Journal 27.2, 1984: páginas 97--111.

On Wed, 31 Jan 2024 19:02:58 -0300, Julieta Shem wrote:

> Lawrence D'Oliveiro <ldo@nz.invalid> writes:
>
>> On Tue, 30 Jan 2024 09:15:26 +0100, Paolo Amoroso wrote:
>>
>>> This paper presents LP/lisp, a literate programming tool for Common
>>> Lisp:
>>
>> Every time I hear “literate programming” nowadays, I think “why not use
>> a Jupyter notebook”?
>
> My understanding is that these notebooks target interaction. Literate
> programming targets presentation.

So is this “presentation” not supposed to be so interactive?

One of the things that helps people understand code is being able to mess
with it.

Lawrence D'Oliveiro <ldo@nz.invalid> writes:

> On Wed, 31 Jan 2024 19:02:58 -0300, Julieta Shem wrote:
>
>> Lawrence D'Oliveiro <ldo@nz.invalid> writes:
>>
>>> On Tue, 30 Jan 2024 09:15:26 +0100, Paolo Amoroso wrote:
>>>
>>>> This paper presents LP/lisp, a literate programming tool for Common
>>>> Lisp:
>>>
>>> Every time I hear “literate programming” nowadays, I think “why not use
>>> a Jupyter notebook”?
>>
>> My understanding is that these notebooks target interaction. Literate
>> programming targets presentation.
>
> So is this “presentation” not supposed to be so interactive?

One can make it so like these notebooks have, but as far as I know Knuth
never had such thing in mind. Knuth's idea is that a program should be
literary work---it should be able to win a Pulitzer prize.

> One of the things that helps people understand code is being able to mess
> with it.

Sure thing. Long live the REPL. But literate programming was never
about that---at least not originally. I think the emphasis is on
presentation. A compiler forces the programmer to a certain order in
the code. The idea in literate programming is that the compiler is one
consumer and human readers are another. Programmers should be free to
write the program in whatever order they find best; there should be no
difficulty in that.

After we introduce and explain something about the program, that's
perhaps the right moment to show the reader the code.

``The correct way to explain a complex thing is to break it into parts
and then explain each part; and things should be explained twice
(formally and informally). These two principles lead naturally to
programs made up of modules that begin with text (informal
explanation) and finish with Pascal (formal explanation).''
-- Donald E. Knuth, Tracy Larrabee, and Paul M. Roberts, 1987.
``Mathematical Writing'', lecture notes, october 19th, section 10,
CS 209, Stanford University.

The presentation should be free of any bureaucracy that might hurt the
reader's attention such as error checking. With a literate programming
tool, you can freely separate chunks of the code even if such separation
makes no sense to the compiler---the compiler will see the chunks
together after the literate programming tool /tangles/ all the chunks.
(Of course, the writer must specify what that order is.)

On 2024-02-01, Julieta Shem <jshem@yaxenu.org> wrote:
> One can make it so like these notebooks have, but as far as I know Knuth
> never had such thing in mind. Knuth's idea is that a program should be
> literary work---it should be able to win a Pulitzer prize.

Unfortunately, Knuth's implementation consists of sheer crockery: a
crude macro system which pulls a program together from named fragments,
which chop the program text along arbitrary boundaries.

Knuth's system is merely useless, but would be actively harmful in the
context of software engineering in an organization in which many people
work on a program. Or even just two or three people.

(That's a situation that, I think, Knuth avoided all his life and
basically knows nothing about first hand.)

--
TXR Programming Language: http://nongnu.org/txr
Cygnal: Cygwin Native Application Library: http://kylheku.com/cygnal
Mastodon: @Kazinator@mstdn.ca

Kaz Kylheku <433-929-6894@kylheku.com> writes:

> On 2024-02-01, Julieta Shem <jshem@yaxenu.org> wrote:
>> One can make it so like these notebooks have, but as far as I know Knuth
>> never had such thing in mind. Knuth's idea is that a program should be
>> literary work---it should be able to win a Pulitzer prize.
>
> Unfortunately, Knuth's implementation consists of sheer crockery: a
> crude macro system which pulls a program together from named
> fragments, which chop the program text along arbitrary boundaries.
>
> Knuth's system is merely useless, but would be actively harmful in the
> context of software engineering in an organization in which many people
> work on a program. Or even just two or three people.

It seems that the world did not enjoy the idea so much, consequently
perhaps the idea did not evolve. If people were really interested in
literate programming, tools would have evolved too.

On Wed, 31 Jan 2024 23:09:31 -0300, Julieta Shem <jshem@yaxenu.org>
wrote:

>Kaz Kylheku <433-929-6894@kylheku.com> writes:
>
>> On 2024-02-01, Julieta Shem <jshem@yaxenu.org> wrote:
>>> One can make it so like these notebooks have, but as far as I know Knuth
>>> never had such thing in mind. Knuth's idea is that a program should be
>>> literary work---it should be able to win a Pulitzer prize.
>>
>> Unfortunately, Knuth's implementation consists of sheer crockery: a
>> crude macro system which pulls a program together from named
>> fragments, which chop the program text along arbitrary boundaries.
>>
>> Knuth's system is merely useless, but would be actively harmful in the
>> context of software engineering in an organization in which many people
>> work on a program. Or even just two or three people.
>
>It seems that the world did not enjoy the idea so much, consequently
>perhaps the idea did not evolve. If people were really interested in
>literate programming, tools would have evolved too.

Scribble[1] supports literate programming. It works in the same way
as Knuth's tools - extracting chunks of code from the document and
stitching them together ... but it is integrated with the programming
environment, so it is a lot easier to use than, e.g., CWEB.

YMMV.

[1] https://docs.racket-lang.org/scribble/index.html

Julieta Shem <jshem@yaxenu.org> writes:
>``The correct way to explain a complex thing is to break it into parts
>and then explain each part;
....
>-- Donald E. Knuth, Tracy Larrabee, and Paul M. Roberts, 1987.

|To my taste the main characteristic of intelligent thinking
|is that one is willing and able to study in depth an aspect
|of one's subject matter in isolation, for the sake of its own
|consistency, all the time knowing that one is occupying with
|only one of the aspects.
E. W. DIJKSTRA

|The key to understanding complicated things is to know what
|not to look at and what not compute and what not to think.
GERALD JAY SUSSMAN

George Neuner <gneuner2@comcast.net> writes:

> On Wed, 31 Jan 2024 23:09:31 -0300, Julieta Shem <jshem@yaxenu.org>
> wrote:
>
>>Kaz Kylheku <433-929-6894@kylheku.com> writes:
>>
>>> On 2024-02-01, Julieta Shem <jshem@yaxenu.org> wrote:
>>>> One can make it so like these notebooks have, but as far as I know Knuth
>>>> never had such thing in mind. Knuth's idea is that a program should be
>>>> literary work---it should be able to win a Pulitzer prize.
>>>
>>> Unfortunately, Knuth's implementation consists of sheer crockery: a
>>> crude macro system which pulls a program together from named
>>> fragments, which chop the program text along arbitrary boundaries.
>>>
>>> Knuth's system is merely useless, but would be actively harmful in the
>>> context of software engineering in an organization in which many people
>>> work on a program. Or even just two or three people.
>>
>>It seems that the world did not enjoy the idea so much, consequently
>>perhaps the idea did not evolve. If people were really interested in
>>literate programming, tools would have evolved too.
>
> Scribble[1] supports literate programming. It works in the same way
> as Knuth's tools - extracting chunks of code from the document and
> stitching them together ... but it is integrated with the programming
> environment, so it is a lot easier to use than, e.g., CWEB.

I suppose you don't mean easier for writing C. I don't think Scribble
would be integrated with the C compiler as CWEB is. But I do think that
Scribble is in general the correct approach to the problem. I would
love to stop and learn how to use it. I would love to stop and build a
LaTeX layout similar to the one NOWEB provides.

Julieta Shem <jshem@yaxenu.org> writes:

> Paolo Amoroso <info@paoloamoroso.com> writes:
>
>> On Tue, 30 Jan 2024 00:37:02 -0300
>> Julieta Shem <jshem@yaxenu.org> wrote:
>>
>>> I wish we had a tool like CWEB but for Common Lisp. The stability of
>>> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
>>> produces a beautiful document.)
>>
>> This paper presents LP/lisp, a literate programming tool for Common
>> Lisp:
>>
>> Literate Programming in Lisp (LP/Lisp)
>> http://mainesail.umcs.maine.edu/MaineSAIL/publications/papers/2010/lplisp-tr.pdf
>
> Thanks! That was an interesting read. Glad to see there's this option.
> I'm not sure I'd switch from noweb to lplisp, but I'm going to give it a
> try. I'll report here what I find.
>
> (*) On LP/Lisp and noweb
>
> Literate Programming in Lisp (LP/Lisp)
> Roy M. Turner
>
> --8<---------------cut here---------------start------------->8---
> You may ask, why another literate programming tool? Why not use
> something like the excellent noweb package? Well, there are some
> problems with using that model of literate programming for interpreted
> languages like Lisp. For a compiled language, introducing another
> step---translating from the literate programming “source” file to the
> language’s source code---is not particularly problematic. However, the
> typical Lisp programming model involves incremental development and,
> most of all, interactive debugging. So the programmer usually writes the
> code, then, when there is a bug, fixes the problem in an Emacs buffer,
> evaluates the changed definition, and continues. With something like
> noweb, this isn’t really practical. Changes to in the Lisp code don’t
> migrate back to the noweb source code, and there are no tools I’m aware
> of that support debugging and incremental evaluation directly from the
> noweb source.
> --8<---------------cut here---------------end--------------->8---
>
> That's quite right. I patiently deal with this. I automate the file
> generation with a Makefile, revert the buffer in EMACS and continue the
> debugging. When I'm satisfied, I copy the new code to the NOWEB file
> and continue.

I experimented a bit and found the following nice scheme for Lisp and
NOWEB. For dealing with the REPL, I'm using noweb-mode in the GNU
EMACS. When the point enters a chunk of code, lisp-mode is activated.
When it leaves the chunk, noweb-mode reactivates latex-mode. To specify
that chunks should be in lisp-mode, I say

% -*- noweb-default-code-mode: lisp-mode; -*-

at the top of my source code in noweb. This way I get syntax
highlighting, paredit-mode and I'm able to talk to the SLIME REPL
straight from the code chunk. So, for Lisp specifically, the
line-number lack of integration between compiler and noweb file isn't
quite a problem.

For the generation of the LaTeX document, I'm using a program that
monitors changes in a file and then runs a command. When the source
code in noweb changes, I ask make to reproduce the PDF. With a PDF
viewer that also monitors the document on disk, the changes are
reflected automatically---feels like WYSIWYG software.

In summary, the ritual is---open an ESHELL and say ``make livedoc'',
then bury that buffer and work on source.nw, interacting directly with
the SLIME REPL (and having the PDF always up to date). When I want to
see the whole program built, I say ``make exe'' on another ESHELL.

For monitoring a file, I'm using

https://github.com/sjl/peat

Axel Reichert <mail@axel-reichert.de> writes:

[...]

>> I wish we had a tool like CWEB but for Common Lisp. The stability of
>> Common Lisp seems promising. (I use Norman Ramsey's noweb. It
>> produces a beautiful document.)
>
> Have you tried org-mode and org-babel in Emacs? Should be a nice
> combination.

I use org-mode for quick notes and sometimes real-world presentations.
But org-babel I never used. For me to stop using NOWEB I'd need a tool
that produces a beautiful document like NOWEB does. Totally doable for
someone who knows the literate programming tool very well and also
LaTeX---not me.

On Fri, 02 Feb 2024 12:16:33 -0300, Julieta Shem wrote:

> Totally doable for someone who knows the literate programming tool very
> well and also LaTeX---not me.

I could never get to grips with the TEX family of tools.

troff/groff, on the other hand, turned out to be quite easy to get to
grips with. I can use it to produce man pages, and also render those same
pages in typeset quality with a simple, short command.

Lawrence D'Oliveiro <ldo@nz.invalid> writes:

> On Fri, 02 Feb 2024 12:16:33 -0300, Julieta Shem wrote:
>
>> Totally doable for someone who knows the literate programming tool very
>> well and also LaTeX---not me.
>
> I could never get to grips with the TEX family of tools.
>
> troff/groff, on the other hand, turned out to be quite easy to get to
> grips with. I can use it to produce man pages, and also render those same
> pages in typeset quality with a simple, short command.

This is getting off-topic---I wonder if we should continue here. I do
find TeX very difficult to understand. I wonder if the reason is
macros. I sometimes get errors that I have absolutely no idea what
they're about. I've bisected the document at times just to find where
the problem is. I've also seen situations in which there was no problem
in the document, but I had to remove auxiliary files and recompile.

I don't make any conclusions. I would like it to understand deeply
because I would like the end result. If I understood it deeply, I think
I would have tried to copy the NOWEB design into Scribble, say. But
what I should do? Should I read the TeXbook? I've read the LaTeX book,
whatever it's called, but it didn't seem to teach me how the system
works---it's just how to use the classes, which I know enough to do
write my documents with ease.

Perhaps it just takes hard work of reading the TeXbook and understanding
the primitives of the system, then going out in the world of TeX and
LaTeX packages to understand their creative work. Such hard work,
though, requires time. I never really had such time, but I believe now
I do. I've been investing in Lisp and I'm glad I switched from Racket
to Common Lisp because I'm enjoying it a lot more.

Do you have online examples of these man pages you rendered in typeset
quality?