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
