Mailing-List: contact dev-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@accumulo.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAF1jEfA=zo7SC0UkS2dXjSk-G4=1jkfS3sgqvwKNRJBiJ1TDMQ@mail.gmail.com>
References: 
 <CAF1jEfDg+MWPN+_miRR0=bsqAO6EtZpisSZ1Gkn7-uVgb5e_uQ@mail.gmail.com>
	<CAPMpPc6ns0HXOD6+Xu03WEHiyAZbNXKPVoqJ+aDTP6F7A6ewyQ@mail.gmail.com>
	<CAF1jEfA=zo7SC0UkS2dXjSk-G4=1jkfS3sgqvwKNRJBiJ1TDMQ@mail.gmail.com>
Date: Wed, 1 May 2013 20:44:14 -0400
Message-ID: 
 <CAL5zq9a75qMBBdwf+xf0Q8tzFN8DG37wX0Hx+Q5t55-3r+Gm3w@mail.gmail.com>
Subject: Re: asciidoc manual
From: Christopher <ctubbsii@apache.org>
To: Accumulo Dev List <dev@accumulo.apache.org>
Content-Type: text/plain; charset=ISO-8859-1

I think it looks great, but my only concern is how easily is this
automated, without a lot of manual package installation and setup. I'd
want to make it easy for developers to simply check out the project
and build, without a lot of forethought, like it is to do with some of
the more often used maven plugins for documentation (doxia). I'd like
anybody to be able to check out the project and fix a typo in the
documentation, and test how it looks, without installing a lot of
extra packages.

(Note: this is currently not easily done with the existing system, as
pdflatex and other tools are required to be installed in advance, so
I'm glad we're looking outside of LaTeX, for that reason. I just
wouldn't want to move laterally in this regard, if we can move
upwards.)

--
Christopher L Tubbs II
http://gravatar.com/ctubbsii


On Wed, May 1, 2013 at 8:31 PM, Billie Rinaldi <billie.rinaldi@gmail.com> wrote:
> On Wed, May 1, 2013 at 2:18 PM, Adam Fuchs <afuchs@apache.org> wrote:
>
>> This looks good to me. Out of curiosity, what made you decide to use
>> asciidoc rather than the multitude of other options? Cross-platform support
>> looks good (support for Windows, Mac, and Linux). There also seems to be a
>> big enough user base for long term supportability.
>>
>
> Mostly that I had created nice-looking pdfs with it before and I was
> curious to see if it would work for the manual.  I wanted something where
> the base format was essentially plain text with good converters to html and
> pdf.  Feel free to list some obvious alternatives.
>
>
>>
>> A few things I noticed:
>> 1. The headers and TOCs differ in the pdf and html versions as to what they
>> include. It would be better if we could standardize across those -- maybe
>> we should standardize the build of both the html and pdf formats as coming
>> from the docbook intermediate format?
>>
>
> I'll look into whether we can expand the depth of the html TOC.  I think we
> could probably reduce the depth of the pdf TOC.  I'm not sure I agree they
> need to be the same, but it would be nice to know if we could adjust them.
> And the 4-level depth on the pdf is probably overkill.
>
>
>> 2. Hyperlinking in the pdf TOC would be better if it were the whole line
>> rather than just the page num (this may be a bit nitpicky).
>>
>
> I expect this probably isn't configurable.
>
>
>> 3. In the html version, some of the examples have lines that go way off to
>> the right (e.g. Table Configuration -> Iterators -> Combiners). I like how
>> the pdf version wraps those lines -- this is probably a docbook feature.
>>
>
> It looks like we may be able to specify a max width when generating the
> html.  I'll check it out.
>
> Billie
>
>
>>
>> Adam
>>
>>
>>
>> On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <billie.rinaldi@gmail.com
>> >wrote:
>>
>> > I've been experimenting with converting the user manual to asciidoc.  On
>> > balance, I think the resulting html and pdf are better than our existing
>> > ones, and the maintenance will be easier.  For a preview, see
>> >
>> > http://people.apache.org/~billie/asciidoc_user_manual
>> >
>> > In particular
>> >
>> >
>> http://people.apache.org/~billie/asciidoc_user_manual/accumulo_user_manual.html
>> > and
>> >
>> >
>> http://people.apache.org/~billie/asciidoc_user_manual/accumulo_user_manual.pdf
>> >
>> > To generate these documents, I installed asciidoc, dblatex, and
>> > source-highlight, then ran the following commands.
>> >
>> > To generate html: asciidoc -a toc -d book accumulo_user_manual.txt
>> > To generate xml: asciidoc -a toc -b docbook -d book
>> > accumulo_user_manual.txt
>> > To generate pdf: dblatex -tpdf accumulo_user_manual.xml
>> >
>> > Thoughts?
>> >
>> > Billie
>> >
>>