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 >
