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

On Friday, 2 February 2018 at 14:30:25 UTC, Russel Winder wrote:
> On Thu, 2018-02-01 at 19:28 +0000, John Gabriele via Digitalmars-d wrote:
>> On Thursday, 1 February 2018 at 03:00:07 UTC, Walter Bright wrote:
>> > On 1/31/2018 5:58 PM, H. S. Teoh wrote:
>> > > cosmetic features.
>> > 
>> > I tough lesson I've learned is that cosmetics matter, a lot. Sometimes much more than substance. There's no getting away from it.
>
> I agree but only if s/Markdown/AsciiDoctor/g
>
>> This is one reason I recommend markdown for docs. Cosmetics is what markdown does best. People *like* looking at it and editing it. It's like typing an email or a forum comment.
>> 
>> Other reasons I recommend it are:
>> 
>>    * everyone already knows it (it's at github, stackoverflow, and
>> reddit),
>> 
>>    * it's fairly easy to write (as easy as possible while still
>> looking good),
>> 
>>    * there's an open spec (CommonMark), and
>> 
>>    * writing new language-specific markup formats appears to be
>> something that's not done anymore. There's javadoc, texinfo,
>> doxygen, docbook, groff --- all very ... *mature* technologies.
>> In modern projects: Rust uses markdown, Python uses reST, Git
>> uses asciidoc --- all general-purpose non- language-specific
>> lightweight markup formats.
>> 
>> The only reason I can think of for *not* using markdown for project docs is if your project is another competing lightweight markup format.
>
> Markdown was created to write a few HTML pages. AsciiDoc (and thus AsciiDoctor) was invented to be a front end to the DocBook/XML toolchain.
>
> Thus Markdown is for a few small very simple webpages, AsciiDoctor is for creating any form of document from a page to a book. They are similar where Markdown has functionality, but AsciiDoctor has so much more, and most people end up finding they want all the extras. XeLaTeX and Sphinx/ReStructuredText are the competition for AsciiDoctor. Markdown is lacking in functionality people will find they need to use.

Note that markdown is a small sharp tool in your toolbox: for writing easily readable (in plain text) docs, easily converted to html. For more than that, tools like [Pandoc](http://pandoc.org):

  * convert markdown to html but also to a bunch of other formats as well, and

  * support extra markdown functionality like tables, definition lists, footnotes, and citations. Don't know how if handles making an index.

Also, note that it's not uncommon to write a short script that stitches together a handful of markdown docs into a website or other larger composite doc. I even wrote one myself: <http://www.unexpected-vortices.com/sw/rippledoc/index.html>. There may be others listed at <https://github.com/jgm/pandoc/wiki/Pandoc-Extras>.

On Tuesday, 30 January 2018 at 20:45:44 UTC, Andrei Alexandrescu wrote:
> https://www.quora.com/Why-hasnt-D-started-to-replace-C++
>
> Andrei

The Betamax Problem

When you introduce something new, how do you know that it is going to be compelling enough for people to move from whatever it is they are doing and use your new thing?

It is not an easy question to answer but in the realm of programming languages it's a very tough question, because people are going to have to learn a whole new language, and its going to come with costs and potentially unquantifiable risks for any company that attempts to shift to that language. So whatever it is you are offering has to be tremendously compelling compared to what is already there.

An important question is what problem set does D solve? It's very hard to sell a language to industry without convincingly answering that question. If you are selling them a 'better' language - that's a tougher sell. If you are selling a solution to a particular problem set - you stand better a chance.

For a manager to consider D as the successor to C++, it doesn't just have to be a better language design than C++, it has to have the best language design of any compiled language and demonstrate the best performance. Is the former really true? Are various language features that have been inherited from C++/Java the best way forward? For instance does D have the best approach to object oriented programming, or templates? Or any important set of features you care to mention? Are there things that C++ does better than D? How straightforward is it to get great performance from D? Is how do you 'tune' your D code for high performance obvious or well documented?

If the answers to any of the above questions is a negative for D, that's a serious problem if what you want to do is replace C++, because C++ is already a solid well know language and the competition from new programming languages is extremely tough, and because its only going to get easier to create programming languages this competition will get tougher.

To finish the Betamax story, when CD came along, people dropped cassette tapes like hot potatoes and DVDs killed VHS stone dead. Does D represent a similar leap from C++?

I'm not saying that D is Betamax. I'm just giving food for thought.

On Wednesday, 7 February 2018 at 21:02:11 UTC, data pulverizer wrote:
> On Tuesday, 30 January 2018 at 20:45:44 UTC, Andrei Alexandrescu wrote:
>> https://www.quora.com/Why-hasnt-D-started-to-replace-C++
>>
>> Andrei
>
> The Betamax Problem

I don't think the analogy holds. With VHS and betamax, you just put in the tape and watch your movie. Most people didn't care very much what the name on the machine said --- both types of machines had the same buttons.

In contrast to that, programmers are very particular about the languages they use (which includes tooling, community, module repos, available books).

> An important question is what problem set does D solve? It's very hard to sell a language to industry without convincingly answering that question. If you are selling them a 'better' language - that's a tougher sell. If you are selling a solution to a particular problem set - you stand better a chance.

My impression is that the object is not necessarily to sell D to industry, but rather to sell it to developers. Developers choose what they want to learn and use at home and in side projects. Then at work some tools here and there get written in it. Then some customer-facing projects. Before you know it, it's been "sold to industry".

I think, as of last year, D has upped its sales (to developers) game:

  * fully open-sourced dmd

  * GDC slated for inclusion into GCC

  * there's been talk of adding some markdown features to ddoc. Cosmetic, yes; sells D well to developers, emphatically yes.

I'm not sure how long dub has been around, but having an easy to use CPAN-alike (online module repo) is HUGE. Dub is great for sales. The better dub and the repo gets, the more attractive D gets.

On Tuesday, 30 January 2018 at 20:45:44 UTC, Andrei Alexandrescu wrote:
> https://www.quora.com/Why-hasnt-D-started-to-replace-C++
>
> Andrei

my modest opinion about this

D currently is a small player, that have an attractive proposition for some

* it is like C++ (that is close to the power of C++) but simpler
* it have some unique advanced feature related to meta programming

D's best hope is to be a bigger player, it is unrealistic to replace c++
Any improvement made to D will help make it a bigger player

And while some D features can be better advertised
(like Design by Contract, DbC is a big deal, and few other languages are know to have it)

I think D need to constantly add features, the idea that D is big enough, or that it needs more idioms rather than features, is in my opinion wrong

D need to constantly add features, because all of it competitions are constantly adding features

As D add features, it may have a breakthrough, at some point

On Wednesday, 7 February 2018 at 21:02:11 UTC, data pulverizer wrote:
> On Tuesday, 30 January 2018 at 20:45:44 UTC, Andrei Alexandrescu wrote:
>> https://www.quora.com/Why-hasnt-D-started-to-replace-C++
>>
>> Andrei
>
> The Betamax Problem
>
> When you introduce something new, how do you know that it is going to be compelling enough for people to move from whatever it is they are doing and use your new thing?
>
> It is not an easy question to answer but in the realm of programming languages it's a very tough question, because people are going to have to learn a whole new language, and its going to come with costs and potentially unquantifiable risks for any company that attempts to shift to that language. So whatever it is you are offering has to be tremendously compelling compared to what is already there.

A great deal of confusion in the world arises from failing to make distinctions between things that appear to be the same but really aren't when you look closely.

Also, in about 1870 odd there was a revolution in economic thought that took place more or less simultaneously in Vienna, Lausanne and Cambridge.  The Marginal Revolution had yet to be fully digested in the way people think about social phenomena.

My director of studies at Cambridge, Lord Eatwell, Labour spokesman in the House of Lords,  was known for his devotion to the work of Pierro Sraffa, a man known principally for a rather hostile book review of a book by Hayek and a rather slim book of his own, Production of Commodities by Means of Commodities, a book that tried to draw insights about the economy from a model with two goods, corn and gold.

And I think considering firms as homogeneous, with the same cultural values  and facing the same situation will be about as insightful as I think Sraffa's work ended up being - not very.

Life is risk.  It's risky to get out of bed in the morning, but it's also risky not to get out of bed.  And it's true that an agent acting on behalf of someone else - ie a manager who has no stake in the business - will often think about things first in terms of not taking a decision that might lead him to be blamed.  But most firms are not large enterprises, and in the US small and medium sized firms over time create more than 100% of job growth, last I checked.  And a manager who is also at least to some extent a principal ie an owner in the business knows that to be conservative in a time of change is not necessarily prudent, and it may well also not be the profit maximising choice.

As someone who is both a manager and a part owner I disagree that a new technology choice needs to be overwhelmingly compelling to be considered.  And I don't get paid to make decisions about things that are easily quantifiable - what for you need me for if the numbers are straightforward?

The reality is that firms are very different, in a dynamic industry even within the same sector they are different.  And at any one time there are a bunch of people close to trying D or more.  You don't need to persuade everyone to grow.  You just need to persuade a few more people to tip over the margin.  And there are often plenty of safe ways to take risks.  You just need to make sure you have a plan B.  Listen to Manu's talk for a real example of what I mean.  And note that he said Finns are very conservative.

> An important question is what problem set does D solve? It's very hard to sell a language to industry without convincingly answering that question. If you are selling them a 'better' language - that's a tougher sell. If you are selling a solution to a particular problem set - you stand better a chance.

But really who is selling D to anyone? We are very far from that stage right now.  Did someone sell D to Microsoft COM team, Remedy or to Weka? Nope.  People who had earned the authority to decide became aware of the language end decided to use it.  And they did so because for them it solved their particular problems better then anything else they could think of.

> For a manager to consider D as the successor to C++, it doesn't just have to be a better language design than C++, it has to have the best language design of any compiled language and demonstrate the best performance.

Why?  Best in what way? Best for whom and for what kind of problems?

I completely disagree with that.   It needs just to be better in the situation then the conceivable alternatives.  And situations and challenges are really quite different between firms.

 Is the former really true?
> Are various language features that have been inherited from C++/Java the best way forward? For instance does D have the best approach to object oriented programming, or templates? Or any important set of features you care to mention? Are there things that C++ does better than D? How straightforward is it to get great performance from D? Is how do you 'tune' your D code for high performance obvious or well documented?
>
> If the answers to any of the above questions is a negative for D, that's a serious problem if what you want to do is replace C++, because C++ is already a solid well know language and the competition from new programming languages is extremely tough, and because its only going to get easier to create programming languages this competition will get tougher.
>
> To finish the Betamax story, when CD came along, people dropped cassette tapes like hot potatoes and DVDs killed VHS stone dead. Does D represent a similar leap from C++?
>
> I'm not saying that D is Betamax. I'm just giving food for thought.

You can turn your scepticism on anything, and the value of the exercise really depends on the results.  But doubt on its own isn't necessarily a good guide to the future in my experience.

In particular with D because the benefit doesn't I think come from any single feature but from the totality of the gestalt of what it's like to work in D compared to other languages.

I think that if you want to understand the adoption of new technologies then Clayton Christensen's Innovators Dilemma has considerable insight.  Up to a point Crossing the Chasm and companion books too.  I think by Moore.

On Thursday, 8 February 2018 at 00:09:47 UTC, Ali wrote:
> On Tuesday, 30 January 2018 at 20:45:44 UTC, Andrei Alexandrescu wrote:
>> https://www.quora.com/Why-hasnt-D-started-to-replace-C++
>>
>> Andrei
>
> my modest opinion about this
>
> D currently is a small player, that have an attractive proposition for some
>
> * it is like C++ (that is close to the power of C++) but simpler
> * it have some unique advanced feature related to meta programming
>
> D's best hope is to be a bigger player, it is unrealistic to replace c++
> Any improvement made to D will help make it a bigger player
>
> And while some D features can be better advertised
> (like Design by Contract, DbC is a big deal, and few other languages are know to have it)
>
> I think D need to constantly add features, the idea that D is big enough, or that it needs more idioms rather than features, is in my opinion wrong
>
> D need to constantly add features, because all of it competitions are constantly adding features
>
> As D add features, it may have a breakthrough, at some point

Maybe features help, but there's also just a natural process of maturation that we don't notice because it happens slowly.

In 2014 when I started using D it wasn't unusual for the compilers to segfault.  And since I didn't know D, or even modern compilers, their flags etc (beyond a bit of work in visual studio in the late 90s, I mostly learnt to program C on 8 bit CP/M, which was a bit different then),it was quite a confusing experience.  I couldn't have recommended D to somebody else then.

The documentation also was not very accessible to people who didn't think formally and were used to Python material.  I tried working with one chap, a trader who knew a bit of python and he was absolutely terrified of the D documentation.

The situation there is also rather better today.

Then again, how can I trust the compiler.  It means something that Liran at Weka said they haven't had any data corruption bugs, because data on they scale tends to find problems and bring them to the fore.

From what I have seen, big changes, much more than is generally appreciated are often not a consequence only of one big causal factor, but lots of little things aligned and coming together.

However if you want a big thing just consider growth in data set sizes and storage capacity and related that to trends in processor power and memory speed.

Guido says python is fast enough because you are bottlenecked on I/O and network.  But in my office I have a test infiniband network where the 40 Gbps switch cost about 600 quid (that's old technology now).  NVMe drives do pretty decent throughput.  Json parsing is not the cleverest thing one can do with data but how does that compare with the throughput from just a couple of nvme drives?

And according to the ACM a fundamental assumption that held true since the dawn of computing is in the process of being overturned.   With storage class memory and newer network technology (there's a road map to get to 1Tbps) the bottleneck from here isnt storage or network - it's CPU.

I guess that won't hurt the adoption of D.  Not tomorrow, but slowly over time.

On Wednesday, 7 February 2018 at 22:31:58 UTC, John Gabriele wrote:
> I'm not sure how long dub has been around, but having an easy to use CPAN-alike (online module repo) is HUGE. Dub is great for sales. The better dub and the repo gets, the more attractive D gets.

I completely agree that the availability of libraries is a huge factor.  I almost gave up on D because of the limited amount of 3rd party libs.
I think just improving the search function would help.
http://code.dlang.org/search?q=keccak
Comes up with nothing, so I started porting a sha3/keccak lib from C to D.  Then someone pointed out botan has sha3 support, which can be found if you search for "crypto"
http://code.dlang.org/search?q=crypto

On Thursday, 8 February 2018 at 15:29:08 UTC, Ralph Doncaster wrote:
> On Wednesday, 7 February 2018 at 22:31:58 UTC, John Gabriele wrote:
>> I'm not sure how long dub has been around, but having an easy to use CPAN-alike (online module repo) is HUGE. Dub is great for sales. The better dub and the repo gets, the more attractive D gets.
>
> I completely agree that the availability of libraries is a huge factor.  I almost gave up on D because of the limited amount of 3rd party libs.
> I think just improving the search function would help.
> http://code.dlang.org/search?q=keccak
> Comes up with nothing, so I started porting a sha3/keccak lib from C to D.  Then someone pointed out botan has sha3 support, which can be found if you search for "crypto"
> http://code.dlang.org/search?q=crypto
The opposite situation you may see, when searching for mysql:

You will get 9 packages listed. Which should I take?
If you click on everyone, you will realize, that some of them are forks of other.
And the version number of mysql-native at the top, just recently increased so strong, that it makes a different.
The minimum additional information which should be listed - I think - is the number of downloads and GitHub stars.

I know that there is work behind the scene to find some kind of weighted sort, this would be cool, but just displaying the GitHub voting might help a lot.

On Thursday, 8 February 2018 at 15:29:08 UTC, Ralph Doncaster wrote:
> On Wednesday, 7 February 2018 at 22:31:58 UTC, John Gabriele wrote:
>> I'm not sure how long dub has been around, but having an easy to use CPAN-alike (online module repo) is HUGE. Dub is great for sales. The better dub and the repo gets, the more attractive D gets.
>
> I completely agree that the availability of libraries is a huge factor.  I almost gave up on D because of the limited amount of 3rd party libs.
> I think just improving the search function would help.
> http://code.dlang.org/search?q=keccak
> Comes up with nothing, so I started porting a sha3/keccak lib from C to D.  Then someone pointed out botan has sha3 support, which can be found if you search for "crypto"
> http://code.dlang.org/search?q=crypto

i think it is the ecosystem. we do not have a better ecosystem to offer and accommodate c++ developers. by ecosystem i mean, things that take the pain out of a c++ developer and make them solely focus on their code. we don't have an IDE, we don't have one perfect, portable GUI library, we don't have a better build system, we don't even have a migration guide for them. (d for c++ developers page does not count) we only have a better and easier language. that's all we have. otherwise i do not think c++ developers are sadomasochists that would do this torture to themselves. :)