[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Comment on: FAQ chapter for the manual
Re: Comment on: FAQ chapter for the manual
Fri, 07 Feb 2003 00:11:05 +0100
Gnus/5.090008 (Oort Gnus v0.08) Emacs/21.2 (i386-pc-linux-gnu)
>>> "Bruce" == Bruce Korb <address@hidden> writes:
Bruce> You left out an argument in favor: the add-on files are self
Bruce> contained. I, in fact, intentionally make it very simple to
Bruce> add expression files to AutoGen. :-) You add a file named
Bruce> ``exprMumble.c'' to the agen5 directory and it is automatically
Bruce> incorporated into autogen, but for the fact you also have to
Bruce> edit Makefile.am to add it to the list. If they don't want to
Bruce> distribute it, then omit it. It gets dropped automatically,
Bruce> but for the fact it is now listed in Makefile.am. :-)
Bruce> There ought to be a way to say, "I understand all your
Bruce> philosophical objections, but I don't care. Glob this expression
Bruce> and insert the result into Makefile.in and please don't tell me you
Bruce> know how to do my business better than me."
I think we agree. The last sentence in this section was meant
to imply such a patch would be considered, would someone mind
enough to work it out.
Bruce> We have philosophical differences.
Fortunately this allows us to talk more often.
>> Suppose our package contains a program for
>> which we want to build a man page using `help2man'.
Bruce> This example is too simplistic. There are a number of packages
Bruce> that derive documentation from the sources.
That's seems simplier to me: you can distribute the sources and
the derived documentation without spurious rebuilds. I'm
speaking of a simple one-step .c -> .html case here.
If you meant .c -> .texi -> .info, you need to distribute the
files at each step if you decide to distribute the latter.
This is really what I wanted to imply with "If you distribute
something generated, distribute its sources." Maybe I should
elaborate on this. Or would it be clearer to just replace
`sources' by `dependencies'?
There are ugly stamp-file tricks to play if one doesn't
want to ship intermediate files, but I'm not volunteering
to document such an hairy topic. Not these days, at least.
Bruce> Mine is "special" in that I distribute the piece that
Bruce> does the extraction, but anyone deriving a .texi file
Bruce> from javadoc comments will have essentially the same
Honestly, I've used getdefs/autogen to build Texinfo
documentation in three projects so far and never hit any
difficulty. I don't think this is different from your javadoc
example. I just ship the .info files so that users to not need
Texinfo. And I ship the .texi files so that users do not need
I understand you can decide that my last sentence does not apply
in your case, since your package builds getdefs and autogen.
I think this precisely makes your project different from others.
Bruce> Do you distribute trivially extracted text or not? I
Bruce> say, "not" and if not you have this dilemma. Various
Bruce> pieces of documentation will depend upon the extracted
Bruce> .texi file, even if you distribute these docs. The
Bruce> result is your clients will always have their builds
Bruce> attempting to rebuild distributed docs and the distcheck
Bruce> will choke. After years of arguing this, I did finally
Bruce> win my point and it ought to be in the FAQ. :-)
I confess I don't understand this paragraph at all. Are you
speaking about not distributing some intermediate files?
Also what are the dilemma and the point?
You said your clients always rebuild distributed docs. Either
you think this is ok and there is no point in distributing these
docs, either you think this rebuilding is not ok and your
dependencies need work. In all cases it seems distcheck is
right in complaining. I don't yet see how this could be
otherwise so I'm certainly missing your point.
Bruce> BTW, the problem gets much worse if the product distributes with
Bruce> no .texi files because the texi rules know that if there are no
Bruce> texi files, then there can be no texi documentation. This is
Bruce> a mistake. I've been told that the texi rules come from the texi
Bruce> folks, so it's not Automake's job to fix it. It's still a problem.
Fixing the rules for building .info files is cleary Automake's job.
Could you fill a PR with an example of what you are trying to achieve?
(I'm not sure I understand what you want.)