[PATCH] DocBook XML toolchain modernization

[Corinna Vinschen]

Hi Warren,

On May 23 21:50, Corinna Vinschen wrote:
> On May 23 13:03, Warren Young wrote:
> > On 5/23/2013 08:11, Corinna Vinschen wrote:
> > >On May 23 16:02, Corinna Vinschen wrote:
> > >>For some reason doc/Makefile.in has lost all dependencies
> > 
> > I noted that in the original proposal: one of the things you got
> > from doctool is automatic dependency generation.  I'd put an item on
> > the Wishlist to this effect, saying I needed to replace it.
> > 
> > At your prompting, I now have.  There is a new script called
> > xidepend which generates Makefile.dep, which is included (and
> > cleaned, if asked) by Makefile.in.
> > 
> > It's not perfect.  Because of the time it takes to run the
> > dependency chaser, I've elected to make it dependent on only changes
> > to the top-level XML files.  This means that if you add an XInclude
> > to one of the leaf files, the referenced file won't get added to the
> > dependency list for the top-level file that indirectly depends on it
> > until you remove Makefile.dep, forcing its re-generation.
> 
> That should be sufficient.  We're only adding files pretty seldom
> anyway.

Unfortunately it doesn't work.  I just changed only the new-features.xml
file and `make' claimed "Nothing to be done for `all'".

Inspecting the generated Makefile.dep, I see this:

  /home/corinna/src/cygwin/vanilla/winsup/doc/cygwin-ug-net//home/corinna/src/cygwin/vanilla/winsup/doc/cygwin-ug-net.html: legal.xml overview.xml setup-net.xml using.xml programming.xml
  /home/corinna/src/cygwin/vanilla/winsup/doc/faq//home/corinna/src/cygwin/vanilla/winsup/doc/faq.html: faq-what.xml faq-setup.xml faq-resources.xml faq-using.xml faq-api.xml faq-programming.xml faq-copyright.xml

As you can see, the paths of the make targets are wrong, *and* the
list of dependencies is broken as well.

Running xidepend in the source file results in:

  cygwin-ug-net/cygwin-ug-net.html: legal.xml overview.xml setup-net.xml using.xml programming.xml  ov-ex-win.xml ov-ex-unix.xml highlights.xml new-features.xml  setup-env.xml setup-maxmem.xml setup-locale.xml setup-files.xml  pathnames.xml textbinary.xml filemodes.xml specialnames.xml cygwinenv.xml ntsec.xml cygserver.xml ../utils/utils.xml effectively.xml  gcc.xml gdb.xml dll.xml windres.xml 
  faq/faq.html: faq-what.xml faq-setup.xml faq-resources.xml faq-using.xml faq-api.xml faq-programming.xml faq-copyright.xml 

This looks a lot like you're still testing this with a in-tree build.

Again, as cgf already wrote, we do *NOT* support in-tree builds.  Always
test with a separate build directory, please.

I fixed this now temporarily like this:

- I fixed the generation of the basename in xidepend to take VPATH
  into account.

- I moved the `include Makefile.dep to the end of Makefile.in, otherwise
  the Makefile.dep rules clobber the all rule.

- I dropped the "$(srcdir)" from that include since Makefile.dep is
  created in the build dir.

- I fixed the Makefile.dep build rule to work from any build dir.

- I removed faq.xml as dependency from the Makefile.dep build rule
  since the faq sources are given via $FAQ_SOURCES anyway.

- I added the necessary rule to rebuild Makefile automatically if
  Makefile.in changes.

This works now, but it's unsatisfactory, because we now have three
different ways to implement dependencies:

- cygwin-api deps are generated by tweaking Makefile.in via doctool

- faq deps are generated via setting a variable and referring the
  variable in the build dependency.

- cygwin-ug-net deps are generated via xidepend and create a separate
  Makefile.dep file with a dependency rule.

It would be nice if this could be merged into one unified way to
generate the deps soonish, with the simple requirement that it should
work always, and from a spearate build dir in the first place.


Thanks,
Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat