[PATCH libX11 3/3] docs: Disable fop documentation by default

[Dan Nicholson]

On Sun, Oct 10, 2010 at 6:00 PM, Gaetan Nadon <memsize at videotron.ca> wrote:
> On Sun, 2010-10-10 at 10:50 -0700, Dan Nicholson wrote:
>
>> Should we be distributing the doc output in the tarball then?
>> Currently, we're not, but that would be a simple update to
>> spec/xmlrules.in in libX11.
>
> Oh, I thought they were, but I didn't actually check. IMO, I'd either
> leave the compose key charts out or distribute just the html versions.
> Either way, I'd default fop to off. People that really want the pdf or
> ps versions of the docs can build them on their own.
>
>
> I am just catching up with all the posts. Are we talking about solving  a
> libX11
> problem only, or are we talking about *all* of DocBook XML documentation?
>
> I can understand turning off doc build in some cases due to build time. This
> can be done with
> XORG_ENABLE_DOCS(no) or XORG_ENABLE_SPECS(no).

No, the issue is that the pdf and ps build (with fop) takes a long
time and most of the time I'm guessing people wouldn't want that to be
part of their build. This gives the opportunity to be much more fine
grained with the defaults.

> The conversion to DocBook/XML implies that the xmlto tooling was adequate
> and available on
> a reasonable number platforms. Including generated docs (of any kind) in the
> tarball is a nightmare
> which still has unresolved problems.

I would disagree that including the docs in the tarball is a
nightmare. Lots of projects do that for their users as a convenience.
You just include them in the dist and add one AM_CONDITIONAL from
configure. Remember, we did it for libXi and it was a tiny patch. I
don't know of any unresolved issues with that.

http://cgit.freedesktop.org/xorg/lib/libXi/commit/?id=c183e15263787af913bf8eb7be707e0f2e974824

The reason to do it isn't entirely the availability of the tools, but
the fact that generating the docs is a slow process that should
produce the same output on any system. I personally would like to see
the html versions of the all the docs included in the tarballs. Then
you can just download the docs and not have to build them.

--
Dan