[
https://issues.apache.org/jira/browse/ARROW-95?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15226556#comment-15226556
]
Wes McKinney commented on ARROW-95:
-----------------------------------
We chatted briefly about it on Slack -- I presumed we'd have a ML discussion or
a high level JIRA about making a technical decision, so let's do that.
I'm trying to find the Drill or Calcite documentation sources, can someone send
a link to those to me?
My understanding is that Markdown is much more minimal than reStructuredText or
Asciidoc for creating more complex / interconnected documentation. As an
example of this, named anchors don't really work in Markdown
(http://stackoverflow.com/questions/6695439/how-do-you-create-link-to-a-named-anchor-in-multimarkdown),
and solutions for them are HTML-specific. What if we want to generate a PDF?
Maybe this need is hard to anticipate, but I'm not very comfortable using
Markdown for more than READMEs and blogs (e.g. Jekyll / Pelican).
Folks with more Markdown experience making more complex documentation should
comment on their experience and how much Markdown's limitations (as compared
with rst / adoc) end up being problems.
> Scaffold Main Documentation using asciidoc
> ------------------------------------------
>
> Key: ARROW-95
> URL: https://issues.apache.org/jira/browse/ARROW-95
> Project: Apache Arrow
> Issue Type: Task
> Reporter: Uwe L. Korn
>
> For the general documentation of Arrow, we want to use asciidoc. The "general
> documentation" includes:
> * The Arrow spec / memory layout
> * Howtos for building arrow on different platforms
> * Getting Started snippets for each language and a link to the (to-be-build)
> API documentation
> It would be nice to have a build system and the main file/folder structure in
> place so we can split the work up.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
