Olaf Hering
2012-Jun-11 15:56 UTC
[PATCH] docs: install documentation which is referenced in man pages
# HG changeset patch
# User Olaf Hering <olaf@aepfle.de>
# 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.
Simplify the pod2man call, merge two sed calls into a single one.
Signed-off-by: Olaf Hering <olaf@aepfle.de>
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
.PHONY: all
all: build
@@ -57,13 +61,17 @@ man-pages:
man1/%.1: man/%.pod.1 Makefile
$(INSTALL_DIR) $(@D)
- $(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed
''s/^man1.//''| \
- sed ''s/.1//''` -s 1 -c "Xen" $< $@
+ sed ''s|@DOCDIR@|$(DOCDIR)|g'' $< | \
+ $(POD2MAN) --release=$(VERSION) \
+ --name=`echo $@ | sed ''s/^man1.//;s/.1//''` \
+ -s 1 -c "Xen" - $@
man5/%.5: man/%.pod.5 Makefile
$(INSTALL_DIR) $(@D)
- $(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed
''s/^man5.//''| \
- sed ''s/.5//''` -s 5 -c "Xen" $< $@
+ sed ''s|@DOCDIR@|$(DOCDIR)|g'' $< | \
+ $(POD2MAN) --release=$(VERSION) \
+ --name=`echo $@ | sed ''s/^man5.//;s/.5//''` \
+ -s 5 -c "Xen" - $@
.PHONY: clean
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>.
=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING",
...]>
@@ -652,7 +652,7 @@ frequency changes.
=back
-Please see F<docs/misc/tscmode.txt> for more information on this option.
+Please see F<@DOCDIR@/tscmode.txt> for more information on this option.
=item B<localtime=BOOLEAN>
@@ -1062,9 +1062,11 @@ See L<qemu(1)> for more information.
=item L<xl(1)>
-=item F<xl-disk-configuration>
+=item F<@DOCDIR@/tscmode.txt>
-=item F<xl-network-configuration>
+=item F<@DOCDIR@/xl-disk-configuration.txt>
+
+=item F<@DOCDIR@/xl-network-configuration.markdown>
=back
@@ -1072,7 +1074,6 @@ See L<qemu(1)> for more information.
F</etc/xen/NAME.cfg>
F</var/xen/dump/NAME>
-F<docs/misc/tscmode.txt>
=head1 BUGS
diff -r a70b35deb2b5 -r d5280420afc9 docs/man/xl.pod.1
--- a/docs/man/xl.pod.1
+++ b/docs/man/xl.pod.1
@@ -876,7 +876,7 @@ Restrict output to domains in the specif
Set or get Simple EDF (Earliest Deadline First) scheduler parameters. This
scheduler provides weighted CPU sharing in an intuitive way and uses
realtime-algorithms to ensure time guarantees. For more information see
-docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
+F<@DOCDIR@/sedf_scheduler_mini-HOWTO.txt> in the Xen distribution.
B<OPTIONS>
diff -r a70b35deb2b5 -r d5280420afc9 docs/man/xm.pod.1
--- a/docs/man/xm.pod.1
+++ b/docs/man/xm.pod.1
@@ -774,7 +774,7 @@ no upper cap.
Set Simple EDF (Earliest Deadline First) scheduler parameters. This
scheduler provides weighted CPU sharing in an intuitive way and uses
realtime-algorithms to ensure time guarantees. For more information
-see docs/misc/sedf_scheduler_mini-HOWTO.txt in the Xen distribution.
+see F<@DOCDIR@/sedf_scheduler_mini-HOWTO.txt> in the Xen distribution.
B<PARAMETERS>
diff -r a70b35deb2b5 -r d5280420afc9 docs/misc/xl-disk-configuration.txt
--- a/docs/misc/xl-disk-configuration.txt
+++ b/docs/misc/xl-disk-configuration.txt
@@ -97,7 +97,7 @@ vdev
Description: Virtual device as seen by the guest (also
referred to as guest drive designation in some
- specifications). See docs/misc/vbd-interface.txt.
+ specifications). See @DOCDIR@/vbd-interface.txt.
Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
above specification for further details.
Deprecated values: None
Ian Campbell
2012-Jun-12 15:14 UTC
Re: [PATCH] docs: install documentation which is referenced in man pages
On Mon, 2012-06-11 at 16:56 +0100, Olaf Hering wrote:> # HG changeset patch > # User Olaf Hering <olaf@aepfle.de> > # 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@aepfle.de> > > 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.markdownAny 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.
Olaf Hering
2012-Jun-13 07:58 UTC
Re: [PATCH] docs: install documentation which is referenced in man pages
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
Ian Campbell
2012-Jun-13 08:06 UTC
Re: [PATCH] docs: install documentation which is referenced in man pages
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
Olaf Hering
2012-Jun-13 13:13 UTC
Re: [PATCH] docs: install documentation which is referenced in man pages
On Wed, Jun 13, Ian Campbell wrote:> 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.So how should I handle that part then? Leaving it alone for the time being? That would be fine with me.> > > > +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?I think that will just cause unneeded churn. The list of user documentation files can be maintained in Makefile variable such as DOCS_TO_INSTALL. Olaf
Ian Campbell
2012-Jun-26 16:19 UTC
Re: [PATCH] docs: install documentation which is referenced in man pages
On Wed, 2012-06-13 at 14:13 +0100, Olaf Hering wrote:> On Wed, Jun 13, Ian Campbell wrote: > > > 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. > > So how should I handle that part then? Leaving it alone for the time > being? That would be fine with me.Lets leave it for now.> > > > > +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? > > I think that will just cause unneeded churn. The list of user > documentation files can be maintained in Makefile variable such as > DOCS_TO_INSTALL.OK.