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

[Cedric Bosdonnat <cbosdonnat@suse.com>]

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