Fix the HTML rendering of man pages to avoid markdown reinterpretation

Some of our manpages have the construct "[something](somethingelse)".

From a POD and HTML perspective, there's nothing special with that.
However, since we wrap the HTML with markdown (perfectly legitimate), we
need to pay attention that nothing in the HTML can reasonably be
reinterpreted as markdown.

Unfortunately, the construct mentioned about has that issue.

This is easily fixed by replacing '](' with '](', which is valid
HTML5.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/web/pull/443)

diff --git a/bin/fix-man-html b/bin/fix-man-html
new file mode 100755 (executable)
index 0000000..3caad2a
--- /dev/null
+++ b/bin/fix-man-html
@@ -0,0 +1,12 @@
+#! /usr/bin/env perl
+
+# The pod source may contain things that can be reinterpreted as markdown,
+# and thereby rendered incorrectly.  This script fixes that, usually by
+# replacing some character with the corresponding HTML character entity.
+
+local $/;                       # Slurp the whole file
+my $contents = <STDIN>;
+
+$contents =~ s|\]\(|\&rbrack;(|g; # ]( suggests a markdown link
+
+print $contents;

diff --git a/bin/mk-manpagetts b/bin/mk-manpagetts
index b63e291d56d878ef5fb09c4f0955f58c19239cd9..f749fe410aa8302d95adec89c71fc2280bbc2f4e 100755 (executable)
--- a/bin/mk-manpagetts
+++ b/bin/mk-manpagetts
@@ -59,6 +59,10 @@ sub main {
 
                 # Get main HTML output
                 my $out = $class->geninc( $release, $inpod, %data );
+
+                # Fix HTML output where it could be reinterpretted as markdown
+                $out =~ s|\]\(|\](|g; # ]( suggests a markdown link
+
                 open( my $fh, ">", $outinc )
                     or $class->die("Can't open $outinc: $!");
                 print $fh $out or $class->die("Can't print $outinc: $!");

diff --git a/bin/mk-manpagetts3 b/bin/mk-manpagetts3
index 9cb32fbfc83ddecb4646f1002277925579226e69..4304d5d193c22e8110c7ab873e6c6e6f8a55267f 100755 (executable)
--- a/bin/mk-manpagetts3
+++ b/bin/mk-manpagetts3
@@ -24,7 +24,10 @@ srcdir=tmp-install/share/doc/openssl/html
     if [ "$F" != "$Dn/$Fn" ]; then
         # HTML file, which we treat specially
         G=$Dn/$Fn.inc
-        $HERE/strip-man-html < $srcdir/$F > $destdir/$G
+        cat $srcdir/$F \
+            | $HERE/strip-man-html \
+            | $HERE/fix-man-html \
+            > $destdir/$G
 
         section=$(basename $Dn | sed -e 's|^man||')
         description="$($HERE/all-html-man-names < $destdir/$G | sed -e 's|^.* - ||' -e 's|\&|\\\&|g')"