If there's something functionally deficient about the documentation
we're generating (in this case, it sounds like the shell appendix is
just capturing the output of `help`?), then I'm for changing it.
Personally, I have nothing against LaTeX (in fact, I like it quite a
bit). I just want to put in my two-cents: if we make some sort of change
that's going to require a rewrite of all of the documentation, it should
be done with something which everyone is comfortable writing and it
should satisfy the distribution requirements (HTML, printable, etc).
The problem I've seen when trying to find a universal solution is that
you end up with some mediocre solution which is less appealing than what
you started with. There are tons of tools around generating static sites
(Jekyll, Hyde, Bonsai, and Sphinx all come to mind) that are really
centered towards making easy-to-maintain sites. Maven also has its fair
share that can be auto-generation (the de-facto maven site plugin and
Doxia which Christopher mentioned)
The short of what I'm trying to get at is this: If we decide to work on
cleaning up the documentation using some new tool(s), it should
encourage maintainability and our brand (people see it and know it's
"Apache Accumulo").
On 04/24/2013 06:35 PM, David Medinets wrote:
We've been talking about changing the documentation for some time now.
Should we take a poll and commit to the change? Once a decision is made,
the work to convert from latex to the next thing can be parceled out.
However, perhaps we should be taking a whole different approach and
switching to a Semantic Wiki. Is the ability to print chapters a
requirement?
On Wed, Apr 24, 2013 at 6:04 PM, Christopher <[email protected]> wrote:
I noticed that there's a script that grabs shell output and builds an
appendix for the user manual PDF. However, that doesn't appear to be
automated as part of the documentation build profile.
So, the questions are:
1) Do we need this?
2) Does it need to be run manually?
Also, I guess there's some extra steps to convert the LaTeX source for
the PDF into HTML... regarding that:
1) are those steps documented anywhere?
2) can we automate that procedure?
3) do we even need it?
Personally, I think it'd be better to just do the PDF for now, until
we get Doxia or something similar working.
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
