Home | About | Sematext search-lucene.com search-hadoop.com
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB
 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.

Billie
>
> 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
> >
>
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB