Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

manual: docitem macros for linking modules #9988

Merged
merged 2 commits into from
Oct 28, 2020
Merged

manual: docitem macros for linking modules #9988

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
669623c
manual: docitem macros for linking modules
Octachron Oct 23, 2020
9cd83fb
review: squash-me
Octachron Oct 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
41 changes: 14 additions & 27 deletions manual/manual/library/compilerlibs.etex
View file
Open in desktop
Expand Up @@ -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}
16 changes: 6 additions & 10 deletions manual/manual/library/core.etex
View file
Open in desktop
Expand Up @@ -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}
11 changes: 3 additions & 8 deletions manual/manual/library/libdynlink.etex
View file
Open in desktop
Expand Up @@ -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}
14 changes: 3 additions & 11 deletions manual/manual/library/libstr.etex
View file
Open in desktop
Expand Up @@ -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}
22 changes: 7 additions & 15 deletions manual/manual/library/libthreads.etex
View file
Open in desktop
Expand Up @@ -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}
19 changes: 8 additions & 11 deletions manual/manual/library/libunix.etex
View file
Open in desktop
Expand Up @@ -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
Expand All @@ -39,20 +38,18 @@ 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}

\section{s:Module \texttt{UnixLabels}: labelized version of the interface}
\section{Module \texttt{UnixLabels}: labelized version of the interface}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the s: looks like a search-and-replace bug here, right? But how come we are not using the new \section{label}{title} macro?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't remember how I inserted this s: here.

Part of the issue is that this section heading is the only one in the manual that is inside an ocamldocinput section, which reinstall the normal section macro.

I have pushed a change to get out earlier of the ocamldocinput mode and avoid this corner case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the new patch, the label is Unixlabels when I would maybe have expected s:Unixlabels, but I trust you to have done the right thing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have merely kept the previous label since the label is unused, not in conflict with other labels, and only exists in the pure latex version of the manual.

\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{linklist}
\end{latexonly}

\begin{windows}
Expand Down
170 changes: 57 additions & 113 deletions manual/manual/library/stdlib-blurb.etex
View file
Open in desktop
Expand Up @@ -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}
12 changes: 10 additions & 2 deletions manual/manual/macros.hva
View file
Open in desktop
Expand Up @@ -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}}
7 changes: 6 additions & 1 deletion manual/manual/macros.tex
View file
Open in desktop
Expand Up @@ -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}}


Expand Down
8 changes: 8 additions & 0 deletions manual/manual/manual.inf
View file
Open in desktop
Expand Up @@ -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}}