The lack of standardization is a real problem. The fact that
markdown.pl supports a different dialect than does github, and then of
course all the really cool people are using multimarkdown, though Trello
(launched yesterday) supports regular markdown for comments, ...
I mean, it's annoying. It's already annoying, since github and
markdown.pl support different conventions around embedded_underscores
and whether they should be\_escaped.
It's definitely much less standard than is DocBook XML, and that effects
tooling support.
On the other hand, there's less complexity for tooling to support, and
presumably reasonably skilled nerds can munge plaintext with scripts to
get to what's needed for some particular purpose. Fundamentally
plaintext, readable-as-source formal Markdown documentation, with clever
paths to "build" to PDF, DocBook, website, etc?
There does seem to be a rise generally out in the world in terms of
Markdown-supporting tooling. Take a look at this, for instance:
http://www.iawriter.com/
http://www.iawriter.com/mac/faq#markdown
So yes, when Markdown goes the way of the dodo, it will still be
readable and writeable plaintext that motivated coders can write scripts
to compile out to whatever's wanted. Not saying it's going to be
super-easy or no-effort-required, but I do think it's evidently
feasible. And likely some of these tools will be beneficial -- at the
least, a workflow of merging the markdown files, slurping into IA
Writer, and printing to PDF? It's annoying, but it would work? And
that's not even the primary plan, that's a fallback when LaTeX gets too
infuriating.
How do people feel about writing Markdown? Marvin, you going to be
thrilled to use this sparse fundamentally plaintext language, or are you
going to be annoyed that there isn't DocBook's formal support for
citations and tables and so forth?
Appreciate the +1s of support, but looking to have the discussion about
what's a reasonable format for authoring and maintaining the content of
the documentation. At least enough discussion to get buy-in so that
there's as much comfort as possible with pressing forward with composing
excellent content for this manual. I see that as really the most
important question. We should use a markup language that's
sophisticated enough to handle most desired manual content, and no more
complex than that.
I'm willing to confine myself to Markdown's very sparse markup in
exchange for not having to deal with XML-in-XML. This work for everyone
else too?
Tables are at best a pain (fall back to inline HTML) and at worst won't
work (looks like they don't work when building to PDF in the current
build script.) Is that going to be okay?
If everyone has a moment, maybe fork my repo, add or edit some
documentation (any documentation, maybe grab something from the wiki in
need of love as a starting point), and see how it feels?
https://github.com/apetro/CAS-Documentation
Andrew
On 9/14/2011 9:27 AM, Marvin Addison wrote:
I'm all for making our lives easier, and if Markdown will accomplish that,
+1
My only lingering reservation is that standards-based XML provides a
pretty flexible path to migrate to other rendering tools in the
future. Markdown markup is tied to its rendering engine. That said I
think the practical matters outweigh this conceptual concern.
Besides, the plain text of Markdown is pretty readable, so in the
worst case if Markdown goes the way of the dodo the manual would be
fairly readable as plain text.
+1
M
--
You are currently subscribed to [email protected] as:
[email protected]
To unsubscribe, change settings or access archives, see
http://www.ja-sig.org/wiki/display/JSG/cas-dev
