[pve-devel] [PATCH docs 1/3] asciidoc-pve: ignore link targets for non-manpages

Alwin Antreich a.antreich at proxmox.com
Tue Feb 12 10:44:49 CET 2019

From: Thomas Lamprecht <t.lamprecht at proxmox.com>

To allow linking from to a chapter/section not included in a manpage
allow the manpage link resolver to just return text in a case the
link target text is in fact no manpage.

If the link is a valid one in general will be checked in a lot of
other places, so here we won't run into a regression where a wrong,
non-existing, link does not get detected by the build system.

The particular case I run into problems with this is when linking
from the pveceph chapter to the pve-package-repos, to point to the
(cheph) repos. pve-package-repos is no where included or itself a
manpage, so this checks fails. Even if we say it would make sense to
have it as a manpage, which was my initial solution, we run then into
issues as we have a link to a outside reference, located in
pve-bibliography, which then we probably do not want as manpage.

So in the case where a valid link, which just has no manpage counter
part, is passed to the respective link resolver I just return the
link text as is. An alternative could be to get the link object and
put it in parentheses after the link text, but I'm not to sure about
this so let's for now go the easier route.

Signed-off-by: Thomas Lamprecht <t.lamprecht at proxmox.com>
Signed-off-by: Alwin Antreich <a.antreich at proxmox.com>
 asciidoc-pve.in | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/asciidoc-pve.in b/asciidoc-pve.in
index 70848ca..d1a754d 100644
--- a/asciidoc-pve.in
+++ b/asciidoc-pve.in
@@ -146,7 +146,10 @@ sub replace_man_xref {
     die "xref: no text for man page link '$blockid'\n" if !$text;
     my $section = $fileinfo->{mansection}->{manvolnum}->{$link};
-    die "link target is not a manual page" if !defined($section);
+    if (!defined($section)) {
+	warn "link '$blockid' target '$link' is not a manual page, ignoring\n";
+	return "$text";
+    }
     if ($man_target eq 'html') {

More information about the pve-devel mailing list