Re: [Xen-devel] [PATCH 2/2] docs: Fix links in html generation of man pages

[Anthony PERARD <anthony.perard@xxxxxxxxxx>]

On Tue, Jan 15, 2019 at 05:07:49PM +0000, Ian Jackson wrote:
> Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of 
> man pages"):
> > On Tue, Jan 15, 2019 at 03:57:35PM +0000, Ian Jackson wrote:
> > > Do you have an example of the resulting output ?  You could put it on
> > > xenbits and then it would be easy to diff it.
> > 
> > Maybe: https://xenbits.xenproject.org/people/aperard/2019/man/
> 
> Thanks.
> 
> > But here is a sample
> 
> This all looks good to me.
> 
> > (the only not working link will be in
> > xl-disk-configuration, all other links works like shown in the diff of
> > xl.cfg):
> 
> I looked at the source and it says:
> 
>   Virtual device as seen by the guest (also referred to as guest drive
>   designation in some specifications).  L<xen-vbd-interface(7)>
> 
> which is missing some joining word like `See', and a full stop, too.
> I still don't know why a cache is needed for it to make it into a
> link.

The cache is just a residual of an internal representation.

What pod2html needs is --podpath, to quote the man:
    "Specify which subdirectories of the podroot contain pod files whose
    HTML converted forms can be linked-to in cross-references."

What isn't said in the manual is that pod2html will not make any
relative link to none-existing .pod files. It's maybe because when we
use L<name> or L<text|name>, "name" is supposed to be a Perl manual
page (see perlpod). pod2html just doesn't generate links if it can't
find that manual page.
The last possible use of L<> is L<text|scheme:...> but that would be
an absolute URL, which isn't what we need. I basically had to trick
pod2html into generating relative links.

> Can we do some seddery to this too ?

I think we would have to change approach to fix that last link. Maybe
sed the input to have absolute urls, then sed the output to change them
into relative ones. That would make the patch easier to understand, I
think.

-- 
Anthony PERARD

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel