Re: [DynInst_API:] commit: integrated build system for documentation

[Josh Stone <jistone@xxxxxxxxxx>]

On 08/13/2015 09:07 AM, Bill Williams wrote:
> There are now targets for doc (build all latex manuals, check existence 
> of Word-derived PDFs) and $COMPONENT-doc (same, but for an individual 
> manual) for every component that has documentation. I've moved the 
> authoritative versions of the word docs to the dyninst repository, as 
> well. These do *not* build as part of "all" by default, as many of our 
> regression testing machines lack tikz/pgf support in their LaTeX 
> installs (and I expect this to be a common problem). The $COMPONENT-doc 
> target does not exist for LaTeX-based manuals (all but Dyninst and 
> ProcControl) if LaTeX is not present on the system.

Can you document the exact requirements?

I don't know a lot about LaTeX, but I see Fedora has a lot of packages
with tikz/pgf in the description.  There are over 5000 total texlive*
subpackages available -- I'd prefer to install only what is needed.

(The texlive.spec is a 400k-line autogenerated beast.  Don't go there.)

However, if the release tarball will have PDFs for everything, I may not
bother rebuilding them at all for rpm packaging.

Note, there are some PDFs in the repo already, named subtly different
than the build targets.  e.g. parseapi.pdf vs. parseAPI.pdf,
stackwalkerapi.pdf vs. stackwalk.pdf, etc.  Whether or not you intend to
commit pdf products, please clean this up.

> The "install" target will install any manuals that exist to the 
> doc-install directory (by default, $CMAKE_INSTALL_PREFIX/doc).

I think the more typical path is "$prefix/share/doc/$package".

But for rpm packaging, I don't need them installed anyway.  I can use
the "%doc" macro on the files in the build dir, and it will do the right
thing for distro policy.

> Please consider the docs repository deprecated as of this commit.

That's good -- they belong in lockstep.

Honestly, I think it was a mistake to split the testsuite too.  It
really should be part of the main source distribution.  It could be an
optional part of the build, disabled by default, but it's quite useful
for testing on arch+distros that are different than your "upstream"
environments.  e.g. Our QA uses this heavily in the release process
across all of our supported platforms.

It wouldn't even bloat the git tree much, as the bulk of it is already
in the history from before the split, and git is good about sharing
objects.  "git subtree add" can rejoin them easily if you like, either
squashed or with full history anew.  Then only cmake would need tweaks
to reunify the build.

> Is there a desire for a configuration option that will add the docs to 
> "all"?

I think running "make all doc" is fine.