On Thu, 2018-02-01 at 19:41 +0000, John Gabriele via Digitalmars-d wrote: > […] > It's trivial to put multiple markdown files together into a large > doc, if that's desired. Just put a bunch of .md files together > into the same directory and run your markdown processor on them. > They can link to each other in the [normal > way](./other-file.html#normal-way).
Auto generation of contents pages, and indexes? Tables? Nested lists? The CommonMark crib sheet says nothing. AsciiDoctor has all of them, though I prefer XeLaTeX. > Markdown provides a simple, practical, modern, and commonly-known > way to get docs written fast and by anyone who wants to pop in > and improve them. There's no easier way to write plain text docs > that look as good. AsciiDoctor. > Sorry, can't recall if I already mentioned this, but D suffers > from a perception that it's "old", or "the language that tried > and failed to replace C++". Something simple like markdown for > its docs sends a clear message that D is modern and knows when to > pivot to new and better ways after the old ways are not serving > it anymore. Markdown is so last decade. Ditto AsciiDoctor. XeLateX so last millenium. The question is choosing the right tool for the job, not pandering to hipster fashionistas. Clearly one reviews new ways and moves to them if that provides a better way forward, but the goal is more important that the technology. There are the autogenerated reference pages. JavaDoc, Doxygen, all have their upside and downside. D has DDOC, is it fit for purpose? Should it be replaced (by Doxygen) or evolved? Maybe Markdown fits here, but without table support you end up hacking stuff. cf. vast tracts of early JavaDoc stuff. For the documents no created by scanning the source code, you want something like Markdown, AsciiDoc, ReStructuredText, XeLaTeX. I think Sphinx/ReStructuredText actually can do both from code generated reference and other documents – it does for many projects as well as Python. I happen to rate AsciiDoc far better than Markdown as a lightweight text markup, though actually I prefer XeLaTeX. However, simply trading emails about "I think X is best" is not going to get anyone anywhere. Only when someone actually does something is there movement forward. So unless some actually creates a demo of the (Markdown|AsciiDoctor|XeLaTeX) system nothing will change. Of course if Walter and/or Andrei don't like it, it will be wasted effort. > Incidentally, choosing an established standard like markdown is a > good way to short-circuit bikeshedding about "it what ways should > ddoc be updated to include some markdown features?". Just pick > standard CommonMark markdown and you're done. s/Markdown/AsciiDoctor/g > One last note and I'll (try to!) stop: it's difficult enough to > get good writers to help with docs. Much more so when they've got > to first learn your own language-specific markup (which is only > useful with your project). This is a good and strong point, that has been raised in many other places I frequent. One group changed from their custom DocBook/XML to Sphinx because someone did stuff rather than talking about it. AsciiDoctor would clearly have been a better solution, evolution using the DocBook toolchain, but they went for the revolution because people put effort into it to make the decision happen. The core point is how are you going to get pull requests from people to update and evolve the documentation. An esoteric, indeed unique, markup language is clearly the wrong choice. -- Russel. =========================================== Dr Russel Winder t: +44 20 7585 2200 41 Buckmaster Road m: +44 7770 465 077 London SW11 1EN, UK w: www.russel.org.uk
signature.asc
Description: This is a digitally signed message part