-Re: asciidoc manual
Billie Rinaldi 2013-05-03, 20:35
On Wed, May 1, 2013 at 5:44 PM, Christopher <[EMAIL PROTECTED]> 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
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.
> Christopher L Tubbs II
> On Wed, May 1, 2013 at 8:31 PM, Billie Rinaldi <[EMAIL PROTECTED]>
> > 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
> >> 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
> > 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
> >> include. It would be better if we could standardize across those --
> >> we should standardize the build of both the html and pdf formats as
> >> from the docbook intermediate format?
> > I'll look into whether we can expand the depth of the html TOC. I think
> > could probably reduce the depth of the pdf TOC. I'm not sure I agree
> > need to be the same, but it would be nice to know if we could adjust
> > 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
> >> the right (e.g. Table Configuration -> Iterators -> Combiners). I like
> >> 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: