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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-06-11 at 16:56 +0100, Olaf Hering wrote:
> # HG changeset patch
> # User Olaf Hering <olaf@xxxxxxxxx>
> # Date 1339429861 -7200
> # Node ID d5280420afc9c1e52d8e8bf35bb36512120e0556
> # Parent  a70b35deb2b5592cc1b2363860f21bb2c7049885
> docs: install documentation which is referenced in man pages
> 
> Currently the various man pages refer to some other documentation files
> in the source tree. For example, xl.cfg.5 refers to
> docs/misc/xl-disk-configuration.txt, which in turn refers to
> docs/misc/vbd-interface.txt.
> 
> Since these files are not packaged, the provided documentation appears
> incomplete. Fix this by installing the additional files into DOCDIR and
> also adjust the contents of the man pages and affected documentation
> files to contain the full path of DOCDIR.
> 
> 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.

> Simplify the pod2man call, merge two sed calls into a single one.
> 
> Signed-off-by: Olaf Hering <olaf@xxxxxxxxx>
> 
> diff -r a70b35deb2b5 -r d5280420afc9 docs/Makefile
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -21,6 +21,10 @@ DOC_TXT         := $(patsubst %.txt,txt/
>                  $(patsubst man/%.pod.1,txt/man/%.1.txt,$(DOC_MAN1SRC)) \
>                  $(patsubst man/%.pod.5,txt/man/%.5.txt,$(DOC_MAN5SRC))
>  
> +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?

>  clean:
> @@ -89,6 +97,9 @@ install: all
>       cp -dR man1 $(DESTDIR)$(MANDIR)
>       cp -dR man5 $(DESTDIR)$(MANDIR)
>       [ ! -d html ] || cp -dR html $(DESTDIR)$(DOCDIR)
> +     for i in $(DOC_MAN_REFS) ; do \
> +             sed 's|@DOCDIR@|$(DOCDIR)|g' $$i > 
> $(DESTDIR)$(DOCDIR)/`basename $$i` ; \
> +             done
>  
>  html/index.html: $(DOC_HTML) ./gen-html-index INDEX
>       perl -w -- ./gen-html-index -i INDEX html $(DOC_HTML)
> 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.

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

Ian.



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