Quora: Why hasn't D started to replace C++?

[Russel Winder]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20180202/b035b5cd/attachment.sig>