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

[Wei Liu <wei.liu2@citrix.com>]

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