On Thursday, 1 February 2018 at 11:06:09 UTC, Russel Winder wrote:
On Wed, 2018-01-31 at 16:13 +0000, John Gabriele via
Digitalmars-d wrote:
[…]
this older language from times past, before C++11, and using
ddoc
for docs instead of markdown contributes to this perception.
Let
me know if you'd like help in translating D website and doc
pages
from ddoc to markdown.
I am sure Markdown is find for single page HTML pages, but for
bigger documents that need to render to HTML or PDF (or other
e-publishing formats) surely AsciiDoctor and XeLaTeX are the
only choices.
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).
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.
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.
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.
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).
