Re: Scheme Book

[Urs Liska]

Am Freitag, den 31.01.2020, 16:53 -0800 schrieb Aaron Hill:
> On 2020-01-31 11:57 am, Urs Liska wrote:
> > https://scheme-book.ursliska.de
> 
> My apologies for hijacking this thread.

Don't worry, seems like a useful thing.

> 
> Two things:
> 
> 1)  Is it possible to auto-generate (ideal) or manually maintain
> (not 
> ideal) a page linked from the contributing section regarding the 
> sections of the book that are incomplete?  
> For instance, "list 
> recursion" has no content currently.  But you would not know that
> unless 
> you drill down into that section, which in this new styling requires
> a 
> fair number of mouse clicks.  I sometimes have spare cycles where I 
> could help flesh out this book, but at the face of it, I would not 
> immediately know where to look.  A one-page index listing where work
> is 
> needed would be great.

The previous system, GitBook, treated missing files in a way similar to
a Wiki, by creating non-clickable entries in the TOC. MkDocs doesn't
seem to have this, missing input files will cause 404 errors. As a
lesser evil I decided to put in empty files - which will at least auto-
generate the heading for the page, and an edit link so someone could
directly jump to Github to enter something.

Of course that's suboptimal, for the reasons you describe.
I think a good solution would be a dedicated TOC page serving two
purposes at once: giving the overview and direct navigation asked for
by Freeman in the first place, and adding state information to each
page's entry.

First I thought doing so automatically would be deficient because that
could only catch missing or actually empty files (which would miss a
file with a short description of the missing/intended content).
However, I *think* it is possible to use metadata for that. MkDocs has
some functionality to process metadata in itself, which could be used
by a plugin, which is something I haven't investigated yet. But since
the book has to be built by a build script anyway it would be easy to
hook in a step of generating the TOC/state page using content from the
metadata. So not only empty files could be properly flagged but also
files that have a state flag in the metadata.

This will need some time, which could drastically be reduced by someone
stepping in and helping me with the investigation.

> 
> 
> 2)  Since some pages are entirely blank, it can be difficult to 
> contribute as title alone may not fully indicate the intended purpose
> of 
> a section.  Using the example above, should "list recursion" be
> talking 
> about nesting lists within lists and common strategies for this 
> structure (c.f. member vs member*) or is there something else to 
> discuss?  Including a short one-liner description of what to expect 
> would be helpful.

This can certainly be integrated in the above appraoch. A plugin can
surely extract such a comment from the metadata and write it on the
page, and a TOC generator can also add this as a comment to a TOC
entry.

However, one thing to note is that "what is missing" is not necessarily
equivalent to "what Urs at one point added as a TOC entry". The
structure I outlined at some point is a draft, and looking at the
contents again after a few years tells me there's a lot that could be
improved.

That wants to say: If someone finds the time and energy to add to that
book it's not relevant if that addition fits to the existing empty
pages, it can be something totally different.

The aim of this book has always been an introduction, giving interested
users the chance to get over the initial threshold of perceiving Scheme
as black magic. And while I think the level of detail and the pace of
explanation is generally quite successful in this regard, I now think
the overall structure, i.e. the order of topics the reader is exposed
to, could be improved.

I hope I'll find the time to do that, page by page, and while reviewing
I will purge the "I" perspective to make it more suitable as a
community-driven resource.

The "task" of potential contributors is not to fill in the blanks I
have created in the outline but to add or improve arbitrary topics, and
suggestions regarding the improvement of the outline are equally
welcome.

Best
Urs

> 
> 
> -- Aaron Hill
>