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

[Anthony PERARD <anthony.perard@xxxxxxxxxx>]

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@xxxxxxxxxx>

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