[Xen-changelog] [xen master] docs: Fix links in html generation of man pages

[patchbot@xxxxxxx]

commit 84323dfb9daac3b47919113f881c19cffe01fc22
Author:     Anthony PERARD <anthony.perard@xxxxxxxxxx>
AuthorDate: Tue Jan 15 15:48:37 2019 +0000
Commit:     Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
CommitDate: Tue Jan 15 17:25:40 2019 +0000

    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.
    
    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>
    Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
    Release-acked-by: Juergen Gross <jgross@xxxxxxxx>
---
 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
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog