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 > > >
