[OE-core] [PATCH 0/8] support xmlto

[Burton, Ross]

On 8 July 2014 10:47, Hongxu Jia <hongxu.jia at windriver.com> wrote:
> The xmlto was shipped from meta-oe, and fixed the defects that
> 'xmlto/xsltproc stylesheets cannot be found even when they are
> installed in sysroot'
>
> The xmlto required docbook-xml-dtd and docbook-xsl-stylesheets,
> we refered debian's docbook-xml-dtd and ubuntu config.
>
> We also enable xmlto for alsa-utils, xorg-proto-common.inc,
> xorg-lib-common.inc, xserver-xorg.inc.

Presumably the goal here is to enable documentation generation?  I'd
say what we want is more complicated than a blanket "--with-xmlto" and
comes back to the same points I raised when the doxygen patch was
submitted.

Native packages never need to build documentation, as nobody is going
to read it.  We've made steps in this direction with the texinfo class
that stubs makeinfo for native recipes.

Target packages may want documentation, but may not.  A powerul board
such as a Minnow or Beagle can support development on the target and
having e.g. the X11 protocol documentation available might be
convenient.  A board with no UI and 64MB of RAM isn't going to support
development on the target and every built piece of documentation is
wasted time.

SDK packages do want documentation.  The ability to ship a SDK with a
toolchain, libraries, and exactly the correct documentation for the
libraries is valuable and currently something we can't do.

I'd suggest that we need a global BUILD_DOCUMENTATION variable that
can be overridden per-class so that e.g. native and target recipes
don't build documentation but SDK packages do.  Then along with xmlto
we can add gtk-doc and doxygen, adding the ability to build full API
documentation for the SDKs.

As such this is definitely a two-part series.  Adding xmlto is useful
and I'm genuinely happy that someone who wasn't me managed to get
docbook-xsl working ;) as that's the blocker for gtk-doc support too.
However rnabling xmlto in some recipes globally isn't the right thing
to do and will introduce noticeable regressions in build time for many
classes of users for no reason.

Ross