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
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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
On 02/08/2018, 12:24, "Lars Kurth" <[email protected]> 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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Ping!
Adding Ian Jackson specifically - we should really fix this for 4.12 Regards
Lars
Quoted 29 lines · 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>.htmlProbably 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
Quoted 7 lines
Regards
Lars_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Quoted 21 lines
Quoted 21 lines · 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
Quoted 7 lines
Quoted 7 lines
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.
Signature · 6 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
PATCH 1/2 man: Fix links in xl(1)
All links to other manpages should contain the man section number.
--- docs/man/xl.1.pod.in | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
docs/man/xl.1.pod.in +4 -4
@@ -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:
Signature · 7 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] man: Fix links in xl(1)
Anthony PERARD writes ("[PATCH 1/2] man: Fix links in xl(1)"):
Quoted 1 line
All links to other manpages should contain the man section number.
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] man: Fix links in xl(1)
Quoted 4 lines · Ian Jackson
Anthony PERARD writes ("[PATCH 1/2] man: Fix links in xl(1)"):
Quoted 1 line
All links to other manpages should contain the man section number.
Acked-by Ian Jackson <[email protected]>
Juergen
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
PATCH 2/2 docs: Fix links in html generation of man pages
In reply to Anthony PERARDCurrently, 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.
---
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(-)
docs/Makefile +2 -1
@@ -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
Signature · 7 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
Anthony PERARD writes ("[PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 5 lines
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.
Quoted 3 lines
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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
Quoted 5 lines · Ian Jackson
Anthony PERARD writes ("[PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 4 lines
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.
Quoted 7 lines
Quoted 1 line
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):
xl-disk-configuration.5.html renamed from man/xl-disk-configuration.5.html +1 -1
@@ -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>
xl.cfg.5.html renamed from man/xl.cfg.5.html +7 -7
@@ -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>
Signature · 6 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Ian Jackson
Acked-byRe: [PATCH 2/2] docs: Fix links in html generation of man pages
Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 5 lines · Ian Jackson
Quoted 2 lines
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.
Quoted 1 line
But here is a sample
This all looks good to me.
Quoted 3 lines
(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:
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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
Quoted 27 lines · Ian Jackson
Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 5 lines · Ian Jackson
Quoted 2 lines
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.
Quoted 1 line
But here is a sample
This all looks good to me.
Quoted 3 lines
(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 ?
Quoted 6 lines
Anyway, this patch of yours is a big improvement, so:
Acked-by Ian Jackson <[email protected]>I think linkifying that one missing link is a `nice to have' and can be done now or later as yo like.
Juergen
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
In reply to Ian JacksonQuoted 17 lines · Ian Jackson
Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 5 lines · Ian Jackson
Quoted 2 lines
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.
Quoted 1 line
But here is a sample
This all looks good to me.
Quoted 3 lines
(the only not working link will be in xl-disk-configuration, all other links works like shown in the diff of xl.cfg):
Quoted 8 lines
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.
Quoted 1 line
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.
Signature · 6 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
Quoted 6 lines
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.
Quoted 3 lines
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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
PATCH 1/2 docs: Fix all links to Xen man pages in html
In reply to Anthony PERARDSecond 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.
---
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(-)
docs/Makefile +3 -2
@@ -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
Signature · 7 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html
docs/Makefile endif · line 98
Quoted 8 lines · Anthony PERARD
docs/Makefile +0
-0@@ -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
docs/Makefile endif · line 104
Quoted 8 lines
docs/Makefile +3
-2- 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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html
Andrew Cooper writes ("Re: [Xen-devel] [PATCH 1/2] docs: Fix all links to Xen man pages in html"):
Quoted 14 lines · Anthony PERARD
docs/Makefile endif · line 98
Quoted 8 lines
docs/Makefile +0
-0@@ -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.
Quoted 1 line
# 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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html
Quoted 15 lines · Ian Jackson
Andrew Cooper writes ("Re: [Xen-devel] [PATCH 1/2] docs: Fix all links to Xen man pages in html"):
Quoted 14 lines · Anthony PERARD
docs/Makefile endif · line 98
Quoted 8 lines
docs/Makefile +0
-0@@ -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.
Quoted 4 lines
Quoted 1 line
# 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">Signature · 6 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 1/2] docs: Fix all links to Xen man pages in html
In reply to Anthony PERARDAnthony PERARD writes ("[PATCH 1/2] docs: Fix all links to Xen man pages in html"):
Quoted 13 lines
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.
...
docs/Makefile endif · line 101
Quoted 5 lines
docs/Makefile +3
-2- 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' > $$@
Did you intend this for 4.12 ? If so you should probably CC Juergen.
Regards,
Ian.
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
PATCH 2/2 man: Highlight reference in xl-disk-configuration(5)
In reply to Anthony PERARDProvide a better way to see the link to a different manpage, with simple words.
--- docs/man/xl-disk-configuration.5.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/man/xl-disk-configuration.5.pod +1 -1
@@ -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
Signature · 7 lines
Anthony PERARD _______________________________________________ Xen-devel mailing list [email protected] https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] man: Highlight reference in xl-disk-configuration(5)
Anthony PERARD writes ("[PATCH 2/2] man: Highlight reference in xl-disk-configuration(5)"):
Quoted 5 lines
Provide a better way to see the link to a different manpage, with simple words.
Suggested-by Ian Jackson <[email protected]>Signed-off-by Anthony PERARD <[email protected]>
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [PATCH 2/2] docs: Fix links in html generation of man pages
In reply to Ian JacksonQuoted 5 lines · Ian Jackson
Anthony PERARD writes ("Re: [PATCH 2/2] docs: Fix links in html generation of man pages"):
snip
Quoted 8 lines
Anyway, this patch of yours is a big improvement, so:
Acked-by Ian Jackson <[email protected]>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
[email protected]
https://lists.xenproject.org/mailman/listinfo/xen-devel