Christopher 2013-04-24, 22:04
Billie Rinaldi 2013-04-25, 02:09
Christopher 2013-04-25, 13:40
Christopher 2013-04-25, 13:43
Billie Rinaldi 2013-04-25, 14:13
David Medinets 2013-04-24, 22:35
-Re: Shell documentation appendix
Josh Elser 2013-04-24, 23:01
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
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
> 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
Keith Turner 2013-04-25, 16:38
Billie Rinaldi 2013-04-25, 16:48
Keith Turner 2013-04-25, 16:55
Christopher 2013-04-25, 18:38
Keith Turner 2013-04-25, 18:48
Eric Newton 2013-04-25, 18:49
Billie Rinaldi 2013-04-26, 01:56
Christopher 2013-04-26, 02:58