| Message ID | 20161208165612.14223-1-cbosdonnat@suse.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On 08/12/16 16:56, Cédric Bosdonnat wrote: > From a user point of view, when reading things like "See > docs/misc/....txt" in a man page, it is not obvious to find the > location of that file. Use $docdir to turn these into absolute > paths. > > Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> Hmm. I can see your point and we really should improve the man pages. However, this change will cause http://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html to point at a local file rather than something which is reasonably accessable from the webroot. Another issue to consider is that some packagers only package the manpages, not the other misc text content. (I would argue that none of the manpages should refer to misc text content in the first place). The web docs are already in a fairly poor state in this regards, so I don't know whether it might just be better to taking this patch. ~Andrew
On Thu, Dec 08, 2016 at 05:56:12PM +0100, Cédric Bosdonnat wrote: > From a user point of view, when reading things like "See > docs/misc/....txt" in a man page, it is not obvious to find the > location of that file. Use $docdir to turn these into absolute > paths. > > Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> > --- > docs/man/xl.cfg.pod.5.in | 16 ++++++++-------- > docs/man/xl.pod.1.in | 2 +- > m4/paths.m4 | 3 +++ > 3 files changed, 12 insertions(+), 9 deletions(-) > > diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in > index 21b58bc21e..29a012b794 100644 > --- a/docs/man/xl.cfg.pod.5.in > +++ b/docs/man/xl.cfg.pod.5.in > @@ -185,7 +185,7 @@ host cpus and memory. In that case, the soft affinity of all the vcpus > of the domain will be set to the pcpus belonging to the NUMA nodes > chosen during placement. > > -For more details, see F<docs/misc/xl-numa-placement.markdown>. > +For more details, see L</@XEN_DOC_DIR@/docs/misc/xl-numa-placement.markdown>. I think this is a sensible thing to do. But should you omit the leading "/" in all instances? Wei.
On Thu, 2016-12-08 at 17:59 +0000, Wei Liu wrote: > On Thu, Dec 08, 2016 at 05:56:12PM +0100, Cédric Bosdonnat wrote: > > From a user point of view, when reading things like "See > > docs/misc/....txt" in a man page, it is not obvious to find the > > location of that file. Use $docdir to turn these into absolute > > paths. > > > > Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> > > --- > > docs/man/xl.cfg.pod.5.in | 16 ++++++++-------- > > docs/man/xl.pod.1.in | 2 +- > > m4/paths.m4 | 3 +++ > > 3 files changed, 12 insertions(+), 9 deletions(-) > > > > diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in > > index 21b58bc21e..29a012b794 100644 > > --- a/docs/man/xl.cfg.pod.5.in > > +++ b/docs/man/xl.cfg.pod.5.in > > @@ -185,7 +185,7 @@ host cpus and memory. In that case, the soft affinity of all the vcpus > > of the domain will be set to the pcpus belonging to the NUMA nodes > > chosen during placement. > > > > -For more details, see F<docs/misc/xl-numa-placement.markdown>. > > +For more details, see L</@XEN_DOC_DIR@/docs/misc/xl-numa-placement.markdown>. > > I think this is a sensible thing to do. But should you omit the leading > "/" in all instances? If I omit this one, the head / seems to be eaten as this has some special meaning in pod format. -- Cedric
On Thu, 2016-12-08 at 17:59 +0000, Andrew Cooper wrote: > On 08/12/16 16:56, Cédric Bosdonnat wrote: > > From a user point of view, when reading things like "See > > docs/misc/....txt" in a man page, it is not obvious to find the > > location of that file. Use $docdir to turn these into absolute > > paths. > > > > Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> > > Hmm. I can see your point and we really should improve the man pages. > > However, this change will cause > http://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html to point at a > local file rather than something which is reasonably accessable from the > webroot. Oh, I didn't think about this one. You're right! > Another issue to consider is that some packagers only package the > manpages, not the other misc text content. (I would argue that none of > the manpages should refer to misc text content in the first place). So wouldn't the best thing to do rather be converting the misc text content into proper man pages so that everyone gets it? And we could also easily jump from one man page to the other using tools like the Vim plugin (I'm sure other editors has the same sort of tool). -- Cedric > The web docs are already in a fairly poor state in this regards, so I > don't know whether it might just be better to taking this patch. > > ~Andrew >
Hi, Cedric et al. I like the idea of tidying this up. Thanks for the
patch, which (with some small changes) will be a good idea.
Cedric Bosdonnat writes ("Re: [Xen-devel] [PATCH] docs: turn links to docs/* into absolute path"):
> On Thu, 2016-12-08 at 17:59 +0000, Andrew Cooper wrote:
> > However, this change will cause
> > http://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html to point at a
> > local file rather than something which is reasonably accessable from the
> > webroot.
>
> Oh, I didn't think about this one. You're right!
This would be solved by making the path configurable at build time.
We would have the docs generator use an appropriate (perhaps empty)
prefix.
Can I suggest that your first patch should replace each instance of
docs/misc/ too ? I mean, that you should introduce XEN_DOCMISC_DIR or
something, which subsumes docs/misc/.
That way when the docs are installed by a packager in
/usr/share/doc/xen/ there doesn't have to be this weird docs/misc/
path component.
> > Another issue to consider is that some packagers only package the
> > manpages, not the other misc text content. (I would argue that none of
> > the manpages should refer to misc text content in the first place).
I think those packagers are Doing It Wrong.
> So wouldn't the best thing to do rather be converting the misc text content
> into proper man pages so that everyone gets it? And we could also easily
> jump from one man page to the other using tools like the Vim plugin
> (I'm sure other editors has the same sort of tool).
Well, that would be nice. It would certainly be nice for more of the
docs to be in a more sophisticated format.
But do we want to insist on all new documentation being written in POD
or markdown ? That might reduce the amount of documentation we get.
Thanks,
Ian.
On Fri, 2016-12-09 at 11:25 +0000, Ian Jackson wrote: > Hi, Cedric et al. I like the idea of tidying this up. Thanks for the > patch, which (with some small changes) will be a good idea. > > Cedric Bosdonnat writes ("Re: [Xen-devel] [PATCH] docs: turn links to docs/* into absolute path"): > > On Thu, 2016-12-08 at 17:59 +0000, Andrew Cooper wrote: > > > However, this change will cause > > > http://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html to point at a > > > local file rather than something which is reasonably accessable from the > > > webroot. > > > > Oh, I didn't think about this one. You're right! > > This would be solved by making the path configurable at build time. > We would have the docs generator use an appropriate (perhaps empty) > prefix. > > Can I suggest that your first patch should replace each instance of > docs/misc/ too ? I mean, that you should introduce XEN_DOCMISC_DIR or > something, which subsumes docs/misc/. > > That way when the docs are installed by a packager in > /usr/share/doc/xen/ there doesn't have to be this weird docs/misc/ > path component. Good idea! > > > Another issue to consider is that some packagers only package the > > > manpages, not the other misc text content. (I would argue that none of > > > the manpages should refer to misc text content in the first place). > > I think those packagers are Doing It Wrong. Hehe ;) let's not care about that case then. > > So wouldn't the best thing to do rather be converting the misc text content > > into proper man pages so that everyone gets it? And we could also easily > > jump from one man page to the other using tools like the Vim plugin > > (I'm sure other editors has the same sort of tool). > > Well, that would be nice. It would certainly be nice for more of the > docs to be in a more sophisticated format. I'm currently moving a few of the misc docs into man pages. Already done * xl-disk-configuration.txt (plus reformatting in POD) * vbd-interface.txt (reformatted too) * xl-disk-configuration.markdown I can continue with these for sure: it's rather easy to do and wouldn't take too long to get finished. > But do we want to insist on all new documentation being written in POD > or markdown ? That might reduce the amount of documentation we get. I see pandoc knows how to convert markdown to man... may be I should tweak the makefile to support that. Honestly between a random formatting of a text file (those we have are rather nice) and a simple format like POD or markdown, I think the format isn't the barrier to documentation writing. -- Cedric
On Fri, Dec 09, 2016 at 01:02:10PM +0100, Cedric Bosdonnat wrote: > On Fri, 2016-12-09 at 11:25 +0000, Ian Jackson wrote: > > Hi, Cedric et al. I like the idea of tidying this up. Thanks for the > > patch, which (with some small changes) will be a good idea. > > > > Cedric Bosdonnat writes ("Re: [Xen-devel] [PATCH] docs: turn links to docs/* into absolute path"): > > > On Thu, 2016-12-08 at 17:59 +0000, Andrew Cooper wrote: > > > > However, this change will cause > > > > http://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html to point at a > > > > local file rather than something which is reasonably accessable from the > > > > webroot. > > > > > > Oh, I didn't think about this one. You're right! > > > > This would be solved by making the path configurable at build time. > > We would have the docs generator use an appropriate (perhaps empty) > > prefix. > > > > Can I suggest that your first patch should replace each instance of > > docs/misc/ too ? I mean, that you should introduce XEN_DOCMISC_DIR or > > something, which subsumes docs/misc/. > > > > That way when the docs are installed by a packager in > > /usr/share/doc/xen/ there doesn't have to be this weird docs/misc/ > > path component. > > Good idea! > > > > > Another issue to consider is that some packagers only package the > > > > manpages, not the other misc text content. (I would argue that none of > > > > the manpages should refer to misc text content in the first place). > > > > I think those packagers are Doing It Wrong. > > Hehe ;) let's not care about that case then. > > > > So wouldn't the best thing to do rather be converting the misc text content > > > into proper man pages so that everyone gets it? And we could also easily > > > jump from one man page to the other using tools like the Vim plugin > > > (I'm sure other editors has the same sort of tool). > > > > Well, that would be nice. It would certainly be nice for more of the > > docs to be in a more sophisticated format. > > I'm currently moving a few of the misc docs into man pages. Already done > * xl-disk-configuration.txt (plus reformatting in POD) > * vbd-interface.txt (reformatted too) > * xl-disk-configuration.markdown > > I can continue with these for sure: it's rather easy to do and wouldn't take > too long to get finished. > > > But do we want to insist on all new documentation being written in POD > > or markdown ? That might reduce the amount of documentation we get. > Markdown should be fine. POD not so much... Wei.
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in index 21b58bc21e..29a012b794 100644 --- a/docs/man/xl.cfg.pod.5.in +++ b/docs/man/xl.cfg.pod.5.in @@ -185,7 +185,7 @@ host cpus and memory. In that case, the soft affinity of all the vcpus of the domain will be set to the pcpus belonging to the NUMA nodes chosen during placement. -For more details, see F<docs/misc/xl-numa-placement.markdown>. +For more details, see L</@XEN_DOC_DIR@/docs/misc/xl-numa-placement.markdown>. =back @@ -480,18 +480,18 @@ 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 host they should map to. See F<docs/misc/xl-disk-configuration.txt>. +the host they should map to. See L</@XEN_DOC_DIR@/docs/misc/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>. +L</@XEN_DOC_DIR@/docs/misc/xl-network-configuration.markdown>. =item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]> Specifies the virtual trusted platform module to be -provided to the guest. Please see F<docs/misc/vtpm.txt> +provided to the guest. Please see L</@XEN_DOC_DIR@/docs/misc/vtpm.txt> for more details. Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> @@ -604,7 +604,7 @@ Specifies the virtual channels to be provided to the guest. A channel is a low-bandwidth, bidirectional byte stream, which resembles a serial link. Typical uses for channels include transmitting VM configuration after boot and signalling to in-guest agents. Please see -F<docs/misc/channels.txt> for more details. +L</@XEN_DOC_DIR@/docs/misc/channels.txt> for more details. Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> settings. Leading and trailing whitespace is ignored in both KEY and @@ -1464,7 +1464,7 @@ determined in the similar way to that of B<default> TSC mode. =back -Please see F<docs/misc/tscmode.txt> for more information on this option. +Please see L</@XEN_DOC_DIR@/docs/misc/tscmode.txt> for more information on this option. =item B<localtime=BOOLEAN> @@ -1895,7 +1895,7 @@ specified, enabling the use of XenServer PV drivers in the guest. =back This parameter only takes effect when device_model_version=qemu-xen. -See F<docs/misc/pci-device-reservations.txt> for more information. +See L</@XEN_DOC_DIR@/docs/misc/pci-device-reservations.txt> for more information. =back @@ -2034,7 +2034,7 @@ natively or via hardware backwards compatibility support. =item F<xl-network-configuration> -=item F<docs/misc/tscmode.txt> +=item L</@XEN_DOC_DIR@/docs/misc/tscmode.txt> =back diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in index 8e2aa5b5af..22f24607a1 100644 --- a/docs/man/xl.pod.1.in +++ b/docs/man/xl.pod.1.in @@ -1354,7 +1354,7 @@ How the device should be presented to the guest domain; for example "hdc". the target path in the backend domain (usually domain 0) to be exported; Can be a block device or a file etc. See B<target> in -F<docs/misc/xl-disk-configuration.txt>. +L</@XEN_DOC_DIR@/docs/misc/xl-disk-configuration.txt>. =back diff --git a/m4/paths.m4 b/m4/paths.m4 index 722a8aa4a9..9a6ede4a11 100644 --- a/m4/paths.m4 +++ b/m4/paths.m4 @@ -140,4 +140,7 @@ AC_SUBST(XEN_PAGING_DIR) XEN_DUMP_DIR=$xen_dumpdir_path AC_SUBST(XEN_DUMP_DIR) + +XEN_DOC_DIR=$docdir +AC_SUBST(XEN_DOC_DIR) ])
From a user point of view, when reading things like "See docs/misc/....txt" in a man page, it is not obvious to find the location of that file. Use $docdir to turn these into absolute paths. Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> --- docs/man/xl.cfg.pod.5.in | 16 ++++++++-------- docs/man/xl.pod.1.in | 2 +- m4/paths.m4 | 3 +++ 3 files changed, 12 insertions(+), 9 deletions(-)