Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Threaded View
Accumulo >> mail # dev >> asciidoc manual

Copy link to this message
Re: asciidoc manual
On Wed, May 1, 2013 at 2:18 PM, Adam Fuchs <[EMAIL PROTECTED]> 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.

> Adam
> On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <[EMAIL PROTECTED]
> >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
> >