Saildoc: do not mangle links targets enclosed in <>

This can be useful to reference things that aren't defined by sail.

3 files changed, 82 insertions, 15 deletions

diff --git a/src/latex.ml b/src/latex.ml
index 2bb38bd7..6d479a52 100644
--- a/src/latex.ml
+++ b/src/latex.ml
@@ -237,10 +237,14 @@ let latex_of_markdown str =
     | Ref (r, name, alt, _) ->
        (* special case for [id] (format as code) *)
        let format_fn = if name = alt then inline_code else replace_this in
-       begin match r#get_ref name with
-       | None -> sprintf "\\hyperref[%s]{%s}" (refcode_string name) (format_fn alt)
-       | Some (link, _) -> sprintf "\\hyperref[%s]{%s}" (refcode_string link) (format_fn alt)
-       end
+       (* Do not attempt to escape link destinations wrapped in <> *)
+       if Str.string_match (Str.regexp "<.+>") name 0 then
+         sprintf "\\hyperref[%s]{%s}" (String.sub name 1 ((String.length name) - 2)) (format_fn alt)
+       else
+         begin match r#get_ref name with
+         | None -> sprintf "\\hyperref[%s]{%s}" (refcode_string name) (format_fn alt)
+         | Some (link, _) -> sprintf "\\hyperref[%s]{%s}" (refcode_string link) (format_fn alt)
+         end
     | Url (href, text, "") ->
        sprintf "\\href{%s}{%s}" href (format text)
     | Url (href, text, reference) ->
diff --git a/test/latex/candperm.commands.tex.exp b/test/latex/candperm.commands.tex.exp
index 6c92c681..df253d71 100644
--- a/test/latex/candperm.commands.tex.exp
+++ b/test/latex/candperm.commands.tex.exp
@@ -4,16 +4,40 @@
 
 \newcommand{\sailvalexecute}{\saildoclabelled{zexecute}{\saildocval{}{\lstinputlisting[language=sail]{out/valzexecute33a689e3a631b9b905b85461d3814943.tex}}}}
 
-\newcommand{\sailfclCAndPermexecute}{\saildoclabelled{fclCAndPermzexecute}{\saildocfcl{Capability register \emph{cd} is replaced with the contents of capability
+\newcommand{\sailfclCAndPermBrokenexecute}{\saildoclabelled{fclCAndPermBrokenzexecute}{\saildocfcl{Capability register \emph{cd} is replaced with the contents of capability
+register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
+its previous value and bits 0 .. 10 of integer register \emph{rs2}
+and the \cuperms{} field set to the bitwise and of its previous value
+and bits \hyperref\hyperref[ztablezGpseudocodezDconstants]{\lstinline{table:pseudocode-constants}}{\emph{first\_uperm}} ..
+\hyperref\hyperref[ztablezGpseudocodezDconstants]{\lstinline{table:pseudocode-constants}}{\emph{last\_uperm}} of \emph{rd}.
+
+}{\lstinputlisting[language=sail]{out/fclCAndPermBrokenzexecute33a689e3a631b9b905b85461d3814943.tex}}}}
+
+\newcommand{\sailfclCAndPermEscapedexecute}{\saildoclabelled{fclCAndPermEscapedzexecute}{\saildocfcl{Capability register \emph{cd} is replaced with the contents of capability
 register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
 its previous value and bits 0 .. 10 of integer register \emph{rs2}
 and the \cuperms{} field set to the bitwise and of its previous value
 and bits \hyperref[table:pseudocode-constants]{\emph{first\_uperm}} ..
 \hyperref[table:pseudocode-constants]{\emph{last\_uperm}} of \emph{rd}.
 
-}{\lstinputlisting[language=sail]{out/fclCAndPermzexecute33a689e3a631b9b905b85461d3814943.tex}}}}
+}{\lstinputlisting[language=sail]{out/fclCAndPermEscapedzexecute33a689e3a631b9b905b85461d3814943.tex}}}}
+
+\newcommand{\sailfclCAndPermMarkdownexecute}{\saildoclabelled{fclCAndPermMarkdownzexecute}{\saildocfcl{Capability register \emph{cd} is replaced with the contents of capability
+register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
+its previous value and bits 0 .. 10 of integer register \emph{rs2}
+and the \cuperms{} field set to the bitwise and of its previous value
+and bits \hyperref[table:pseudocode-constants]{*first_uperm*} ..
+\hyperref[table:pseudocode-constants]{*last_uperm*} of \emph{rd}.
+
+}{\lstinputlisting[language=sail]{out/fclCAndPermMarkdownzexecute33a689e3a631b9b905b85461d3814943.tex}}}}
+
+\newcommand{\sailfclCAndPermMarkdownWithRefMacroexecute}{\saildoclabelled{fclCAndPermMarkdownWithRefMacrozexecute}{\saildocfcl{Capability register \emph{cd} is replaced with the contents of capability
+register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
+its previous value and bits 0 .. 10 of integer register \emph{rs2}
+and the \cuperms{} field set to the bitwise and of its previous value
+and bits \firstUPerm{} .. \lastUPerm{} of \emph{rd}.
 
-\newcommand{\sailfclCSetFlagsexecute}{\saildoclabelled{fclCSetFlagszexecute}{\saildocfcl{}{\lstinputlisting[language=sail]{out/fclCSetFlagszexecute33a689e3a631b9b905b85461d3814943.tex}}}}
+}{\lstinputlisting[language=sail]{out/fclCAndPermMarkdownWithRefMacrozexecute33a689e3a631b9b905b85461d3814943.tex}}}}
 
 
 
diff --git a/test/latex/candperm.sail b/test/latex/candperm.sail
index 4aec545a..75482db1 100644
--- a/test/latex/candperm.sail
+++ b/test/latex/candperm.sail
@@ -1,13 +1,15 @@
-/* Test that we can parse the CAndPerm documentation correctly:
- * Previously the \hyperref expressions were broken. */  
 default Order dec
 
 scattered union ast('datasize : Int, 'destsize : Int, 'regsize : Int)
 val execute : forall ('datasize : Int) ('destsize : Int) ('regsize : Int).
   ast('datasize, 'destsize, 'regsize) -> unit
+
+/* Note: need at least two function clauses to generate latex output */
 scattered function execute
-/*! CAndPerm union clause documentation */
-union clause ast = CAndPerm : (int, int, int)
+/*
+ * The naive copy-paste of the existing latex fails due to [] being interpreted as a link.
+ */
+union clause ast = CAndPermBroken : (int, int, int)
 /*!
  * Capability register \emph{cd} is replaced with the contents of capability
  * register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
@@ -16,13 +18,50 @@ union clause ast = CAndPerm : (int, int, int)
  * and bits \hyperref[table:pseudocode-constants]{\emph{first\_uperm}} ..
  * \hyperref[table:pseudocode-constants]{\emph{last\_uperm}} of \emph{rd}.
  */
-function clause execute(CAndPerm(cd, cs1, rs2)) = {
+function clause execute(CAndPermBroken(cd, cs1, rs2)) = {
+    /* Implementation */
+    return ()
+}
+union clause ast = CAndPermEscaped : (int, int, int)
+/*!
+ * Capability register \emph{cd} is replaced with the contents of capability
+ * register \emph{cs1} with the \cperms{} field set to the bitwise-AND of
+ * its previous value and bits 0 .. 10 of integer register \emph{rs2}
+ * and the \cuperms{} field set to the bitwise and of its previous value
+ * and bits \hyperref\[table:pseudocode-constants\]{\emph{first\_uperm}} ..
+ * \hyperref\[table:pseudocode-constants\]{\emph{last\_uperm}} of \emph{rd}.
+ */
+function clause execute(CAndPermEscaped(cd, cs1, rs2)) = {
+    /* Implementation */
+    return ()
+}
+
+union clause ast = CAndPermMarkdown : (int, int, int)
+/*!
+ * Capability register *cd* is replaced with the contents of capability
+ * register *cs1* with the \cperms{} field set to the bitwise-AND of
+ * its previous value and bits 0 .. 10 of integer register *rs2*
+ * and the \cuperms{} field set to the bitwise and of its previous value
+ * and bits [*first_uperm*][<table:pseudocode-constants>] ..
+ * [*last_uperm*][<table:pseudocode-constants>] of *rd*.
+ */
+function clause execute(CAndPermMarkdown(cd, cs1, rs2)) = {
+    /* Implementation */
+    return ()
+}
+
+union clause ast = CAndPermMarkdownWithRefMacro : (int, int, int)
+/*!
+ * Capability register *cd* is replaced with the contents of capability
+ * register *cs1* with the \cperms{} field set to the bitwise-AND of
+ * its previous value and bits 0 .. 10 of integer register *rs2*
+ * and the \cuperms{} field set to the bitwise and of its previous value
+ * and bits \firstUPerm{} .. \lastUPerm{} of *rd*.
+ */
+function clause execute(CAndPermMarkdownWithRefMacro(cd, cs1, rs2)) = {
     /* Implementation */
     return ()
 }
-/* Note: need at least two function clauses to generate latex output */
-union clause ast = CSetFlags : (int, int, int)
-function clause execute CSetFlags(cd, cs1, rs2) = return(())
 
 end execute
 end ast