accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh Elser <josh.el...@gmail.com>
Subject Re: Shell documentation appendix
Date Wed, 24 Apr 2013 23:01:15 GMT
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 <ctubbsii@apache.org> 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
>>


Mime
View raw message