[help-texinfo] What's the sensible way to modularize documenation?

[Steve Juranich]

I'm currently facing a little problem where I'm writing documentation for
a fairly large software package that includes an API as well as a few
stand-alone programs.  What I'd like to do is make the documentation for
the stand-alones be a section in the main package info page, but also have
it so when a user types 'info program-name', something useful is printed
to the screen.

The best solution I've found so far is to put the guts of the
documentation for the binaries into their own files (called something like
'base-program-name.texi'), and then just use a @include in both the
MainPackage.texi and the program-name.texi files.

This works fairly well for me as long as I don't care about offline
documentation.  When I start trying to make PDF or HTML versions of the
documentation, I get various message that all basically equate to the fact
that the cross-references get all hosed when I break up the files like I
have.

My next option is to write "dummy" info pages that basically say:

Don't look here, check out *Note (MainPackage)program-name: instead.

To me, this is ultra-kludgey, as opposed to my current solution which is
only super-kludgey.

At any rate, I was wondering if anybody out there had any ideas on how to
make this work, or if there was a standard "texinfo" way of doing this
kind of thing.

Thanks for the help.

-- 
Stephen W. Juranich
Science Applications Intl. Corp. (SAIC)
(520) 570-7706