On Friday, 2 February 2018 at 14:25:53 UTC, Russel Winder wrote:
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.
CommonMark is the less featureful common denominator markdown.
For myself, to get TOC's and tables I use
[Pandoc](http://pandoc.org/).
But I see your point. For larger complete documents like books,
you want tools that can handle all the things that books require.
But, afaik, we're talking about 2 specific needs here:
1. documenting code in a way that gets extracted and rendered
into html
2. dlang.org doc webpages
with a secret 3rd need: you want contributors to be willing to
write and update these.
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.
Everyone already knows and uses Markdown. It's so common that it
gets used in plain text forums like this one, sometimes without
folks even knowing they're using it. For short plain text docs
that may be converted to html, markdown has won and is the
easiest on-ramp for some writer who has a few minutes and is
willing to write some doc-comments for a function (or a confusing
passage in the docs) that they just stumbled over.
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.
I wouldn't say markdown is last decade (not sure if you're
joking). More like it's simply become part of the background at
this point since it's so commonly used.
But I agree about not pandering to fashion. The goal is to make
it as easy as possible to document your code and have tools
render it as html for users to make use of, as well as making it
easy as possible for potential contributors to jump in and make
edits/improvements. I think markdown is the best way to acheive
that goal.
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.
Pandoc extends CommonMark and has tables, definiton lists, and a
couple of other things worth imitating. Regarding tables, it
supports three styles (again, the default easy-on-the-eyes style,
plus a couple others --- see their docs). See
<http://pandoc.org/MANUAL.html#tables>.
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
AsciiDoctor appears to be tuned for writing long docs like books.
Markdown beats it on looks, convenience, and popularity ---
exactly the things you want to attract folks to writing more
comment docs and web pages.
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.
I don't understand your comment there. I group DDoc, Docbook XML,
DDoc, Texinfo, groff, etc. all in the same esoteric unique markup
languages camp. If I wanted to make a small change to a half-page
doc comment, and it was written in ddoc, I'd be pleased as punch
to convert the two or three paragraphs to markdown first. Someone
might even write a ddoc2md converter. Heck, someone on the pandoc
mailing list might even be willing to knock together a pandoc
input reader for reading ddoc (Pandoc could then be used to
convert ddoc to markdown).
