You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@accumulo.apache.org by Billie Rinaldi <bi...@gmail.com> on 2013/05/01 19:10:50 UTC
asciidoc manual
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
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
On Wed, May 1, 2013 at 5:44 PM, Christopher <ct...@apache.org> wrote:
> 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.)
>
At this point, I wouldn't mind a lateral move that is more easily
maintainable. I haven't detailed the current process of translating latex
to html, but it is probably worse than you imagine. Basically, I want a
simple solution that will make it so I don't have to do the manual
latex/html translation process one more time for 1.5.0 (a process that
creates imperfect html anyhow). The asciidoc solution also has the benefit
of making more consistent pdf and html versions than we have now.
Based on a superficial initial look at doxia, it seems like we're going to
have to give up something to use it for generating html and pdf formats,
i.e. we may have to maintain the manual in xml format instead of plain
text. I would rather not do that. But if that's not true, or if someone
makes a really compelling argument for how much better things could be if
we start with xml, we could consider switching in the future.
Billie
> --
> Christopher L Tubbs II
> http://gravatar.com/ctubbsii
>
>
> On Wed, May 1, 2013 at 8:31 PM, Billie Rinaldi <bi...@gmail.com>
> wrote:
> > On Wed, May 1, 2013 at 2:18 PM, Adam Fuchs <af...@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
> >> >
> >>
>
Re: asciidoc manual
Posted by Christopher <ct...@apache.org>.
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 <bi...@gmail.com> wrote:
> On Wed, May 1, 2013 at 2:18 PM, Adam Fuchs <af...@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
>> >
>>
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
On Wed, May 1, 2013 at 2:18 PM, Adam Fuchs <af...@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
> >
>
Re: asciidoc manual
Posted by Adam Fuchs <af...@apache.org>.
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.
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?
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).
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.
Adam
On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <bi...@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
>
Re: asciidoc manual
Posted by Josh Elser <jo...@gmail.com>.
I actually really liked that highlighting :X
On 5/1/13 2:42 PM, David Medinets wrote:
> The new documents look good but can you turn off java highlighting? I find
> the different colors distracting.
>
>
> On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <bi...@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
>>
Re: asciidoc manual
Posted by Christopher <ct...@apache.org>.
I like the asciidoctor-maven-plugin, but agree the PDF limitation is a
big issue. Doxia has APT (Almost Plain Text) support, which is similar
to Asciidoc. I'd like to investigate that option, as well.
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
On Sat, May 4, 2013 at 7:13 AM, Michael Wall <mj...@gmail.com> wrote:
> I have used asciidoc for several projects and really like it. One option
> is http://asciidoctor.org/. It is a Ruby processor for asciidoc, but it
> runs in JRuby and even has a maven plugin,
> https://github.com/asciidoctor/asciidoctor-maven-plugin. Github uses
> asciidoctor for README.adoc and README.asciidoc files,
> http://asciidoctor.org/news/2013/01/30/asciidoc-returns-to-github/ and I
> even see traffic about using it from the JBoss community. So it is in
> active development, well supported and growing. The only issue I see is
> that asciidoctor does not support a native build to PDF, you still have to
> use the asciidoc toolchain. But that may changed in the future,
> https://github.com/asciidoctor/asciidoctor/issues/113
>
> Mike
>
>
> On Fri, May 3, 2013 at 5:18 PM, David Medinets <da...@gmail.com>wrote:
>
>> I took another look at the HTML and it was indeed the bright red strings
>> that I did not like. Otherwise, brilliant!
>>
Re: asciidoc manual
Posted by Michael Wall <mj...@gmail.com>.
I have used asciidoc for several projects and really like it. One option
is http://asciidoctor.org/. It is a Ruby processor for asciidoc, but it
runs in JRuby and even has a maven plugin,
https://github.com/asciidoctor/asciidoctor-maven-plugin. Github uses
asciidoctor for README.adoc and README.asciidoc files,
http://asciidoctor.org/news/2013/01/30/asciidoc-returns-to-github/ and I
even see traffic about using it from the JBoss community. So it is in
active development, well supported and growing. The only issue I see is
that asciidoctor does not support a native build to PDF, you still have to
use the asciidoc toolchain. But that may changed in the future,
https://github.com/asciidoctor/asciidoctor/issues/113
Mike
On Fri, May 3, 2013 at 5:18 PM, David Medinets <da...@gmail.com>wrote:
> I took another look at the HTML and it was indeed the bright red strings
> that I did not like. Otherwise, brilliant!
>
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
I regenerated the asciidoc html and pdf with different settings:
http://people.apache.org/~billie/asciidoc_user_manual/
I managed to address the toc depth issue and to give the html syntax
highlighting a more muted color scheme. However, although I've set a max
width for the html, the verbatim-style lines still won't wrap. I also
tried a new theme (based on Keith's discovery).
Billie
On Fri, May 3, 2013 at 2:18 PM, David Medinets <da...@gmail.com>wrote:
> I took another look at the HTML and it was indeed the bright red strings
> that I did not like. Otherwise, brilliant!
>
Re: asciidoc manual
Posted by David Medinets <da...@gmail.com>.
I took another look at the HTML and it was indeed the bright red strings
that I did not like. Otherwise, brilliant!
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
On Wed, May 1, 2013 at 11:42 AM, David Medinets <da...@gmail.com>wrote:
> The new documents look good but can you turn off java highlighting? I find
> the different colors distracting.
>
Are there any specific colors that are bothering you? I don't know if this
is configurable, but we could look into it. For example, I find the colors
in the pdf much more pleasing than the colors in the html, which are
totally different. The bright red for string literals seems unnecessary.
Billie
>
>
> 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
> >
>
Re: asciidoc manual
Posted by David Medinets <da...@gmail.com>.
The new documents look good but can you turn off java highlighting? I find
the different colors distracting.
On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <bi...@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
>
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
On Wed, May 1, 2013 at 11:06 AM, Josh Elser <jo...@gmail.com> wrote:
> On 5/1/13 1:59 PM, Billie Rinaldi wrote:
>
>> >I think the only things that stands out at me are that the tables are a
>>> >little gross looking (notably 6.3 and 6.4, "Indexing" and
>>> "Entity-Attribute
>>> >and Graph Tables"). I'll try to look around tonight, but is there
>>> something
>>> >we could do to get column and row outlines? Does asciidoc have any
>>> notion
>>> >of plugins that we could leverage for prettier tables?
>>> >
>>>
>> What do you dislike about the tables? Asciidoc tables aren't very
>> configurable, but there are a few things that can be changed. Do you mean
>> grid lines for the table, lines between each column and row? We can add
>> those, the options are "none", "rows", "cols" or "all". I'll try adding
>> row lines and see if it helps.
>>
>>
>> Yes, the lack of row and column outlines. I think that's what is sitting
> odd with me. Perhaps the lack of a table outline on the left and right side
> of the table, too. The table comes across as a paragraph of text instead of
> a tightly structured element.
>
> This is just my gut feeling. If others think it looks fine, that's ok too
> :)
>
I agree having the left and right sides missing made it look kind of
funny. I updated the version at ~billie with walls and row lines.
Billie
Re: asciidoc manual
Posted by Josh Elser <jo...@gmail.com>.
On 5/1/13 1:59 PM, Billie Rinaldi wrote:
>> >I think the only things that stands out at me are that the tables are a
>> >little gross looking (notably 6.3 and 6.4, "Indexing" and "Entity-Attribute
>> >and Graph Tables"). I'll try to look around tonight, but is there something
>> >we could do to get column and row outlines? Does asciidoc have any notion
>> >of plugins that we could leverage for prettier tables?
>> >
> What do you dislike about the tables? Asciidoc tables aren't very
> configurable, but there are a few things that can be changed. Do you mean
> grid lines for the table, lines between each column and row? We can add
> those, the options are "none", "rows", "cols" or "all". I'll try adding
> row lines and see if it helps.
>
>
Yes, the lack of row and column outlines. I think that's what is sitting
odd with me. Perhaps the lack of a table outline on the left and right
side of the table, too. The table comes across as a paragraph of text
instead of a tightly structured element.
This is just my gut feeling. If others think it looks fine, that's ok too :)
Re: asciidoc manual
Posted by Billie Rinaldi <bi...@gmail.com>.
On Wed, May 1, 2013 at 10:43 AM, Josh Elser <jo...@gmail.com> wrote:
> Nice! Those code snippets look awesome.
>
Yeah, I really like the syntax highlighting and that it comes through in
both the html and the pdf.
>
> I think the only things that stands out at me are that the tables are a
> little gross looking (notably 6.3 and 6.4, "Indexing" and "Entity-Attribute
> and Graph Tables"). I'll try to look around tonight, but is there something
> we could do to get column and row outlines? Does asciidoc have any notion
> of plugins that we could leverage for prettier tables?
>
What do you dislike about the tables? Asciidoc tables aren't very
configurable, but there are a few things that can be changed. Do you mean
grid lines for the table, lines between each column and row? We can add
those, the options are "none", "rows", "cols" or "all". I'll try adding
row lines and see if it helps.
>
> Thanks for looking into this!
>
>
> On 5/1/13 1:10 PM, Billie Rinaldi 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<http://people.apache.org/~billie/asciidoc_user_manual>
>>
>> In particular
>> http://people.apache.org/~**billie/asciidoc_user_manual/**
>> accumulo_user_manual.html<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<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
>>
>>
>
Re: asciidoc manual
Posted by Josh Elser <jo...@gmail.com>.
Nice! Those code snippets look awesome.
I think the only things that stands out at me are that the tables are a
little gross looking (notably 6.3 and 6.4, "Indexing" and
"Entity-Attribute and Graph Tables"). I'll try to look around tonight,
but is there something we could do to get column and row outlines? Does
asciidoc have any notion of plugins that we could leverage for prettier
tables?
Thanks for looking into this!
On 5/1/13 1:10 PM, Billie Rinaldi 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
>
Re: asciidoc manual
Posted by Eric Newton <er...@gmail.com>.
Looks good to me.
On Wed, May 1, 2013 at 1:10 PM, Billie Rinaldi <bi...@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
>