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.


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

Attachment: signature.asc
Description: This is a digitally signed message part

Reply via email to