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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Wed, 2012-06-13 at 08:58 +0100, Olaf Hering wrote:
> 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.

F<..> just means "format as a filename i.e. italics", it doesn't turn
into an actual link even in html. I should have said "reference" rather
than "link" I think.

> > > +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.

Perhaps we should be splitting the misc dir up into user and dev etc?

> 
> > > 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



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel