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
Description: This is a digitally signed message part