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