[BUG] docs: our man page generation uses http://man.he.net/ by default which causes broken links. It should be changed to point to a relative path

[BUG] docs: our man page generation uses http://man.he.net/ by default which causes broken links. It should be changed to point to a relative path

[Lars Kurth]

Hi all,

most of our man pages on pretty much all releases from 4.2 contain broken links. 

For example:
In https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html the source contains:

"For more details, see L<xl-numa-placement(7)>." 
Maps onto http://man.he.net/man7/xl-numa-placement  (does not exist)

“See L<http://man.he.net/man5/xl-disk-configuration> for more details.” 
Maps onto http://man.he.net/man5/xl-disk-configuration (does not exist)

Etc.

There seem to be two issues:
* The root path http://man.he.net, which is incorrect
* The resolution of filenames to man<x>/<name>: should be man/<name>.<x>.html

Probably we need to feed some arguments to probably we need to feed some arguments 
to pod2html in order to generate the correct urls. See  https://perldoc.perl.org/pod2html.html 
(maybe we need we need –htmldir). For our docs build, this should probably go to 
https://xenbits.xen.org/docs/unstable/man/ while for local installs to 
${prefix}/share/doc/xen/html/man or something like it.

I had a look to see whether I can fix this, but that seems a little too complex for me

Regards
Lars

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

Re: [BUG] docs: our man page generation uses http://man.he.net/ by default which causes broken links. It should be changed to point to a relative path

[Lars Kurth]

On 02/08/2018, 12:24, "Lars Kurth" <lars.kurth@citrix.com> wrote:

    Hi all,
    
    most of our man pages on pretty much all releases from 4.2 contain broken links. 
    
    For example:
    In https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html the source contains:
    
    "For more details, see L<xl-numa-placement(7)>." 
    Maps onto http://man.he.net/man7/xl-numa-placement  (does not exist)
    
    “See L<http://man.he.net/man5/xl-disk-configuration> for more details.” 

That should read - copy and paste
“See L<xl-disk-configuration(5)> for more details.”

    Maps onto http://man.he.net/man5/xl-disk-configuration (does not exist)
    
    Etc.
    
    There seem to be two issues:
    * The root path http://man.he.net, which is incorrect
    * The resolution of filenames to man<x>/<name>: should be man/<name>.<x>.html
    
    Probably we need to feed some arguments to probably we need to feed some arguments 
    to pod2html in order to generate the correct urls. See  https://perldoc.perl.org/pod2html.html 
    (maybe we need we need –htmldir). For our docs build, this should probably go to 
    https://xenbits.xen.org/docs/unstable/man/ while for local installs to 
    ${prefix}/share/doc/xen/html/man or something like it.
    
    I had a look to see whether I can fix this, but that seems a little too complex for me
    
    Regards
    Lars
    
    

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

Re: [BUG] docs: our man page generation uses http://man.he.net/ by default which causes broken links. It should be changed to point to a relative path

[Lars Kurth]

Ping!
Adding Ian Jackson specifically - we should really fix this for 4.12
Regards
Lars

> On 2 Aug 2018, at 12:24, Lars Kurth <lars.kurth@citrix.com> wrote:
> 
> Hi all,
> 
> most of our man pages on pretty much all releases from 4.2 contain broken links. 
> 
> For example:
> In https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html the source contains:
> 
> "For more details, see L<xl-numa-placement(7)>." 
> Maps onto http://man.he.net/man7/xl-numa-placement  (does not exist)
> 
> “See L<http://man.he.net/man5/xl-disk-configuration> for more details.” 
> Maps onto http://man.he.net/man5/xl-disk-configuration (does not exist)
> 
> Etc.
> 
> There seem to be two issues:
> * The root path http://man.he.net, which is incorrect
> * The resolution of filenames to man<x>/<name>: should be man/<name>.<x>.html
> 
> Probably we need to feed some arguments to probably we need to feed some arguments 
> to pod2html in order to generate the correct urls. See  https://perldoc.perl.org/pod2html.html 
> (maybe we need we need –htmldir). For our docs build, this should probably go to 
> https://xenbits.xen.org/docs/unstable/man/ while for local installs to 
> ${prefix}/share/doc/xen/html/man or something like it.
> 
> I had a look to see whether I can fix this, but that seems a little too complex for me
> 
> Regards
> Lars
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xenproject.org
> https://lists.xenproject.org/mailman/listinfo/xen-devel


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

Re: [BUG] docs: our man page generation uses http://man.he.net/ by default which causes broken links. It should be changed to point to a relative path

[Anthony PERARD]

> > On 2 Aug 2018, at 12:24, Lars Kurth <lars.kurth@citrix.com> wrote:
> > 
> > Hi all,
> > 
> > most of our man pages on pretty much all releases from 4.2 contain broken links. 
> > 
> > For example:
> > In https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html the source contains:
> > 
> > "For more details, see L<xl-numa-placement(7)>." 
> > Maps onto http://man.he.net/man7/xl-numa-placement  (does not exist)
> > 
> > “See L<http://man.he.net/man5/xl-disk-configuration> for more details.” 
> > Maps onto http://man.he.net/man5/xl-disk-configuration (does not exist)
> > 
> > Etc.
> > 
> > There seem to be two issues:
> > * The root path http://man.he.net, which is incorrect
> > * The resolution of filenames to man<x>/<name>: should be man/<name>.<x>.html
> > 
> > Probably we need to feed some arguments to probably we need to feed some arguments 
> > to pod2html in order to generate the correct urls. See  https://perldoc.perl.org/pod2html.html 
> > (maybe we need we need –htmldir). For our docs build, this should probably go to 
> > https://xenbits.xen.org/docs/unstable/man/ while for local installs to 
> > ${prefix}/share/doc/xen/html/man or something like it.
> > 
> > I had a look to see whether I can fix this, but that seems a little too complex for me

I've managed to do something about it, and it is indeed complex. But
maybe pod2html isn't the right tool. Anyway, I have got two patchs to
follow.

-- 
Anthony PERARD

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

[PATCH 1/2] man: Fix links in xl(1)

[Anthony PERARD]

All links to other manpages should contain the man section number.

Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>
---
 docs/man/xl.1.pod.in | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/man/xl.1.pod.in b/docs/man/xl.1.pod.in
index 18006880d6..4310fcd818 100644
--- a/docs/man/xl.1.pod.in
+++ b/docs/man/xl.1.pod.in
@@ -905,7 +905,7 @@ claimed for domains.
 
 =item B<outstanding_claims>
 
-When a claim call is done (see L<xl.conf>) a reservation for a specific
+When a claim call is done (see L<xl.conf(5)>) a reservation for a specific
 amount of pages is set and also a global value is incremented. This
 global value (outstanding_claims) is then reduced as the domain's memory
 is populated and eventually reaches zero. Most of the time the value will
@@ -1458,7 +1458,7 @@ List virtual Trusted Platform Modules for a domain.
 
 Creates a new vdispl device in the domain specified by I<domain-id>.
 I<vdispl-device> describes the device to attach, using the same format as the
-B<vdispl> string in the domain config file. See L<xl.cfg> for
+B<vdispl> string in the domain config file. See L<xl.cfg(5)> for
 more information.
 
 B<NOTES>
@@ -1500,7 +1500,7 @@ List virtual displays for a domain.
 
 Creates a new vsnd device in the domain specified by I<domain-id>.
 I<vsnd-item>'s describe the vsnd device to attach, using the same format as the
-B<VSND_ITEM_SPEC> string in the domain config file. See L<xl.cfg> for
+B<VSND_ITEM_SPEC> string in the domain config file. See L<xl.cfg(5)> for
 more information.
 
 B<EXAMPLE>
@@ -1974,7 +1974,7 @@ Transcendent Memory.
 
 The following man pages:
 
-L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)>
+L<xl.cfg(5)>, L<xlcpupool.cfg(5)>, L<xentop(1)>, L<xl-disk-configuration(5)>
 L<xl-network-configuration(5)>
 
 And the following documents on the xen.org website:
-- 
Anthony PERARD


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

[PATCH 2/2] docs: Fix links in html generation of man pages

[Anthony PERARD]

Currently, all links to other man pages are sent to
http://man.he.net/man$mansection/$manpage, but that site doesn't have
Xen man pages, so all links to other Xen man pages are broken.

In order to fix that, this is going to be a bit complex.

First, we need to teach pod2html on where other .pod files can be found,
otherwise it isn't going make any links to our pages. This is done with
--podpath.

Second, pod2html doesn't actually understand our format
"$manpage.$mansection.pod". But instead of teaching it (which is
probably impossible) we are going to modify our .pod files in order to
tell pod2html which file to look for. This is done with the sed command
by transforming for example: "L<xl.conf(5)>" to "L<xl.conf(5)|xl.conf.5>".

Last but not least, in order to have relative links to the other
generated man page, we are going against the rules, we are going to use
"--htmlroot=." so that pod2html doesn't prepand "/" to all "relative"
links. We are also going to `cd` into the "man" dir and set podpath to
"." so that pod2html is going to generate relative links to other pod
file in the form "./$man" insteadof "man/$man" or "../$man" with other
compination of options. The result of --podpath + --podroot can be check
in pod2html's cache file "pod2html.tmp".

All of this is going to generate links in the form "./$html_manpage".

But all of this doesn't work for xen-vbd-interface(7), because it's not
a pod file... maybe we could generate pod2html's cache (pod2html.tmp)
file to add en entry.

Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>

---
Or maybe we could generate the html files, and `sed` them to fix all
links to other xen man pages.
---
 docs/Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index 013fa8eede..cbc61e3f1d 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -96,7 +96,8 @@ endif
 html/man/%.$(1).html: man/%.$(1).pod Makefile
 ifneq ($(POD2HTML),)
 	@$(INSTALL_DIR) $$(@D)
-	$(POD2HTML) --infile=$$< --outfile=$$@
+	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|\1.\2>%g' $$< | \
+		(cd man; $(POD2HTML) --podpath=. --htmlroot=. --outfile=../$$@)
 else
 	@echo "pod2html not installed; skipping $$@"
 endif
-- 
Anthony PERARD


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

Re: [PATCH 1/2] man: Fix links in xl(1)

[Ian Jackson]

Anthony PERARD writes ("[PATCH 1/2] man: Fix links in xl(1)"):
> All links to other manpages should contain the man section number.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

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

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

[Ian Jackson]

Anthony PERARD writes ("[PATCH 2/2] docs: Fix links in html generation of man pages"):
> Currently, all links to other man pages are sent to
> http://man.he.net/man$mansection/$manpage, but that site doesn't have
> Xen man pages, so all links to other Xen man pages are broken.
> 
> In order to fix that, this is going to be a bit complex.

Cor.  Thanks for digging.  Your approach seems no worse than is to be
expected under the circumstances.  (So, well done.)

Do you have an example of the resulting output ?  You could put it on
xenbits and then it would be easy to diff it.

> But all of this doesn't work for xen-vbd-interface(7), because it's not
> a pod file... maybe we could generate pod2html's cache (pod2html.tmp)
> file to add en entry.

I'm not sure I understand why pod2html needs to care about this...

Ian.

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

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

[Anthony PERARD]

On Tue, Jan 15, 2019 at 03:57:35PM +0000, Ian Jackson wrote:
> Anthony PERARD writes ("[PATCH 2/2] docs: Fix links in html generation of man pages"):
> > Currently, all links to other man pages are sent to
> > http://man.he.net/man$mansection/$manpage, but that site doesn't have
> > Xen man pages, so all links to other Xen man pages are broken.
> > 
> > In order to fix that, this is going to be a bit complex.
> 
> Cor.  Thanks for digging.  Your approach seems no worse than is to be
> expected under the circumstances.  (So, well done.)
> 
> 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/

But here is a sample (the only not working link will be in
xl-disk-configuration, all other links works like shown in the diff of
xl.cfg):

--- html/man/xl-disk-configuration.5.html	2019-01-15 16:04:18.913012326 +0000
+++ html-man-v1/xl-disk-configuration.5.html	2019-01-15 16:01:35.922122233 +0000
@@ -150,7 +150,7 @@
 <dt id="Description2">Description</dt>
 <dd>
 
-<p>Virtual device as seen by the guest (also referred to as guest drive designation in some specifications). <a href="http://man.he.net/man7/xen-vbd-interface">xen-vbd-interface(7)</a></p>
+<p>Virtual device as seen by the guest (also referred to as guest drive designation in some specifications). <a>xen-vbd-interface(7)</a></p>
 
 </dd>
 <dt id="Supported-values2">Supported values</dt>

--- html/man/xl.cfg.5.html	2019-01-15 16:04:19.146342181 +0000
+++ html-man-v1/xl.cfg.5.html	2019-01-15 16:01:36.222117709 +0000
@@ -274,7 +274,7 @@
 
 <p>If this option is not specified (and <b>cpus=</b> is not specified either), libxl automatically tries to place the guest on the least possible number of nodes. A heuristic approach is used for choosing the best node (or set of nodes), with the goal of maximizing performance for the guest and, at the same time, achieving efficient utilization of host CPUs and memory. In that case, the soft affinity of all the vCPUs of the domain will be set to host CPUs belonging to NUMA nodes chosen during placement.</p>
 
-<p>For more details, see <a href="http://man.he.net/man7/xl-numa-placement">xl-numa-placement(7)</a>.</p>
+<p>For more details, see <a href="./xl-numa-placement.7.html">xl-numa-placement(7)</a>.</p>
 
 </dd>
 </dl>
@@ -2651,27 +2651,27 @@
 
 <dl>
 
-<dt id="xl-1"><a href="http://man.he.net/man1/xl">xl(1)</a></dt>
+<dt id="xl-1"><a href="./xl.1.html">xl(1)</a></dt>
 <dd>
 
 </dd>
-<dt id="xl.conf-5"><a href="http://man.he.net/man5/xl.conf">xl.conf(5)</a></dt>
+<dt id="xl.conf-5"><a href="./xl.conf.5.html">xl.conf(5)</a></dt>
 <dd>
 
 </dd>
-<dt id="xlcpupool.cfg-5"><a href="http://man.he.net/man5/xlcpupool.cfg">xlcpupool.cfg(5)</a></dt>
+<dt id="xlcpupool.cfg-5"><a href="./xlcpupool.cfg.5.html">xlcpupool.cfg(5)</a></dt>
 <dd>
 
 </dd>
-<dt id="xl-disk-configuration-5"><a href="http://man.he.net/man5/xl-disk-configuration">xl-disk-configuration(5)</a></dt>
+<dt id="xl-disk-configuration-5"><a href="./xl-disk-configuration.5.html">xl-disk-configuration(5)</a></dt>
 <dd>
 
 </dd>
-<dt id="xl-network-configuration-5"><a href="http://man.he.net/man5/xl-network-configuration">xl-network-configuration(5)</a></dt>
+<dt id="xl-network-configuration-5"><a href="./xl-network-configuration.5.html">xl-network-configuration(5)</a></dt>
 <dd>
 
 </dd>
-<dt id="xen-tscmode-7"><a href="http://man.he.net/man7/xen-tscmode">xen-tscmode(7)</a></dt>
+<dt id="xen-tscmode-7"><a href="./xen-tscmode.7.html">xen-tscmode(7)</a></dt>
 <dd>
 
 </dd>


-- 
Anthony PERARD

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

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

[Ian Jackson]

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.  Can we do some seddery to this too ?


Anyway, this patch of yours is a big improvement, so:

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

I think linkifying that one missing link is a `nice to have' and can
be done now or later as yo like.

Ian.

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

Re: [PATCH 1/2] man: Fix links in xl(1)

[Juergen Gross]

On 15/01/2019 16:54, Ian Jackson wrote:
> Anthony PERARD writes ("[PATCH 1/2] man: Fix links in xl(1)"):
>> All links to other manpages should contain the man section number.
> 
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Release-acked-by: Juergen Gross <jgross@suse.com>


Juergen

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

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

[Juergen Gross]

On 15/01/2019 18:07, 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.  Can we do some seddery to this too ?
> 
> 
> Anyway, this patch of yours is a big improvement, so:
> 
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
> 
> I think linkifying that one missing link is a `nice to have' and can
> be done now or later as yo like.

Release-acked-by: Juergen Gross <jgross@suse.com>


Juergen

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

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

[Anthony PERARD]

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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

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

[Lars Kurth]

> On 15 Jan 2019, at 17:07, Ian Jackson <Ian.Jackson@citrix.com> wrote:
> 
> Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):

snip

> Anyway, this patch of yours is a big improvement, so:
> 
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
> 
> I think linkifying that one missing link is a `nice to have' and can
> be done now or later as yo like.
> 
> Ian.


Indeed it is. Thank you for fixing this
Regards
Lars


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

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

[Ian Jackson]

Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
> 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.

How unhelpful.

> 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.

`https:spong.html' is a valid URL.  It is weird but maybe that
would do ?

Ian.

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

[PATCH 1/2] docs: Fix all links to Xen man pages in html

[Anthony PERARD]

Second try, this time also works for all links to xen-vbd-interface(7).

We don't try anymore to have pod2html generate relative links, instead
we do it ourself.

First, we modify all links to man pages to have what looks like an
absolute URL and pod2html will just write it in the html output.
Absolute URL in POD are in the form L<text|scheme:...> so let's just use
a scheme that isn't real, but easy to find in the resulting html output:
"relative:".

Then we fix the output and remove all the bogus scheme "relative" and
can end up with nice relative links.

Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>
---

Notes:
    New output can be found here:
    https://xenbits.xenproject.org/people/aperard/2019/man-v2/
    
    Diff sample compare to the previous patch:
    
    --- html-man-v1/xl-disk-configuration.5.html	2019-01-15 16:01:35.922122233 +0000
    +++ html/man/xl-disk-configuration.5.html	2019-01-15 18:08:31.859960271 +0000
    @@ -150,7 +150,7 @@
     <dt id="Description2">Description</dt>
     <dd>
    
    -<p>Virtual device as seen by the guest (also referred to as guest drive designation in some specifications). <a>xen-vbd-interface(7)</a></p>
    +<p>Virtual device as seen by the guest (also referred to as guest drive designation in some specifications). <a href="xen-vbd-interface.7.html">xen-vbd-interface(7)</a></p>
    
     </dd>
     <dt id="Supported-values2">Supported values</dt>
    --- html-man-v1/xl.cfg.5.html	2019-01-15 16:01:36.222117709 +0000
    +++ html/man/xl.cfg.5.html	2019-01-15 18:06:36.995207695 +0000
    @@ -2651,27 +2651,27 @@
    
     <dl>
    
    -<dt id="xl-1"><a href="./xl.1.html">xl(1)</a></dt>
    +<dt id="xl-1"><a href="xl.1.html">xl(1)</a></dt>
     <dd>
    
     </dd>
    -<dt id="xl.conf-5"><a href="./xl.conf.5.html">xl.conf(5)</a></dt>
    +<dt id="xl.conf-5"><a href="xl.conf.5.html">xl.conf(5)</a></dt>
     <dd>
    
     </dd>
    -<dt id="xlcpupool.cfg-5"><a href="./xlcpupool.cfg.5.html">xlcpupool.cfg(5)</a></dt>
    +<dt id="xlcpupool.cfg-5"><a href="xlcpupool.cfg.5.html">xlcpupool.cfg(5)</a></dt>
     <dd>
    
     </dd>
    -<dt id="xl-disk-configuration-5"><a href="./xl-disk-configuration.5.html">xl-disk-configuration(5)</a></dt>
    +<dt id="xl-disk-configuration-5"><a href="xl-disk-configuration.5.html">xl-disk-configuration(5)</a></dt>
     <dd>
    
     </dd>
    -<dt id="xl-network-configuration-5"><a href="./xl-network-configuration.5.html">xl-network-configuration(5)</a></dt>
    +<dt id="xl-network-configuration-5"><a href="xl-network-configuration.5.html">xl-network-configuration(5)</a></dt>
     <dd>
    
     </dd>
    -<dt id="xen-tscmode-7"><a href="./xen-tscmode.7.html">xen-tscmode(7)</a></dt>
    +<dt id="xen-tscmode-7"><a href="xen-tscmode.7.html">xen-tscmode(7)</a></dt>
     <dd>
    
     </dd>

 docs/Makefile | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index cbc61e3f1d..974d9089ed 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -96,8 +96,9 @@ endif
 html/man/%.$(1).html: man/%.$(1).pod Makefile
 ifneq ($(POD2HTML),)
 	@$(INSTALL_DIR) $$(@D)
-	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|\1.\2>%g' $$< | \
-		(cd man; $(POD2HTML) --podpath=. --htmlroot=. --outfile=../$$@)
+	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|relative:\1.\2.html>%g' $$< | \
+		$(POD2HTML) | \
+		sed -r -e 's%( href=")relative:%\1%g' > $$@
 else
 	@echo "pod2html not installed; skipping $$@"
 endif
-- 
Anthony PERARD


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

[PATCH 2/2] man: Highlight reference in xl-disk-configuration(5)

[Anthony PERARD]

Provide a better way to see the link to a different manpage, with simple
words.

Suggested-by: Ian Jackson <ian.jackson@citrix.com>
Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>
---
 docs/man/xl-disk-configuration.5.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/man/xl-disk-configuration.5.pod b/docs/man/xl-disk-configuration.5.pod
index d3eedc1926..eea893ef91 100644
--- a/docs/man/xl-disk-configuration.5.pod
+++ b/docs/man/xl-disk-configuration.5.pod
@@ -123,7 +123,7 @@ raw
 =item Description
 
 Virtual device as seen by the guest (also referred to as guest drive
-designation in some specifications).  L<xen-vbd-interface(7)>
+designation in some specifications).  See L<xen-vbd-interface(7)>.
 
 =item Supported values
 
-- 
Anthony PERARD


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

Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html

[Andrew Cooper]

On 15/01/2019 18:21, Anthony PERARD wrote:
> diff --git a/docs/Makefile b/docs/Makefile
> index cbc61e3f1d..974d9089ed 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -96,8 +96,9 @@ endif
>  html/man/%.$(1).html: man/%.$(1).pod Makefile
>  ifneq ($(POD2HTML),)
>  	@$(INSTALL_DIR) $$(@D)

I've got no specific comment on the sedary, but please can we we have a
comment here explaining what is going on so some poor sole in 6 months
time stands a chance of figuring this out.

    # Fix up man-page links to work with the resulting html/ layout.

or equivalent.

~Andrew

> -	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|\1.\2>%g' $$< | \
> -		(cd man; $(POD2HTML) --podpath=. --htmlroot=. --outfile=../$$@)
> +	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|relative:\1.\2.html>%g' $$< | \
> +		$(POD2HTML) | \
> +		sed -r -e 's%( href=")relative:%\1%g' > $$@
>  else
>  	@echo "pod2html not installed; skipping $$@"
>  endif


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

Re: [PATCH 2/2] man: Highlight reference in xl-disk-configuration(5)

[Ian Jackson]

Anthony PERARD writes ("[PATCH 2/2] man: Highlight reference in xl-disk-configuration(5)"):
> Provide a better way to see the link to a different manpage, with simple
> words.
> 
> Suggested-by: Ian Jackson <ian.jackson@citrix.com>
> Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

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

Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html

[Ian Jackson]

Anthony PERARD writes ("[PATCH 1/2] docs: Fix all links to Xen man pages in html"):
> Second try, this time also works for all links to xen-vbd-interface(7).
> 
> We don't try anymore to have pod2html generate relative links, instead
> we do it ourself.
> 
> First, we modify all links to man pages to have what looks like an
> absolute URL and pod2html will just write it in the html output.
> Absolute URL in POD are in the form L<text|scheme:...> so let's just use
> a scheme that isn't real, but easy to find in the resulting html output:
> "relative:".
> 
> Then we fix the output and remove all the bogus scheme "relative" and
> can end up with nice relative links.
...
> -	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|\1.\2>%g' $$< | \
> -		(cd man; $(POD2HTML) --podpath=. --htmlroot=. --outfile=../$$@)
> +	sed -r -e 's%L<([^>]+)\(([1-9])\)>%L<\1(\2)|relative:\1.\2.html>%g' $$< | \
> +		$(POD2HTML) | \
> +		sed -r -e 's%( href=")relative:%\1%g' > $$@

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Did you intend this for 4.12 ?  If so you should probably CC Juergen.

Regards,
Ian.

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

Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html

[Ian Jackson]

Andrew Cooper writes ("Re: [Xen-devel] [PATCH 1/2] docs: Fix all links to Xen man pages in html"):
> On 15/01/2019 18:21, Anthony PERARD wrote:
> > diff --git a/docs/Makefile b/docs/Makefile
> > index cbc61e3f1d..974d9089ed 100644
> > --- a/docs/Makefile
> > +++ b/docs/Makefile
> > @@ -96,8 +96,9 @@ endif
> >  html/man/%.$(1).html: man/%.$(1).pod Makefile
> >  ifneq ($(POD2HTML),)
> >  	@$(INSTALL_DIR) $$(@D)
> 
> I've got no specific comment on the sedary, but please can we we have a
> comment here explaining what is going on so some poor sole in 6 months
> time stands a chance of figuring this out.
> 
>   # Fix up man-page links to work with the resulting html/ layout.

Or maybe some of the text from the commit message could be moved into
a code comment.  Either way my ack can stand.

Ian.

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

Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html

[Anthony PERARD]

On Tue, Jan 15, 2019 at 07:16:21PM +0000, Ian Jackson wrote:
> Andrew Cooper writes ("Re: [Xen-devel] [PATCH 1/2] docs: Fix all links to Xen man pages in html"):
> > On 15/01/2019 18:21, Anthony PERARD wrote:
> > > diff --git a/docs/Makefile b/docs/Makefile
> > > index cbc61e3f1d..974d9089ed 100644
> > > --- a/docs/Makefile
> > > +++ b/docs/Makefile
> > > @@ -96,8 +96,9 @@ endif
> > >  html/man/%.$(1).html: man/%.$(1).pod Makefile
> > >  ifneq ($(POD2HTML),)
> > >  	@$(INSTALL_DIR) $$(@D)
> > 
> > I've got no specific comment on the sedary, but please can we we have a
> > comment here explaining what is going on so some poor sole in 6 months
> > time stands a chance of figuring this out.
> > 
> >   # Fix up man-page links to work with the resulting html/ layout.
> 
> Or maybe some of the text from the commit message could be moved into
> a code comment.  Either way my ack can stand.

I'm going to add:

    # Fix up links between man-pages
    # 1) L<xl(1)> -> L<xl(1)|relative:xl.1.html>
    # 2) <a href="relative:xl.1.html"> -> <a href="xl.1.html">


-- 
Anthony PERARD

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