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
