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

[John Gabriele]

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).