Re: Comment on: FAQ chapter for the manual

[Bruce Korb]

Alexandre Duret-Lutz wrote:
> 
> Hi Bruce!


Hi, ALexandre!  :-)


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

I missed that nuance. :)

>  Bruce> We have philosophical differences.
> 
> Fortunately this allows us to talk more often.

:-D

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

I do.  I distribute the rules and tools for the .c -> .texi,
but not the next step.  That makes mine a bit, "special".  :-(

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

There's now a relatively simple process by which one can
delete reconstructed, but also distributed files.  I do
think it would be worthwhile to make that visible so that
those that do construct and distribute .texi files won't
have to necessarily tear their hair out.  Here's the magic:

distcleancheck_listfiles = \
     find -type f -exec 'test -f $(srcdir)/{} || echo {} ;'

That will cause to be removed any file you both build and
redistribute.  Period.

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

It isn't.  Javadoc extraction is a bit better known is all.

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

and if you have the .texi derivation rule as well, then
you need to either 1) be careful that "make distcheck"
doesn't construct the distributed file, or 2) use the above
magic.  I use the magic.  I can understand it and I don't
have to worry whether or not the distcheck dependencies
wind up building what I distribute.

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

It was an insufficiently clear reference to distcleancheck_listfiles.

> You said your clients always rebuild distributed docs.

It's ok to rebuild the .texi, not ok to choke because
they dont have texinfo or texi2html or whatever to go on.
In other words, I distribute the .texi and the .info and
I distribute the means for getting from .c to .texi.

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

I'll have to get back on that.

Cheers! - Bruce