manual: docitem macros for linking modules (#9988)

manual/manual/library/compilerlibs.etex

@@ -26,34 +26,21 @@ type\\*"#load \"compiler-libs/ocamlcommon.cma\";;".
 % Some of the files below are commented out as the documentation is too poor
 % or they are thought to be nonessential.
 
-\ifouthtml
-\begin{links}
-\item \ahref{compilerlibref/Ast\_helper.html}{Module \texttt{Ast_helper}: helper functions for AST construction}
-\item \ahref{compilerlibref/Ast\_mapper.html}{Module \texttt{Ast_mapper}: -ppx rewriter interface}
-\item \ahref{compilerlibref/Asttypes.html}{Module \texttt{Asttypes}: auxiliary types used by Parsetree}
-% \item \ahref{compilerlibref/Lexer.html}{Module \texttt{Lexer}: OCaml syntax lexing}
-\item \ahref{compilerlibref/Location.html}{Module \texttt{Location}: source code locations}
-\item \ahref{compilerlibref/Longident.html}{Module \texttt{Longident}: long identifiers}
-\item \ahref{compilerlibref/Parse.html}{Module \texttt{Parse}: OCaml syntax parsing}
-\item \ahref{compilerlibref/Parsetree.html}{Module \texttt{Parsetree}: OCaml syntax tree}
-\item \ahref{compilerlibref/Pprintast.html}{Module \texttt{Pprintast}: OCaml syntax printing}
-% \item \ahref{compilerlibref/Printast.html}{Module \texttt{Printast}: AST printing}
-\end{links}
 
-\else
+\begin{linklist}
-{\ocamldocinputstart
+\ifouthtml%
 % Ast_helper is excluded from the PDF and text manuals.
 % It is over 20 pages long and does not have doc-comments. It is expected
 % that Ast_helper will be only useful in the HTML manual (to look up signatures).
-% \input{Ast_helper.tex}
+\compilerdocitem{Ast_helper}{helper functions for AST construction}
-\input{Ast_mapper.tex}
+\fi%
-\input{Asttypes.tex}
+\compilerdocitem{Ast_mapper}{-ppx rewriter interface}
-% \input{Lexer.tex}
+\compilerdocitem{Asttypes}{auxiliary types used by Parsetree}
-\input{Location.tex}
+% \item \ahref{compilerlibref/Lexer.html}{Module \texttt{Lexer}: OCaml syntax lexing}
-\input{Longident.tex}
+\compilerdocitem{Location}{source code locations}
-\input{Parse.tex}
+\compilerdocitem{Longident}{long identifiers}
-\input{Parsetree.tex}
+\compilerdocitem{Parse}{OCaml syntax parsing}
-\input{Pprintast.tex}
+\compilerdocitem{Parsetree}{OCaml syntax tree}
-}
+\compilerdocitem{Pprintast}{OCaml syntax printing}
-% \input{Printast.tex}
+% \item \ahref{compilerlibref/Printast.html}{Module \texttt{Printast}: AST printing}
-\fi
+\end{linklist}

manual/manual/library/core.etex

@@ -25,14 +25,10 @@ indexed at the end of this report.
 \input{builtin.tex}
 \ifouthtml
 \section{s:stdlib-module}{Module {\tt Stdlib}: the initially opened module}
-\begin{links}
-\item \ahref{libref/Stdlib.html}{Module \texttt{Stdlib}: the initially opened module}
-\item Module \texttt{Pervasives}: deprecated alias for Stdlib
-\end{links}
-\else
-{
-\ocamldocinputstart
-\input{Stdlib.tex}
-}
 \fi
-
+\begin{linklist}
+\stddocitem{Stdlib}{the initially opened module}
+\ifouthtml%
+\item Module \texttt{Pervasives}: deprecated alias for Stdlib
+\fi%
+\end{linklist}

manual/manual/library/libdynlink.etex

@@ -22,11 +22,6 @@ access to all the libraries that are visible to the main program (and not just
 to the parts of those libraries that are actually used in the main program),
 programs using the "dynlink" library should be linked with "-linkall".
 
-\ifouthtml
+\begin{linklist}
-\begin{links}
+\stddocitem{Dynlink}{dynamic loading of bytecode object files}
-\item \ahref{libref/Dynlink.html}{Module \texttt{Dynlink}: dynamic loading of bytecode object files}
+\end{linklist}
-\end{links}
-
-\else
-\input{Dynlink.tex}
-\fi

manual/manual/library/libstr.etex

@@ -19,14 +19,6 @@ For interactive use of the "str" library, do:
 or (if dynamic linking of C libraries is supported on your platform),
 start "ocaml" and type "#load \"str.cma\";;".
 
-\ifouthtml
+\begin{linklist}
-\begin{links}
+\stddocitem{Str}{regular expressions and string processing}
-\item \ahref{libref/Str.html}{Module \texttt{Str}: regular expressions and string processing}
+\end{linklist}
-\end{links}
-
-\else
-\ocamldocinputstart
-\input{Str.tex}
-\fi
-
-

manual/manual/library/libthreads.etex

@@ -26,18 +26,10 @@ Programs that use threads must be linked as follows:
 Compilation units that use the "threads" library must also be compiled with
 the "-I +threads" option (see chapter~\ref{c:camlc}).
 
-\ifouthtml
+\begin{linklist}
-\begin{links}
+\stddocitem{Thread}{lightweight threads}
-\item \ahref{libref/Thread.html}{Module \texttt{Thread}: lightweight threads}
+\stddocitem{Mutex}{locks for mutual exclusion}
-\item \ahref{libref/Mutex.html}{Module \texttt{Mutex}: locks for mutual exclusion}
+\stddocitem{Condition}{condition variables to synchronize between threads}
-\item \ahref{libref/Condition.html}{Module \texttt{Condition}: condition variables to synchronize between threads}
+\stddocitem{Semaphore}{semaphores, another thread synchronization mechanism}
-\item \ahref{libref/Semaphore.html}{Module \texttt{Semaphore}: semaphores, another thread synchronization mechanism}
+\stddocitem{Event}{first-class synchronous communication}
-\item \ahref{libref/Event.html}{Module \texttt{Event}: first-class synchronous communication}
+\end{linklist}
-\end{links}
-\else
-\input{Thread.tex}
-\input{Mutex.tex}
-\input{Condition.tex}
-\input{Semaphore.tex}
-\input{Event.tex}
-\fi

manual/manual/library/libunix.etex

@@ -9,11 +9,10 @@ provided.  Refer to sections 2~and~3 of the Unix manual for more
 details on the behavior of these functions.
 
 \ifouthtml
-\begin{links}
+\begin{linklist}
-\item \ahref{libref/Unix.html}{Module \texttt{Unix}: Unix system calls}
+\stddocitem{Unix}{Unix system calls}
-\item \ahref{libref/UnixLabels.html}{Module \texttt{UnixLabels}: Labeled
+\stddocitem{UnixLabels}{Labeled Unix system calls}
-   Unix system calls}
+\end{linklist}
-\end{links}
 \fi
 
 Not all functions are provided by all Unix variants. If some functions
@@ -39,20 +38,17 @@ more information on the functions that are not supported under Windows.
 \end{windows}
 
 \begin{latexonly}
-{
+\begin{linklist}
-\ocamldocinputstart
+\stddocitem{Unix}{Unix system calls}
-\input{Unix.tex}
+\end{linklist}
 
-\section{s:Module \texttt{UnixLabels}: labelized version of the interface}
+\section{UnixLabels}{Module \texttt{UnixLabels}: labelized version of the interface}
-\label{UnixLabels}
 \index{UnixLabels (module)@\verb~UnixLabels~ (module)}%
 
 This module is identical to "Unix"~(\ref{Unix}), and only differs by
 the addition of labels. You may see these labels directly by looking
 at "unixLabels.mli", or by using the "ocamlbrowser" tool.
-
 \newpage
-}
 \end{latexonly}
 
 \begin{windows}

manual/manual/library/stdlib-blurb.etex

@@ -106,117 +106,61 @@ be called from C \\
 \end{tabular}
 \end{latexonly}
 
-\ifouthtml
+\begin{linklist}
-\begin{links}
+\stddocitem{Arg}{parsing of command line arguments}
-\item \ahref{libref/Arg.html}{Module \texttt{Arg}: parsing of command line arguments}
+\stddocitem{Array}{array operations}
-\item \ahref{libref/Array.html}{Module \texttt{Array}: array operations}
+\stddocitem{ArrayLabels}{array operations (with labels)}
-\item \ahref{libref/ArrayLabels.html}{Module \texttt{ArrayLabels}: array operations (with labels)}
+\stddocitem{Atomic}{atomic references}
-\item \ahref{libref/Atomic.html}{Module \texttt{Atomic}: atomic references}
+\stddocitem{Bigarray}{large, multi-dimensional, numerical arrays}
-\item \ahref{libref/Bigarray.html}{Module \texttt{Bigarray}: large, multi-dimensional, numerical arrays}
+\stddocitem{Bool}{boolean values}
-\item \ahref{libref/Bool.html}{Module \texttt{Bool}: boolean values}
+\stddocitem{Buffer}{extensible buffers}
-\item \ahref{libref/Buffer.html}{Module \texttt{Buffer}: extensible buffers}
+\stddocitem{Bytes}{byte sequences}
-\item \ahref{libref/Bytes.html}{Module \texttt{Bytes}: byte sequences}
+\stddocitem{BytesLabels}{byte sequences (with labels)}
-\item \ahref{libref/BytesLabels.html}{Module \texttt{BytesLabels}: byte sequences (with labels)}
+\stddocitem{Callback}{registering OCaml values with the C runtime}
-\item \ahref{libref/Callback.html}{Module \texttt{Callback}: registering OCaml values with the C runtime}
+\stddocitem{Char}{character operations}
-\item \ahref{libref/Char.html}{Module \texttt{Char}: character operations}
+\stddocitem{Complex}{Complex numbers}
-\item \ahref{libref/Complex.html}{Module \texttt{Complex}: Complex numbers}
+\stddocitem{Digest}{MD5 message digest}
-\item \ahref{libref/Digest.html}{Module \texttt{Digest}: MD5 message digest}
+\stddocitem{Either}{Either values}
-\item \ahref{libref/Either.html}{Module \texttt{Either}: either values}
+\stddocitem{Ephemeron}{Ephemerons and weak hash table}
-\item \ahref{libref/Ephemeron.html}{Module \texttt{Ephemeron}: Ephemerons and weak hash table}
+\stddocitem{Filename}{operations on file names}
-\item \ahref{libref/Filename.html}{Module \texttt{Filename}: operations on file names}
+\stddocitem{Float}{Floating-point numbers}
-\item \ahref{libref/Float.html}{Module \texttt{Float}: Floating-point numbers}
+\stddocitem{Format}{pretty printing}
-\item \ahref{libref/Format.html}{Module \texttt{Format}: pretty printing}
+\stddocitem{Fun}{function values}
-\item \ahref{libref/Fun.html}{Module \texttt{Fun}: function values}
+\stddocitem{Gc}{memory management control and statistics; finalized values}
-\item \ahref{libref/Gc.html}{Module \texttt{Gc}: memory management control and statistics; finalized values}
+\stddocitem{Genlex}{a generic lexical analyzer}
-\item \ahref{libref/Genlex.html}{Module \texttt{Genlex}: a generic lexical analyzer}
+\stddocitem{Hashtbl}{hash tables and hash functions}
-\item \ahref{libref/Hashtbl.html}{Module \texttt{Hashtbl}: hash tables and hash functions}
+\stddocitem{Int}{integers}
-\item \ahref{libref/Int.html}{Module \texttt{Int}: integers}
+\stddocitem{Int32}{32-bit integers}
-\item \ahref{libref/Int32.html}{Module \texttt{Int32}: 32-bit integers}
+\stddocitem{Int64}{64-bit integers}
-\item \ahref{libref/Int64.html}{Module \texttt{Int64}: 64-bit integers}
+\stddocitem{Lazy}{deferred computations}
-\item \ahref{libref/Lazy.html}{Module \texttt{Lazy}: deferred computations}
+\stddocitem{Lexing}{the run-time library for lexers generated by \texttt{ocamllex}}
-\item \ahref{libref/Lexing.html}{Module \texttt{Lexing}: the run-time library for lexers generated by \texttt{ocamllex}}
+\stddocitem{List}{list operations}
-\item \ahref{libref/List.html}{Module \texttt{List}: list operations}
+\stddocitem{ListLabels}{list operations (with labels)}
-\item \ahref{libref/ListLabels.html}{Module \texttt{ListLabels}: list operations (with labels)}
+\stddocitem{Map}{association tables over ordered types}
-\item \ahref{libref/Map.html}{Module \texttt{Map}: association tables over ordered types}
+\stddocitem{Marshal}{marshaling of data structures}
-\item \ahref{libref/Marshal.html}{Module \texttt{Marshal}: marshaling of data structures}
+\stddocitem{MoreLabels}{Include modules \texttt{Hashtbl}, \texttt{Map} and \texttt{Set} with labels}
-\item \ahref{libref/MoreLabels.html}{Module \texttt{MoreLabels}: Include modules \texttt{Hashtbl}, \texttt{Map} and \texttt{Set} with labels}
+\stddocitem{Nativeint}{processor-native integers}
-\item \ahref{libref/Nativeint.html}{Module \texttt{Nativeint}: processor-native integers}
+\stddocitem{Oo}{object-oriented extension}
-\item \ahref{libref/Oo.html}{Module \texttt{Oo}: object-oriented extension}
+\stddocitem{Option}{option values}
-\item \ahref{libref/Option.html}{Module \texttt{Option}: option values}
+\stddocitem{Parsing}{the run-time library for parsers generated by \texttt{ocamlyacc}}
-\item \ahref{libref/Parsing.html}{Module \texttt{Parsing}: the run-time library for parsers generated by \texttt{ocamlyacc}}
+\stddocitem{Printexc}{facilities for printing exceptions}
-\item \ahref{libref/Printexc.html}{Module \texttt{Printexc}: facilities for printing exceptions}
+\stddocitem{Printf}{formatting printing functions}
-\item \ahref{libref/Printf.html}{Module \texttt{Printf}: formatting printing functions}
+\stddocitem{Queue}{first-in first-out queues}
-\item \ahref{libref/Queue.html}{Module \texttt{Queue}: first-in first-out queues}
+\stddocitem{Random}{pseudo-random number generator (PRNG)}
-\item \ahref{libref/Random.html}{Module \texttt{Random}: pseudo-random number generator (PRNG)}
+\stddocitem{Result}{result values}
-\item \ahref{libref/Result.html}{Module \texttt{Result}: result values}
+\stddocitem{Scanf}{formatted input functions}
-\item \ahref{libref/Scanf.html}{Module \texttt{Scanf}: formatted input functions}
+\stddocitem{Seq}{functional iterators}
-\item \ahref{libref/Seq.html}{Module \texttt{Seq}: functional iterators}
+\stddocitem{Set}{sets over ordered types}
-\item \ahref{libref/Set.html}{Module \texttt{Set}: sets over ordered types}
+\stddocitem{Stack}{last-in first-out stacks}
-\item \ahref{libref/Stack.html}{Module \texttt{Stack}: last-in first-out stacks}
+\stddocitem{StdLabels}{Include modules \texttt{Array}, \texttt{List} and \texttt{String} with labels}
-\item \ahref{libref/StdLabels.html}{Module \texttt{StdLabels}: Include modules \texttt{Array}, \texttt{List} and \texttt{String} with labels}
+\stddocitem{Stream}{streams and parsers}
-\item \ahref{libref/Stream.html}{Module \texttt{Stream}: streams and parsers}
+\stddocitem{String}{string operations}
-\item \ahref{libref/String.html}{Module \texttt{String}: string operations}
+\stddocitem{StringLabels}{string operations (with labels)}
-\item \ahref{libref/StringLabels.html}{Module \texttt{StringLabels}: string operations (with labels)}
+\stddocitem{Sys}{system interface}
-\item \ahref{libref/Sys.html}{Module \texttt{Sys}: system interface}
+\stddocitem{Uchar}{Unicode characters}
-\item \ahref{libref/Uchar.html}{Module \texttt{Uchar}: Unicode characters}
+\stddocitem{Unit}{unit values}
-\item \ahref{libref/Unit.html}{Module \texttt{Unit}: unit values}
+\stddocitem{Weak}{arrays of weak pointers}
-\item \ahref{libref/Weak.html}{Module \texttt{Weak}: arrays of weak pointers}
+\ifouthtml\else
-\end{links}
+\stddocitem{Ocaml_operators}{}
-\else
-{\ocamldocinputstart
-\input{Arg.tex}
-\input{Array.tex}
-\input{ArrayLabels.tex}
-\input{Atomic.tex}
-\input{Bigarray.tex}
-\input{Bool.tex}
-\input{Buffer.tex}
-\input{Bytes.tex}
-\input{BytesLabels.tex}
-\input{Callback.tex}
-\input{Char.tex}
-\input{Complex.tex}
-\input{Digest.tex}
-\input{Either.tex}
-\input{Ephemeron.tex}
-\input{Filename.tex}
-\input{Float.tex}
-\input{Format.tex}
-\input{Fun.tex}
-\input{Gc.tex}
-\input{Genlex.tex}
-\input{Hashtbl.tex}
-\input{Int.tex}
-\input{Int32.tex}
-\input{Int64.tex}
-\input{Lazy.tex}
-\input{Lexing.tex}
-\input{List.tex}
-\input{ListLabels.tex}
-\input{Map.tex}
-\input{Marshal.tex}
-\input{MoreLabels.tex}
-\input{Nativeint.tex}
-\input{Oo.tex}
-\input{Option.tex}
-\input{Parsing.tex}
-\input{Printexc.tex}
-\input{Printf.tex}
-\input{Queue.tex}
-\input{Random.tex}
-\input{Result.tex}
-\input{Scanf.tex}
-\input{Seq.tex}
-\input{Set.tex}
-\input{Stack.tex}
-\input{StdLabels.tex}
-\input{Stream.tex}
-\input{String.tex}
-\input{StringLabels.tex}
-\input{Sys.tex}
-\input{Uchar.tex}
-\input{Unit.tex}
-\input{Weak.tex}
-\input{Ocaml_operators.tex}
-}
 \fi
+\end{linklist}

manual/manual/macros.hva

@@ -291,5 +291,13 @@
 
 \newenvironment{maintitle}{\@open{div}{class="maintitle"}}{\@close{div}}
 
-%%% References to modules in the standard library
+%%% Linking to modules
-\newcommand{\stdmoduleref}[1]{\ahref{libref/#1.html}{\texttt{#1}}}
+
+\newenvironment{linklist}{\begin{links}}{\end{links}}
+
+\newcommand{\moduleref}[3]{\ahref{#1/#2.html}{#3}}
+\newcommand{\stdmoduleref}[1]{\moduleref{libref}{#1}{\texttt{#1}}}
+
+\newcommand{\docitem}[3]{\item \moduleref{#1}{#2}{Module \texttt{#2}}: #3}
+\newcommand{\stddocitem}[2]{\docitem{libref}{#1}{#2}}
+\newcommand{\compilerdocitem}[2]{\docitem{compilerlibref}{#1}{#2}}

manual/manual/macros.tex

@@ -219,9 +219,14 @@
   \addcontentsline{toc}{chapter}{#2}
   \@input{#1.ind}}
 
-%%% References to modules in the standard library
+%%% Linking to modules
 \newcommand{\stdmoduleref}[1]{\hyperref[#1]{\texttt{#1}}[\ref{#1}]}
 
+\newenvironment{linklist}{\begingroup\ocamldocinputstart}{\endgroup}
+\newcommand{\stddocitem}[2]{\input{#1.tex}}
+\newcommand{\compilerdocitem}[2]{\input{#1.tex}}
+
+
 \newenvironment{maintitle}{\begin{center}}{\end{center}}
 
 

manual/manual/manual.inf

@@ -150,3 +150,11 @@
 \def\goodbreak{\ \\}
 
 \def\@savedlistI{}
+
+
+% Linking to modules
+\newenvironment{linklist}{\begingroup\ocamldocinputstart}{\endgroup}
+
+\newcommand{\docitem}[3]{\input{#2.tex}}
+\newcommand{\stddocitem}[2]{\input{#1.tex}}
+\newcommand{\compilerdocitem}[2]{\input{#1.tex}}

manual/tests/check-stdlib-modules

@@ -13,7 +13,11 @@ for i in `cat $TMPDIR/stdlib-$$-modules`; do
     Stdlib | Camlinternal* | *Labels | Obj | Pervasives) continue;;
   esac
   grep -q -e '"'$i'" & p\.~\\pageref{'$i'} &' $1/manual/manual/library/stdlib-blurb.etex || {
-    echo "Module $i is missing from library/stdlib-blurb.etex." >&2
+    echo "Module $i is missing from the module description in library/stdlib-blurb.etex." >&2
+    exitcode=2
+  } &&
+  grep -q -e '\\stddocitem{'$i'}' $1/manual/manual/library/stdlib-blurb.etex || {
+    echo "Module $i is missing from the linklist in library/stdlib-blurb.etex." >&2
     exitcode=2
   }
 done