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

[Ian Jackson <ian.jackson@xxxxxxxxxxxxx>]

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@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel