[PATCH] docs: turn links to docs/* into absolute path

[PATCH] docs: turn links to docs/* into absolute path

[Cédric Bosdonnat]

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>.
 
 =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)
 ])
-- 
2.11.0


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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Andrew Cooper]

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

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Cedric Bosdonnat]

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
> 

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Ian Jackson]

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.

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Cedric Bosdonnat]

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

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Wei Liu]

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.

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Wei Liu]

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.

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

Re: [PATCH] docs: turn links to docs/* into absolute path

[Cedric Bosdonnat]

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

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