From 86528b09b9a2b54ed01015042ee55e99b22f410c Mon Sep 17 00:00:00 2001 From: Florian Angeletti Date: Wed, 28 Oct 2020 17:32:42 +0100 Subject: [PATCH] manual: docitem macros for linking modules (#9988) --- manual/manual/library/compilerlibs.etex | 41 ++---- manual/manual/library/core.etex | 16 +-- manual/manual/library/libdynlink.etex | 11 +- manual/manual/library/libstr.etex | 14 +- manual/manual/library/libthreads.etex | 22 +-- manual/manual/library/libunix.etex | 20 ++- manual/manual/library/stdlib-blurb.etex | 170 ++++++++---------------- manual/manual/macros.hva | 12 +- manual/manual/macros.tex | 7 +- manual/manual/manual.inf | 8 ++ manual/tests/check-stdlib-modules | 6 +- 11 files changed, 127 insertions(+), 200 deletions(-) diff --git a/manual/manual/library/compilerlibs.etex b/manual/manual/library/compilerlibs.etex index efbfca628..4247a2c41 100644 --- a/manual/manual/library/compilerlibs.etex +++ b/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 -{\ocamldocinputstart +\begin{linklist} +\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} -\input{Ast_mapper.tex} -\input{Asttypes.tex} -% \input{Lexer.tex} -\input{Location.tex} -\input{Longident.tex} -\input{Parse.tex} -\input{Parsetree.tex} -\input{Pprintast.tex} -} -% \input{Printast.tex} -\fi +\compilerdocitem{Ast_helper}{helper functions for AST construction} +\fi% +\compilerdocitem{Ast_mapper}{-ppx rewriter interface} +\compilerdocitem{Asttypes}{auxiliary types used by Parsetree} +% \item \ahref{compilerlibref/Lexer.html}{Module \texttt{Lexer}: OCaml syntax lexing} +\compilerdocitem{Location}{source code locations} +\compilerdocitem{Longident}{long identifiers} +\compilerdocitem{Parse}{OCaml syntax parsing} +\compilerdocitem{Parsetree}{OCaml syntax tree} +\compilerdocitem{Pprintast}{OCaml syntax printing} +% \item \ahref{compilerlibref/Printast.html}{Module \texttt{Printast}: AST printing} +\end{linklist} diff --git a/manual/manual/library/core.etex b/manual/manual/library/core.etex index d30f0d4d2..fb9ffd17f 100644 --- a/manual/manual/library/core.etex +++ b/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} diff --git a/manual/manual/library/libdynlink.etex b/manual/manual/library/libdynlink.etex index f7448b942..bf0eaac9c 100644 --- a/manual/manual/library/libdynlink.etex +++ b/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{links} -\item \ahref{libref/Dynlink.html}{Module \texttt{Dynlink}: dynamic loading of bytecode object files} -\end{links} - -\else -\input{Dynlink.tex} -\fi +\begin{linklist} +\stddocitem{Dynlink}{dynamic loading of bytecode object files} +\end{linklist} diff --git a/manual/manual/library/libstr.etex b/manual/manual/library/libstr.etex index 180052fc0..f43b0c9e0 100644 --- a/manual/manual/library/libstr.etex +++ b/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{links} -\item \ahref{libref/Str.html}{Module \texttt{Str}: regular expressions and string processing} -\end{links} - -\else -\ocamldocinputstart -\input{Str.tex} -\fi - - +\begin{linklist} +\stddocitem{Str}{regular expressions and string processing} +\end{linklist} diff --git a/manual/manual/library/libthreads.etex b/manual/manual/library/libthreads.etex index f271fec28..69269d197 100644 --- a/manual/manual/library/libthreads.etex +++ b/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{links} -\item \ahref{libref/Thread.html}{Module \texttt{Thread}: lightweight threads} -\item \ahref{libref/Mutex.html}{Module \texttt{Mutex}: locks for mutual exclusion} -\item \ahref{libref/Condition.html}{Module \texttt{Condition}: condition variables to synchronize between threads} -\item \ahref{libref/Semaphore.html}{Module \texttt{Semaphore}: semaphores, another thread synchronization mechanism} -\item \ahref{libref/Event.html}{Module \texttt{Event}: first-class synchronous communication} -\end{links} -\else -\input{Thread.tex} -\input{Mutex.tex} -\input{Condition.tex} -\input{Semaphore.tex} -\input{Event.tex} -\fi +\begin{linklist} +\stddocitem{Thread}{lightweight threads} +\stddocitem{Mutex}{locks for mutual exclusion} +\stddocitem{Condition}{condition variables to synchronize between threads} +\stddocitem{Semaphore}{semaphores, another thread synchronization mechanism} +\stddocitem{Event}{first-class synchronous communication} +\end{linklist} diff --git a/manual/manual/library/libunix.etex b/manual/manual/library/libunix.etex index ed79a74a3..b1bc074d1 100644 --- a/manual/manual/library/libunix.etex +++ b/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} -\item \ahref{libref/Unix.html}{Module \texttt{Unix}: Unix system calls} -\item \ahref{libref/UnixLabels.html}{Module \texttt{UnixLabels}: Labeled - Unix system calls} -\end{links} +\begin{linklist} +\stddocitem{Unix}{Unix system calls} +\stddocitem{UnixLabels}{Labeled Unix system calls} +\end{linklist} \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} -{ -\ocamldocinputstart -\input{Unix.tex} +\begin{linklist} +\stddocitem{Unix}{Unix system calls} +\end{linklist} -\section{s:Module \texttt{UnixLabels}: labelized version of the interface} -\label{UnixLabels} +\section{UnixLabels}{Module \texttt{UnixLabels}: labelized version of the interface} \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} diff --git a/manual/manual/library/stdlib-blurb.etex b/manual/manual/library/stdlib-blurb.etex index 234bf02dc..c8e479ec3 100644 --- a/manual/manual/library/stdlib-blurb.etex +++ b/manual/manual/library/stdlib-blurb.etex @@ -106,117 +106,61 @@ be called from C \\ \end{tabular} \end{latexonly} -\ifouthtml -\begin{links} -\item \ahref{libref/Arg.html}{Module \texttt{Arg}: parsing of command line arguments} -\item \ahref{libref/Array.html}{Module \texttt{Array}: array operations} -\item \ahref{libref/ArrayLabels.html}{Module \texttt{ArrayLabels}: array operations (with labels)} -\item \ahref{libref/Atomic.html}{Module \texttt{Atomic}: atomic references} -\item \ahref{libref/Bigarray.html}{Module \texttt{Bigarray}: large, multi-dimensional, numerical arrays} -\item \ahref{libref/Bool.html}{Module \texttt{Bool}: boolean values} -\item \ahref{libref/Buffer.html}{Module \texttt{Buffer}: extensible buffers} -\item \ahref{libref/Bytes.html}{Module \texttt{Bytes}: byte sequences} -\item \ahref{libref/BytesLabels.html}{Module \texttt{BytesLabels}: byte sequences (with labels)} -\item \ahref{libref/Callback.html}{Module \texttt{Callback}: registering OCaml values with the C runtime} -\item \ahref{libref/Char.html}{Module \texttt{Char}: character operations} -\item \ahref{libref/Complex.html}{Module \texttt{Complex}: Complex numbers} -\item \ahref{libref/Digest.html}{Module \texttt{Digest}: MD5 message digest} -\item \ahref{libref/Either.html}{Module \texttt{Either}: either values} -\item \ahref{libref/Ephemeron.html}{Module \texttt{Ephemeron}: Ephemerons and weak hash table} -\item \ahref{libref/Filename.html}{Module \texttt{Filename}: operations on file names} -\item \ahref{libref/Float.html}{Module \texttt{Float}: Floating-point numbers} -\item \ahref{libref/Format.html}{Module \texttt{Format}: pretty printing} -\item \ahref{libref/Fun.html}{Module \texttt{Fun}: function values} -\item \ahref{libref/Gc.html}{Module \texttt{Gc}: memory management control and statistics; finalized values} -\item \ahref{libref/Genlex.html}{Module \texttt{Genlex}: a generic lexical analyzer} -\item \ahref{libref/Hashtbl.html}{Module \texttt{Hashtbl}: hash tables and hash functions} -\item \ahref{libref/Int.html}{Module \texttt{Int}: integers} -\item \ahref{libref/Int32.html}{Module \texttt{Int32}: 32-bit integers} -\item \ahref{libref/Int64.html}{Module \texttt{Int64}: 64-bit integers} -\item \ahref{libref/Lazy.html}{Module \texttt{Lazy}: deferred computations} -\item \ahref{libref/Lexing.html}{Module \texttt{Lexing}: the run-time library for lexers generated by \texttt{ocamllex}} -\item \ahref{libref/List.html}{Module \texttt{List}: list operations} -\item \ahref{libref/ListLabels.html}{Module \texttt{ListLabels}: list operations (with labels)} -\item \ahref{libref/Map.html}{Module \texttt{Map}: association tables over ordered types} -\item \ahref{libref/Marshal.html}{Module \texttt{Marshal}: marshaling of data structures} -\item \ahref{libref/MoreLabels.html}{Module \texttt{MoreLabels}: Include modules \texttt{Hashtbl}, \texttt{Map} and \texttt{Set} with labels} -\item \ahref{libref/Nativeint.html}{Module \texttt{Nativeint}: processor-native integers} -\item \ahref{libref/Oo.html}{Module \texttt{Oo}: object-oriented extension} -\item \ahref{libref/Option.html}{Module \texttt{Option}: option values} -\item \ahref{libref/Parsing.html}{Module \texttt{Parsing}: the run-time library for parsers generated by \texttt{ocamlyacc}} -\item \ahref{libref/Printexc.html}{Module \texttt{Printexc}: facilities for printing exceptions} -\item \ahref{libref/Printf.html}{Module \texttt{Printf}: formatting printing functions} -\item \ahref{libref/Queue.html}{Module \texttt{Queue}: first-in first-out queues} -\item \ahref{libref/Random.html}{Module \texttt{Random}: pseudo-random number generator (PRNG)} -\item \ahref{libref/Result.html}{Module \texttt{Result}: result values} -\item \ahref{libref/Scanf.html}{Module \texttt{Scanf}: formatted input functions} -\item \ahref{libref/Seq.html}{Module \texttt{Seq}: functional iterators} -\item \ahref{libref/Set.html}{Module \texttt{Set}: sets over ordered types} -\item \ahref{libref/Stack.html}{Module \texttt{Stack}: last-in first-out stacks} -\item \ahref{libref/StdLabels.html}{Module \texttt{StdLabels}: Include modules \texttt{Array}, \texttt{List} and \texttt{String} with labels} -\item \ahref{libref/Stream.html}{Module \texttt{Stream}: streams and parsers} -\item \ahref{libref/String.html}{Module \texttt{String}: string operations} -\item \ahref{libref/StringLabels.html}{Module \texttt{StringLabels}: string operations (with labels)} -\item \ahref{libref/Sys.html}{Module \texttt{Sys}: system interface} -\item \ahref{libref/Uchar.html}{Module \texttt{Uchar}: Unicode characters} -\item \ahref{libref/Unit.html}{Module \texttt{Unit}: unit values} -\item \ahref{libref/Weak.html}{Module \texttt{Weak}: arrays of weak pointers} -\end{links} -\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} -} +\begin{linklist} +\stddocitem{Arg}{parsing of command line arguments} +\stddocitem{Array}{array operations} +\stddocitem{ArrayLabels}{array operations (with labels)} +\stddocitem{Atomic}{atomic references} +\stddocitem{Bigarray}{large, multi-dimensional, numerical arrays} +\stddocitem{Bool}{boolean values} +\stddocitem{Buffer}{extensible buffers} +\stddocitem{Bytes}{byte sequences} +\stddocitem{BytesLabels}{byte sequences (with labels)} +\stddocitem{Callback}{registering OCaml values with the C runtime} +\stddocitem{Char}{character operations} +\stddocitem{Complex}{Complex numbers} +\stddocitem{Digest}{MD5 message digest} +\stddocitem{Either}{Either values} +\stddocitem{Ephemeron}{Ephemerons and weak hash table} +\stddocitem{Filename}{operations on file names} +\stddocitem{Float}{Floating-point numbers} +\stddocitem{Format}{pretty printing} +\stddocitem{Fun}{function values} +\stddocitem{Gc}{memory management control and statistics; finalized values} +\stddocitem{Genlex}{a generic lexical analyzer} +\stddocitem{Hashtbl}{hash tables and hash functions} +\stddocitem{Int}{integers} +\stddocitem{Int32}{32-bit integers} +\stddocitem{Int64}{64-bit integers} +\stddocitem{Lazy}{deferred computations} +\stddocitem{Lexing}{the run-time library for lexers generated by \texttt{ocamllex}} +\stddocitem{List}{list operations} +\stddocitem{ListLabels}{list operations (with labels)} +\stddocitem{Map}{association tables over ordered types} +\stddocitem{Marshal}{marshaling of data structures} +\stddocitem{MoreLabels}{Include modules \texttt{Hashtbl}, \texttt{Map} and \texttt{Set} with labels} +\stddocitem{Nativeint}{processor-native integers} +\stddocitem{Oo}{object-oriented extension} +\stddocitem{Option}{option values} +\stddocitem{Parsing}{the run-time library for parsers generated by \texttt{ocamlyacc}} +\stddocitem{Printexc}{facilities for printing exceptions} +\stddocitem{Printf}{formatting printing functions} +\stddocitem{Queue}{first-in first-out queues} +\stddocitem{Random}{pseudo-random number generator (PRNG)} +\stddocitem{Result}{result values} +\stddocitem{Scanf}{formatted input functions} +\stddocitem{Seq}{functional iterators} +\stddocitem{Set}{sets over ordered types} +\stddocitem{Stack}{last-in first-out stacks} +\stddocitem{StdLabels}{Include modules \texttt{Array}, \texttt{List} and \texttt{String} with labels} +\stddocitem{Stream}{streams and parsers} +\stddocitem{String}{string operations} +\stddocitem{StringLabels}{string operations (with labels)} +\stddocitem{Sys}{system interface} +\stddocitem{Uchar}{Unicode characters} +\stddocitem{Unit}{unit values} +\stddocitem{Weak}{arrays of weak pointers} +\ifouthtml\else +\stddocitem{Ocaml_operators}{} \fi +\end{linklist} diff --git a/manual/manual/macros.hva b/manual/manual/macros.hva index e0a323e04..fc3830f83 100644 --- a/manual/manual/macros.hva +++ b/manual/manual/macros.hva @@ -291,5 +291,13 @@ \newenvironment{maintitle}{\@open{div}{class="maintitle"}}{\@close{div}} -%%% References to modules in the standard library -\newcommand{\stdmoduleref}[1]{\ahref{libref/#1.html}{\texttt{#1}}} +%%% Linking to modules + +\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}} diff --git a/manual/manual/macros.tex b/manual/manual/macros.tex index ac1467b05..e36eb62d1 100644 --- a/manual/manual/macros.tex +++ b/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}} diff --git a/manual/manual/manual.inf b/manual/manual/manual.inf index e506905f3..a23e280e4 100644 --- a/manual/manual/manual.inf +++ b/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}} diff --git a/manual/tests/check-stdlib-modules b/manual/tests/check-stdlib-modules index 13fc14220..f06db1d16 100755 --- a/manual/tests/check-stdlib-modules +++ b/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