Wrap saildoc LaTeX in \saildoclabelled macro

This takes two arguments: the label name and the \saildocfoo macro use
itself. This allows cunning definitions of \saildoclabelled and
\saildocfoo to tease apart the various bits and reconstruct them in a
different order without having to redefine \phantomsection and \label
temporarily and hard-code knowledge of the implementation of these
documentation commands. I intend to use these in cheri-architecture in
combination with sail-cheri-riscv.

Unlike the other macros, this is considered a bit more niche, so we
include a default definition of it that expands to what was previously
hard-coded. This also makes this a non-breaking change.

1 files changed, 9 insertions, 6 deletions

diff --git a/src/latex.ml b/src/latex.ml
index 128d0ec1..2bb38bd7 100644
--- a/src/latex.ml
+++ b/src/latex.ml
@@ -333,9 +333,9 @@ let doc_spec_simple (VS_aux (VS_val_spec (ts, id, ext, is_cast), _)) =
 
 let rec latex_command cat id no_loc ((l, _) as annot) =
   state.this <- Some id;
-  let labelling = match cat with
-    | Val -> sprintf "\\label{%s}" (refcode_id id)
-    | _ -> sprintf "\\label{%s%s}" (category_name cat) (refcode_id id)
+  let labelname = match cat with
+    | Val -> sprintf "%s" (refcode_id id)
+    | _ -> sprintf "%s%s" (category_name cat) (refcode_id id)
   in
   (* To avoid problems with verbatim environments in commands, we have
      to put the sail code for each command in a separate file. *)
@@ -351,9 +351,9 @@ let rec latex_command cat id no_loc ((l, _) as annot) =
     begin
       state.commands <- StringSet.add command state.commands;
 
-      ksprintf string "\\newcommand{%s}{\\phantomsection%s\\saildoc%s{" command labelling (category_name_simple cat)
+      ksprintf string "\\newcommand{%s}{\\saildoclabelled{%s}{\\saildoc%s{" command labelname (category_name_simple cat)
       ^^ docstring l ^^ string "}{"
-      ^^ ksprintf string "\\lstinputlisting[language=sail]{%s}}}" (Filename.concat !opt_directory code_file)
+      ^^ ksprintf string "\\lstinputlisting[language=sail]{%s}}}}" (Filename.concat !opt_directory code_file)
     end
 
 let latex_label str id =
@@ -434,6 +434,8 @@ let tdef_id = function
 let defs (Defs defs) =
   reset_state state;
 
+  let preamble = string "\\providecommand\\saildoclabelled[2]{\\phantomsection\\label{#1}#2}" ^^ twice hardline in
+
   let overload_counter = ref 0 in
 
   let valspecs = ref IdSet.empty in
@@ -505,7 +507,8 @@ let defs (Defs defs) =
     |> string
   in
 
-  tex
+  preamble
+  ^^ tex
   ^^ separate (twice hardline) [id_command Val !valspecs;
                                 ref_command Val !valspecs;
                                 id_command Function !fundefs;