Best practices: add table of contents
I'm not sure what to think of this MR. If the document were largely stable, then it'd be great. On the other hand, this looks like a lot of work to manually keep the TOC in sync as you modify the document. Some markdown processors recognize the magic [TOC] markup, but unhappily gitlab is not one of them.
Did you do that by hand (including with Emacs keyboard macros) or do you have a preprocessor do it for you (including Emacs functions)?
Maybe we should move this document to texinfo, PLT Scribble or Exscribe?
texinfo is already part of our toolchain, but requires just as much manual TOC maintenance as this MR introduces for best_practices.md
PLT Scribble works great and can produce .pdf as well as .html, and Robert and I have some experience with it writing some ASDF articles. But it would increase the tooling surface of ASDF, and I understand that Robert hates that, with some valid arguments.
My CL tool Exscribe could be used too. It can only realistically dump .html output, but that's all we need and it supports TOC. And since it could completely integrate with the external common-lisp dependencies we already use for testing, it would not increase the number of installation steps for building ASDF.
I did this with the standard Emacs tools; nothing fancy.
While it is a decent system, using Scribble with ASDF, creates additional friction, among other things. Exscribe is fine, too, and it’s in CL.
Markdown is not programmable nor extensible, however, it has withstood the test of time, or so I thought. It can be read by any program and human. The simplicity and ease of use is what makes Markdown useful. There are compromises here, of course.
Here are some questions with regards to this:
- How will the documentation be viewed in the future?
- Will it have the proper tools to process them?
- At what point do we sacrifice power in order to gain portability?
- Will adding another incompatible system actually make things better? What is better?
- If we use another format, how will it be handled by online document viewers? For document system X, will there be a common agreement between sites like GitLab or GitHub to use or create a system that will correctly display that format on browsers.
Even if this document triples in size, I honestly think that it is still managaeable.
Since the existing manual is in TeXinfo, I'm inclined to suggest we pull this in there, as well.
Great! I also made some last-minute changes:
- I reduced the number of
_s in the anchor tags, to one, because browsers do not like more than one instance of it.
- I made the headings more consistent with the other Markdown files—the use of
-,s instead of
#s for level 1 and 2 headings, respectively.
- I reduced the number of
OK, I think it would be a good idea to move this into the manual, but I don't see that means we need to have the current draft be any less good than necessary. So I will merge this MR.
mergedToggle commit list