Re: [PATCH] docs: install documentation which is referenced in man pages

[Olaf Hering <olaf@aepfle.de>]

On Tue, Jun 12, Ian Campbell wrote:

> On Mon, 2012-06-11 at 16:56 +0100, Olaf Hering wrote:
> > xl.cfg.5 refers to non-existant files named xl-disk-configuration and
> > xl-network-configuration. Adjust to new DOCDIR location.
> 
> The reason for omitting the extension is that it can be .html or .txt
> depending on the context which the link is given in.

How is that link ' F<xl-network-configuration>' supposed to be filled?
I think F refers to a local filename.


> > +DOC_MAN_REFS    := misc/sedf_scheduler_mini-HOWTO.txt \
> > +			misc/xl-disk-configuration.txt \
> > +			misc/vbd-interface.txt \
> > +			misc/xl-network-configuration.markdown
> 
> Any reason not to install the whole of $(DOC_TXT) instead of just this
> subset?

Most of it looks like developer documentation to me. In the end
kexec_and_kdump.txt, vtd.txt and perhaps the xen cmdline docu could be
installed in addition to the files above.

> > diff -r a70b35deb2b5 -r d5280420afc9 docs/man/xl.cfg.pod.5
> > --- a/docs/man/xl.cfg.pod.5
> > +++ b/docs/man/xl.cfg.pod.5
> > @@ -255,13 +255,13 @@ devices which the guest will contain.
> >  
> >  Specifies the disks (both emulated disks and Xen virtual block
> >  devices) which are to be provided to the guest, and what objects on
> > -the they should map to.  See F<docs/misc/xl-disk-configuration.txt>.
> > +the they should map to.  See F<@DOCDIR@/xl-disk-configuration.txt>.
> >  
> >  =item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
> >  
> >  Specifies the networking provision (both emulated network adapters,
> >  and Xen virtual interfaces) to provided to the guest.  See
> > -F<docs/misc/xl-network-configuration.markdown>.
> > +F<@DOCDIR@/xl-network-configuration.markdown>.
> 
> I'm slightly concerned about what all this will mean for the HTML
> generated docs, in particular the ones hosted at
> http://xenbits.xen.org/docs/unstable/. Currently they aren't actual
> working links there but they do at least reference the real path in the
> source tree.

I think the tool which generates the html files could be smarter and
turn the string 'F<@DOCDIR@' into a html link.

> At the very least it would be simpler to deal with this if the misc part
> of the path was retainined, both in these references and in the actual
> install location (e.g. @DOCDIR@/misc).

I will change that part and put it into a /misc directory.

Olaf