Happy birthday to me. To celebrate, I'm releasing a simple Literate Programming
tutorial based on the classic C "hello, world" program.

https://metaed.com/papers/hello/

This is in the nature of a draft. Suggestions are welcome.

Edward McGuire <metaed@metaed.com> writes:

> Happy birthday to me.

Happy birthday!

> To celebrate, I'm releasing a simple Literate Programming tutorial
> based on the classic C "hello, world" program.
>
> https://metaed.com/papers/hello/

NICE! Welcome to the literate programming world. I think you made the
best choice---NOWEB by Norman Ramsey. It's not that other tools are
inferior, but that Ramsey's LaTeX layout happens to be the most
beautiful one.

> This is in the nature of a draft. Suggestions are welcome.

I liked the introduction. However, notice that by calling your chunks
as holons, you're eclipsing the name ``chunk'' which seems to be the
understand one. Something to think about.

Also, you begin your program with hello.c---external declarations and
procedure definitions. It's questionable whether this is the best
presentation. This chunk is what the /compiler/ expects to see:
declarations first, then definitions. Is it what humans should see?
Why don't we go straight to the essence of the program and leave the
compiler preferred order for last? You observed that in the NOWEB
section:

--8<-------------------------------------------------------->8---
And they let you organize the sections of the work in the order that
makes sense to the future programmer, instead of in the order that the
programming language constrains you to.
--8<-------------------------------------------------------->8---

So I would say that perhaps the first chunk should be /hello main body/
because that is precisely what we expect from a hello-world.

I see you explain the NOWEB terminology. I wonder if Knuth was the one
who started with the term /chunk/ as well. If so, then I'd advise
against /holon/.

Thanks for keeping this newsgroup alive.

(*) Cosmetics

Your section 2 could use some cosmetic treatment. For instance, the
source code shown should perhaps be separated by a blank line from the
paragraph above.

Your section 5 could be reduced so as to get the section title in a
single line. Perhaps ``a complete program embodied in one file''.

(*) Makefile

More often than not, users don't have NOWEB installed, so they wouldn't
be able to do anything with your program but read it. So I usually
leave the Makefile outside of NOWEB as a stand-alone file and I include
in the package the C source files so that users don't need to have NOWEB
to just compile and run the program.

We could still put the Makefile inside of NOWEB and get it out before
packaging, but I actually like to use the Makefile to detect when make
itself should invoke noweb. In other words, I can prefer to have make
as the main driver.

On 2024-11-01, Wolfgang Agnes <wagnes@jemoni.to> wrote:
> Welcome to the literate programming world.

Thank you, especially for the really thoughtful response. This kind of
constructive reply is exactly what I wanted.

> perhaps the first chunk should be /hello main body/ because that is precisely
> what we expect from a hello-world.

I agree. Part of what's fun about this design process is, instead of starting
literally at the top and sectioning down, or at the bottom and chunking up, you
can start at the middle, then both section down and chunk up. Knuth discovered
this was true for him also, and mentions it in the "Literate Programming" paper.
The tutorial should be reordered to demonstrate that.

> by calling your chunks as holons, you're eclipsing the name ``chunk'' which
> seems to be the understand one. Something to think about.
> [...]
> I see you explain the NOWEB terminology. I wonder if Knuth was the one
> who started with the term /chunk/ as well. If so, then I'd advise
> against /holon/.

My choice of _holon_ reflects my intention that the tutorial be, or become, less
about a particular tool, and more about what literate programming _is_, while
still showing a working example.

Knuth uses neither _chunk_ nor _holon_. In the "Literate Programming" paper, he
acknowledges de Marneffe's Holon Programming Language as the primary influence
on the design of WEB, but does not follow de Marneffe's terminology. In the WEB
manual he uses _module_, and in CWEB he uses _section_. Ramsey (noweb) uses
_chunk_. Briggs (nuweb) uses _scrap_ and _macro_. In short, there is no
agreed-on term.

The term _holon_ captures good design better than the others. It describes a
relatively independent "organic" or "granular" unit of code, whose form and
purpose is easily graspable by the reader, and whose boundaries easily allow for
sectioning down and chunking up, validation, testing, refactoring, etc. And
that's what a good literate programmer aims for.

> (*) Cosmetics

Again thank you.

> More often than not, users don't have NOWEB installed, so they wouldn't
> be able to do anything with your program but read it.

I need to add an appendix, that shows how a person could easily get Noweb
running and actually execute the tutorial code.

Cheers!
Edward

Edward McGuire <metaed@metaed.com> writes:

> On 2024-11-01, Wolfgang Agnes <wagnes@jemoni.to> wrote:
>> Welcome to the literate programming world.
>
> Thank you, especially for the really thoughtful response. This kind of
> constructive reply is exactly what I wanted.

You're so welcome. Glad I could be of some help.

>> perhaps the first chunk should be /hello main body/ because that is precisely
>> what we expect from a hello-world.
>
> I agree. Part of what's fun about this design process is, instead of starting
> literally at the top and sectioning down, or at the bottom and chunking up, you
> can start at the middle, then both section down and chunk up. Knuth discovered
> this was true for him also, and mentions it in the "Literate Programming" paper.

Nice. That's also why I like it so much. I had never noticed how the
compiler order is such a prison. Knuth liberated us from that. It
makes a lot of difference. It brought a pretty good deal of the joy of
programming back to me. (Lisp brought another half of that joy.)

> The tutorial should be reordered to demonstrate that.

Okay.

>> by calling your chunks as holons, you're eclipsing the name ``chunk'' which
>> seems to be the [standard] one. Something to think about.
>> [...]
>> I see you explain the NOWEB terminology. I wonder if Knuth was the one
>> who started with the term /chunk/ as well. If so, then I'd advise
>> against /holon/.
>
> My choice of _holon_ reflects my intention that the tutorial be, or become, less
> about a particular tool, and more about what literate programming _is_, while
> still showing a working example.

Interesting. I agree with that. I should've also said that I really
enjoyed the term, though if everyone *were* using a single one---say,
``chunk''---, I'd stick to it, but you showed that's not the case.

> Knuth uses neither _chunk_ nor _holon_. In the "Literate Programming" paper, he
> acknowledges de Marneffe's Holon Programming Language as the primary influence
> on the design of WEB, but does not follow de Marneffe's terminology. In the WEB
> manual he uses _module_, and in CWEB he uses _section_. Ramsey (noweb) uses
> _chunk_. Briggs (nuweb) uses _scrap_ and _macro_. In short, there is no
> agreed-on term.

Thanks very much for all the references!

> The term _holon_ captures good design better than the others. It describes a
> relatively independent "organic" or "granular" unit of code, whose form and
> purpose is easily graspable by the reader, and whose boundaries easily allow for
> sectioning down and chunking up, validation, testing, refactoring, etc. And
> that's what a good literate programmer aims for.

Totally agree. Maybe we all should use ``holon'' from now on.

>> More often than not, users don't have NOWEB installed, so they wouldn't
>> be able to do anything with your program but read it.
>
> I need to add an appendix, that shows how a person could easily get Noweb
> running and actually execute the tutorial code.

That's a nice idea. NOWEB is such a stable software, your tutorial
would likely last a good deal of time.