<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN"> <HTML> <HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8"> <META NAME="GENERATOR" CONTENT="GtkHTML/3.26.0"> </HEAD> <BODY> On Mon, 2010-10-11 at 06:04 -0700, Dan Nicholson wrote: <BLOCKQUOTE TYPE=CITE> <TT>No, the issue is that the pdf and ps build (with fop) takes a long</TT> <TT>time and most of the time I'm guessing people wouldn't want that to be</TT> <TT>part of their build. This gives the opportunity to be much more fine</TT> <TT>grained with the defaults.</TT> </BLOCKQUOTE> 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. <BLOCKQUOTE TYPE=CITE> <TT>> The conversion to DocBook/XML implies that the xmlto tooling was adequate</TT> <TT>> and available on</TT> <TT>> a reasonable number platforms. Including generated docs (of any kind) in the</TT> <TT>> tarball is a nightmare</TT> <TT>> which still has unresolved problems.</TT> <TT>I would disagree that including the docs in the tarball is a</TT> <TT>nightmare. Lots of projects do that for their users as a convenience.</TT> <TT>You just include them in the dist and add one AM_CONDITIONAL from</TT> <TT>configure. Remember, we did it for libXi and it was a tiny patch. I</TT> <TT>don't know of any unresolved issues with that.</TT> </BLOCKQUOTE> 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. <BLOCKQUOTE TYPE=CITE> <TT><A HREF="http://cgit.freedesktop.org/xorg/lib/libXi/commit/?id=c183e15263787af913bf8eb7be707e0f2e974824">http://cgit.freedesktop.org/xorg/lib/libXi/commit/?id=c183e15263787af913bf8eb7be707e0f2e974824</A></TT> </BLOCKQUOTE> 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. <BLOCKQUOTE TYPE=CITE> <TT>The reason to do it isn't entirely the availability of the tools, but</TT> <TT>the fact that generating the docs is a slow process that should</TT> <TT>produce the same output on any system. I personally would like to see</TT> <TT>the html versions of the all the docs included in the tarballs. Then</TT> <TT>you can just download the docs and not have to build them.</TT> </BLOCKQUOTE> That's just one scenario. Extra stuff in configure.ac not normally needed: <BLOCKQUOTE> <PRE> # 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]) </PRE> </BLOCKQUOTE> Extra check in Makefile.am not normally needed: <BLOCKQUOTE> <PRE> if INSTALL_MANPAGES libman_DATA = $(libman_PRE:.man=.$(LIB_MAN_SUFFIX)) endif </PRE> </BLOCKQUOTE> 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: <BLOCKQUOTE> <PRE> make[1]: *** No rule to make target `XChangeDeviceDontPropagateList.man', needed by `XGetDeviceDontPropagateList.man'.  Stop. </PRE> </BLOCKQUOTE> 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 </BODY> </HTML>