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

[Gaetan Nadon]

On Mon, 2010-10-11 at 06:04 -0700, Dan Nicholson wrote:

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

I don't mind giving more flexibility, but it will generate a "defaults"
war. Someone with
a slower computer will have a different view about what is slow vs
acceptable.


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

That's my reference for "nightmare", which means it is too complex to
code and test and still has at least
one loophole which would require more complexity to fix. If there were
better support from Automake
for this scenario, we probably would not have this issue.

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

That is not representative of the all the coding needed to achieve that
goal, it's one of bugs
that needed to be fixed.

Compare the configure.ac and the Makefile.am of one module with
generated docs in the tarball and
one module without and you will see a big difference.


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

That's just one scenario. 


Extra stuff in configure.ac not normally needed:


        # Check for xmlto and asciidoc for man page conversion
        # (only needed by people building tarballs)
        if test "$have_xmlto" = yes && test "$have_asciidoc" = yes; then
        	have_doctools=yes
        else
        	have_doctools=no
        fi
        AM_CONDITIONAL([HAVE_DOCTOOLS], [test $have_doctools = yes])
        if test $have_doctools = no; then
        	AC_MSG_WARN([xmlto or asciidoc not found - cannot create man pages without it])
        fi
        
        # Determine if the source for man pages is available
        # It may already be present (tarball) or can be generated using doctools
        AM_CONDITIONAL([INSTALL_MANPAGES],
        	[test -f "$srcdir/man/XAllowDeviceEvents.man" || \
        	  test $have_doctools = yes])


Extra check in Makefile.am not normally needed:


        if INSTALL_MANPAGES
        libman_DATA = $(libman_PRE:.man=.$(LIB_MAN_SUFFIX))
        endif


Impact on testing:

For anyone making a change in the makefile, he needs to know about this
stuff so as not to
accidentally break it. This means testing various permutations of
git/tarball with/without xmlto
and with/without generated docs.

Impact on distcheck:

If you don't have xmlto, you cannot create a tarball because the
generated docs are needed.
This is an incentive for developers to not run distcheck on a regular
basis and not discover
some errors. It is an unfortunate side-effect.

Outstanding issue:

The check for a .man page in configure.ac is unreliable. It is done at
configuration time
and things can change afterwards. This was reported by a developer.
The build stops with an obscure error message:


        make[1]: *** No rule to make target `XChangeDeviceDontPropagateList.man',
         needed by `XGetDeviceDontPropagateList.man'.  Stop.

More code is needed to plug this loophole.

Conclusion:

If it must be done, then it must be done. In my book, it's ugly and
brittle, not because people
are writing bad code, but because there is no support from Automake. 

Is it worth spreading this complexity throughout? So far I have not
heard a requirement
for generated docs in the tarball for their own sake, only as a
workaround to problems.

Most of the docs were in xorg-docs module until recently and many were
not built.
Why would they need to be in a tarball now?

There is a web site in construction which contains all the docs, that
should address the need
of those who want to consult documentation that does not need to be
updated to the minute.

The documentation landscape has changed recently (and still not quite
complete) which opens
the possibility for new solutions. 

It's not a bad idea to have a second look at the defaults, now that all
the docs are being built.
Developers will always prefer not to build them unless they need them
and it will always be
just a subset. I have no idea what distros do.

I am saying all this to share my perspective, not to claim I am right, I
am aware I am only seeing
a portion of the big picture.

Thanks










-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20101011/8495e679/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://lists.x.org/archives/xorg-devel/attachments/20101011/8495e679/attachment.pgp>