Thanks, Urs: I have read “Extending LilyPond”, it did give me some idea of some of what I need to know. But the need was still there. I find your “Scheme Book” answers this need. Thank you for all your effort. Wish I was smart enough to help.
Thank You, ƒg On Sat, Feb 1, 2020 at 3:47 AM Urs Liska <[email protected]> wrote: > 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 > > > > >
