Re: Comment on: FAQ chapter for the manual

[Alexandre Duret-Lutz]

Hi Bruce!

>>> "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.  :-)

Point taken.

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

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
getdefs/autogen.

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.)
-- 
Alexandre Duret-Lutz