Mailing List Archive: Xen: Devel

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

Index | Next | Previous | View Threaded

olaf at aepfle

Jun 11, 2012, 8:56 AM

Post #1 of 6 (85 views)
Permalink

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

# HG changeset patch
# User Olaf Hering <olaf [at] aepfle>
# 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 [at] aepfle>

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

_______________________________________________
Xen-devel mailing list
Xen-devel [at] lists
http://lists.xen.org/xen-devel

Ian.Campbell at citrix

Jun 12, 2012, 8:14 AM

Post #2 of 6 (79 views)
Permalink

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

On Mon, 2012-06-11 at 16:56 +0100, Olaf Hering wrote:
> # HG changeset patch
> # User Olaf Hering <olaf [at] aepfle>
> # 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 [at] aepfle>
>
> 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 [at] lists
http://lists.xen.org/xen-devel

olaf at aepfle

Jun 13, 2012, 12:58 AM

Post #3 of 6 (78 views)
Permalink

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

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

_______________________________________________
Xen-devel mailing list
Xen-devel [at] lists
http://lists.xen.org/xen-devel

Ian.Campbell at citrix

Jun 13, 2012, 1:06 AM

Post #4 of 6 (78 views)
Permalink

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

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 [at] lists
http://lists.xen.org/xen-devel

olaf at aepfle

Jun 13, 2012, 6:13 AM

Post #5 of 6 (78 views)
Permalink

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

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

_______________________________________________
Xen-devel mailing list
Xen-devel [at] lists
http://lists.xen.org/xen-devel

Ian.Campbell at citrix

Jun 26, 2012, 9:19 AM

Post #6 of 6 (68 views)
Permalink

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

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.

_______________________________________________
Xen-devel mailing list
Xen-devel [at] lists
http://lists.xen.org/xen-devel

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads