From ef627af68c5d8f1a075f74f4eefbc1278c929cc0 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 05:46:27 -0700
Subject: [PATCH 01/12] line editing driver.mld

---
 doc/driver.mld | 138 ++++++++++++++++++++++++-------------------------
 1 file changed, 69 insertions(+), 69 deletions(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index dd3d51c535..b8292a5fb4 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -4,11 +4,11 @@ This 'live' document describes how to use [odoc] to produce the documentation of
 to show a short, simple example of how [odoc] can be used, covering most of the important features.
 The document built here includes not only the documentation of [odoc] itself, but it also builds the
 docs for a subset of [odoc]'s dependent libraries to show how this may be done. For a much more
-complete and comprehensive use of [odoc], see the {{: https://github.com/ocaml-doc/voodoo} Voodoo project}, the tool that is being used to build
+complete and comprehensive use of [odoc], see the {{: https://github.com/ocaml-doc/voodoo} Voodoo project}, the tool currently used to build
 the package docs for
 {{: https://ocaml.org/packages} ocaml.org/packages}. The information in this page is specific to
-odoc version 2.3 or later. For earlier
-versions see the [driver.md] or [driver.mld] files in the corresponding source distribution.
+[odoc] version 2.3 or later. For earlier
+versions, see the [driver.md] or [driver.mld] files in the corresponding source distribution.
 
 First, we need to initialise MDX with some libraries and helpful values:
 
@@ -24,28 +24,28 @@ let (>>|=) m f = m >>= fun x -> Ok (f x);;
 let get_ok = function | Ok x -> x | Error (`Msg m) -> failwith m
 let relativize p = Fpath.(v ".." // p) (* this driver is run from the [doc] dir *)
 
-(* Whether to instrument with landmarks. Result for each commands will be saved
+(* Whether to instrument with landmarks. Result for each command will be saved
    to directory [_build/default/doc/landmarks]. *)
 let instrument = false
 ]}
 
 {1 Desired Output}
 
-[odoc] produces output files (HTML or others) in a structured directory tree, so before running [odoc], the structure of the output must be decided. For these docs, we want the following structure:
-{ul {- [odoc/index.html] : main page
-}{- [odoc/{odoc_for_authors.html,...}] : other documentation pages
+[odoc] produces output files (HTML or others) in a structured directory tree, so before running [odoc], the output's structure must be decided. For these docs, we want the following structure:
+{ul {- [odoc/index.html] : Main page
+}{- [odoc/{odoc_for_authors.html,...}] : Other documentation pages
 }{- [odoc/odoc_model/index.html] : [odoc] model library subpage
 }{- [odoc/odoc_model/Odoc_model/index.html] : Module page for the module [Odoc_model]
 }{- [odoc/odoc_model/Odoc_model/...] : Further pages for the submodules of [Odoc_model]
-}{- [odoc/odoc_.../index.html] : other [odoc] library pages
-}{- [odoc/deps/stdlib/index.html] : stdlib main page
+}{- [odoc/odoc_.../index.html] : Other [odoc] library pages
+}{- [odoc/deps/stdlib/index.html] : `Stdlib` main page
 }{- [odoc/deps/stdlib/Stdlib/index.html] : Module page for the module [Stdlib]
-}{- [odoc/deps/astring/index.html] : astring main page
-}{- [odoc/deps/...] : other dependencies
-}{- [odoc/source/...] : rendered source files
+}{- [odoc/deps/astring/index.html] : `astring` main page
+}{- [odoc/deps/...] : Other dependencies
+}{- [odoc/source/...] : Rendered source files
 }}
 
-The [odoc] model for achieving this is that we have {e pages} ([.mld] files) that have {e children} which are either {e further pages} ([.mld] files), {e modules} (from [.cmti] files), or
+The [odoc] model for achieving this is that we have {e pages} ([.mld] files) that have {e children} that are either {e further pages} ([.mld] files), {e modules} (from [.cmti] files), or
 a {e source parent}. This {{!page-parent_child_spec}parent/child relationship} is specified on the command line. Parent pages must be {e compiled} by [odoc] before their children. Then compiling a page [mypage.mld] will produce the file [page-mypage.odoc].
 
 In the example below, there will be a file [odoc.mld] that corresponds with the top-level directory [odoc/]. It will be compiled as follows:
@@ -55,7 +55,7 @@ odoc compile odoc.mld --child page-odoc_model --child deps
   --child src-source ...
 ]}
 
-The file [deps.mld] which corresponds with the sub-directory [odoc/deps/], will be compiled as follows:
+The file [deps.mld], which corresponds with the subdirectory [odoc/deps/], will be compiled as follows:
 
 {@sh skip[
 odoc compile deps.mld -I . --parent page-odoc --child page-stdlib --child page-astring ...
@@ -73,7 +73,7 @@ The last type of page contains a list of paths to the source files that should b
 odoc source-tree source.map -I . --parent page-odoc
 ]}
 
-where the first few lines of [source.map] are:
+The first few lines of [source.map] will be:
 
 {@text[
 src/xref2/utils.ml
@@ -81,9 +81,9 @@ src/xref2/type_of.ml
 src/xref2/tools.ml
 ]}
 
-indicating the desire for the rendered source of [utils.ml] to be found as the file [odoc/source/src/xref2/utils.ml.html].
+The above indicates the desire for the rendered source of [utils.ml] to be found as the file [odoc/source/src/xref2/utils.ml.html].
 
-When compiling any [.mld] file, the parent and all children must be specified. Parents can only be pages from other [.mld] files, and children may be pages (from [.mld] files) or modules (from [.cmti]/[.cmt] or [.cmi] files).
+When compiling any [.mld] file, the parent and all children must be specified. Parents can only be pages from other [.mld] files, but children may be pages (from [.mld] files) or modules (from [.cmti]/[.cmt] or [.cmi] files).
 
 The parent page must exist before the child page is created, and it must have had the child specified when it was initially compiled.
 
@@ -93,11 +93,11 @@ Using [odoc] is a three-phase process:
 {ol {- Compilation: odoc compile
 }}
 
-This takes as input either [.mld] files containing pure odoc markup, or the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference). For [.mld] files, this step simply translates them into [odoc]'s internal format and writes the corresponding file. For example, given the input [foobar.mld], [odoc] will output [page-foobar.odoc]. There are no dependencies for compiling [.mld] files beyond the parent as outlined above.
+This takes as input either [.mld] files containing pure [odoc] markup, or the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference). For [.mld] files, this step simply translates them into [odoc]'s internal format and writes the corresponding file. For example, given the input [foobar.mld], [odoc] will output [page-foobar.odoc]. There are no dependencies for compiling [.mld] files beyond the parent as outlined above.
 
-For modules, compilation is the point where [odoc] performs some initial expansion and resolution operations, a process that usually introduces dependencies. For a given input [/path/to/file.cmti] it will output the file [/path/to/file.odoc] unless the [-o] option is used to override the output file. If there were [.cmi] dependencies required for OCaml to compile a particular module, then there will be equivalent [.odoc] dependencies needed for the [odoc compile] step. [odoc] will search for these dependencies in the paths specified with the [-I] directive on compilation. [odoc] provides a command to help with this: [odoc compile-deps].
+For modules, compilation is the point where [odoc] performs some initial expansion and resolution operations, a process that usually introduces dependencies. For a given input [/path/to/file.cmti], it will output the file [/path/to/file.odoc] unless the [-o] option is used to override the output file. If there were [.cmi] dependencies required for OCaml to compile a particular module, then there will be equivalent [.odoc] dependencies needed for the [odoc compile] step. [odoc] will search for these dependencies in the paths specified with the [-I] directive on compilation. [odoc] provides a command to help with this: [odoc compile-deps].
 
-As an example we can run [odoc compile-deps] on the file [../src/xref2/.odoc_xref2.objs/byte/odoc_xref2__Compile.cmti]:
+As an example, we can run [odoc compile-deps] on the file [../src/xref2/.odoc_xref2.objs/byte/odoc_xref2__Compile.cmti]:
 
 {@text[
 $ `odoc` compile-deps ../src/xref2/.odoc_xref2.objs/byte/odoc_xref2__Compile.cmti | tail -n 5
@@ -120,7 +120,7 @@ Please note: it's only necessary to link the non-hidden modules (i.e., without a
 {ol {- Generation: odoc html-generate
 }}
 
-Once the compile and link phases are complete, the resulting [odocl] files may be rendered in a variety of formats. In this example we output HTML.
+Once the compile and link phases are complete, the resulting [odocl] files may be rendered in a variety of formats. In this example we output HTML:
 
 {1 [odoc] Documentation}
 
@@ -132,20 +132,20 @@ In this section [odoc] is used to generate the documentation of [odoc] and some
 Let's start with some functions to execute the three phases of [odoc].
 
 Compiling a file with [odoc] requires a few arguments: the file to compile, an
-optional parent, a list of include paths, a list of children for [.mld] files
+optional parent, a list of include paths, a list of children for [.mld] files,
 and an output path. Include paths can be just ['.'], and we can calculate the
-output file from the input because all of the files are going into the same
+output file from the input because all the files go into the same
 directory.
 
-Odoc supports compiling {i implementations}. This can be useful to render source
+[odoc] supports compiling {i implementations}. This can be useful to render source
 code, generate links from and to source code, and count occurrences of
-identifiers. The [compile-src] command takes a source-tree parent file, and a
-source path which has to be in the source tree.
+identifiers. The [compile-src] command takes a source-tree parent file and a
+source path, which has to be in the source tree.
 
 Linking a file with [odoc] requires the input file and a list of include paths. As
 for compile, we will hard-code the include path.
 
-Generating the HTML requires the input [odocl] file, and an output path. We will
+Generating the HTML requires the input [odocl] file and an output path. We will
 hard-code the output path to be [html/]. In the case of implementations, a
 source file (passed via the [--source] argument) is required.
 
@@ -155,7 +155,7 @@ command on the "implementation" units.
 In all of these, we'll capture [stdout] and [stderr] so we can check it later.
 
 {[
-let odoc = Cmd.v "../src/odoc/bin/main.exe" (* This is the just-built odoc binary *)
+let odoc = Cmd.v "../src/odoc/bin/main.exe" (* This is the just-built [odoc] binary *)
 
 let compile_output = ref [ "" ]
 
@@ -312,10 +312,10 @@ let count_occurrences output =
 We'll now make some library lists. We have not only external dependency
 libraries, but [odoc] itself is also separated into libraries. These two
 sets of libraries will be documented in different sections, so we'll keep them
-in separate lists. Moreover, [odoc] libraries will include the source code, via
-a hardcoded path.
+in separate lists. Moreover, [odoc] libraries will include the source code via
+a hard-coded path.
 
-Additionally we'll also construct a list containing the extra documentation pages. Finally let's create a list mapping the section to its parent, which matches
+Additionally, we'll construct a list containing the extra documentation pages. Finally let's create a list mapping the section to its parent, which matches
 the hierarchy declared above.
 
 {[
@@ -408,7 +408,7 @@ let parents =
 
 [odoc] operates on the compiler outputs. We need to find them for both the files compiled by Dune within this project and those in libraries we compile against.
 The following uses [ocamlfind] to locate the library paths for our dependencies. Since [ocamlfind] gives
-us the absolute path, we also have a short function here to relativize it based on our current working
+us the absolute path, we also have a short function here to relativise it based on our current working
 directory to ensure the log of commands we collect is as reproducible as possible.
 
 {[
@@ -439,7 +439,7 @@ let lib_paths =
 ]}
 
 We need a function to find [odoc] inputs from the given search path. [odoc]
-operates on [.cmti], [.cmt], or [.cmi] files, in order of preference, and the following
+operates on [.cmti], [.cmt], or [.cmi] files, in order of preference. The following
 function finds all matching files starting from the given path. Then it returns an [Fpath.Set.t]
 that contains the [Fpath.t] values representing the absolute file path, without its extension.
 
@@ -462,7 +462,7 @@ let find_units p =
   List.fold_right Fpath.Set.add l Fpath.Set.empty;;
 ]}
 
-Since the units returned by this function have their extension stripped, we need
+Since the units returned by this function have their extension stripped, we need a
 function to find the best file to use with this basename.
 
 {[
@@ -496,9 +496,9 @@ let compile_deps f =
   | _ -> Error (`Msg "odd")
 ]}
 
-For each compiled odoc file, we'll need to remember some options given at [odoc
-compile]-time. An example of this is the source code rendering: when we compile
-an implementation unit, we need to provide the source file at html generation.
+For each compiled [odoc] file, we'll need to remember some options given at [odoc
+compile]-time. An example of this is the source code rendering. When we compile
+an implementation unit, we need to provide the source file at HTML generation.
 
 {[
 type unit = {
@@ -511,7 +511,7 @@ type unit = {
 
 For [odoc] libraries, we infer the implementation and interface source file path
 from the library name. We list them in a file, passed to [odoc source-tree], to
-generate [src-source.odoc]. This file contains the source hierarchy, and will be
+generate [src-source.odoc]. This file contains the source hierarchy. It will be
 linked and passed to [html-generate] just as other pages and compilation units.
 
 It is used as the [source-parent] for all units for which we could provide
@@ -575,7 +575,7 @@ let compile_source_tree units =
 ]}
 
 Let's now put together a list of all possible modules. We'll keep track of
-which library they're in, and whether that library is a part of [odoc] or a dependency
+which library they're in and whether that library is a part of [odoc] or a dependency
 library.
 
 {[
@@ -610,7 +610,7 @@ let all_units =
   odoc_units @ lib_units |> List.flatten
 ]}
 
-Generate the {!api_reference} page to list Odoc's libraries:
+Generate the {!api_reference} page to list [odoc]'s libraries:
 
 {[
 let update_api_reference_page () =
@@ -675,7 +675,7 @@ let compile_mlds () =
     ( "page-deps.odoc" :: odocs @ extra_odocs)
 ]}
 
-Now we get to the compilation phase. For each unit, we query its dependencies, then recursively call to compile these dependencies. Once this is done we compile the unit itself. If the unit has already been compiled we don't do anything. Note that we aren't checking the hashes of the dependencies which a build system should do to ensure that the module being compiled is the correct one. Again we benefit from the fact that we're creating the docs for one leaf package and that there must be no module name clashes in its dependencies. The result of this function is a list of the resulting [odoc] files.
+Now we get to the compilation phase. For each unit, we query its dependencies, then recursively call to compile these dependencies. Once completed, we compile the unit itself. If the unit has already been compiled, we don't do anything. Note that we aren't checking the hashes of the dependencies which a build system should do to ensure that the module being compiled is the correct one. Again we benefit from the fact that we're creating the docs for one leaf package and that there must be no module name clashes in its dependencies. The result of this function is a list of the resulting [odoc] files.
 
 {[
 let compile_all () =
@@ -738,9 +738,9 @@ let link_all odoc_files =
     odoc_files
 ]}
 
-Now we simply run [odoc html-generate] over all of the resulting [odocl] files.
+Now we simply run [odoc html-generate] over all the resulting [odocl] files.
 This will generate sources, as well as documentation for non-hidden units.
-We notify the generator that the javascript file to use for search is [index.js].
+We notify the generator that the JavaScript file to use for search is [index.js].
 
 {[
 let generate_all odocl_files =
@@ -757,30 +757,30 @@ let generate_all odocl_files =
 ]}
 
 
-Finally, we generate an index of all values, types, etc. This index is meant to be consumed by search engines, to create their own index. It is in json format. Generating the index is done via [odoc compile-index], which creates a json file.
+Finally, we generate an index of all values, types, etc. This index is meant to be consumed by search engines in order to create their own index. It is in JSON format. Generating the index is done via [odoc compile-index], which creates a JSON file.
 
-Some more details about the json format:
+Some more details about the JSON format:
 
 {ul
-  {- The whole file is a json array.}
-  {- each entry of the array corresponds to an item to search. An entry is a json object, with the following fields:
+  {- The whole file is a JSON array.}
+  {- Each array entry corresponds to an item to search. An entry is a JSON object, with the following fields:
      {ul
-       {- ["id"], which is a string. It corresponds to the id of the entry, for instance: ["Stdlib.List.map"].}
-       {- ["doc"], which is a string. It corresponds to a "searchable" version of the docstring: one which is stripped from any html or specific markup. This is to avoid having too many results when searching ["class"], for instance.}
-       {- ["kind"] is a json object. It contains the fields:
+       {- ["id"], which is a string. It corresponds to the entry's ID, for instance: ["Stdlib.List.map"].}
+       {- ["doc"], which is a string. It corresponds to a "searchable" version of the docstring, one which is stripped from any HTML or specific markup. This is to avoid having too many results when searching ["class"], for instance.}
+       {- ["kind"] is a JSON object. It contains the fields:
           {ul
             {- ["kind"], a string encoding the kind of the entry (type, value, module, standalone comment, etc.)}
-            {- any information that is specific to it (for instance, a type has kind ["TypeDecl"] and also contains the constraints, manifest, and whether the type is private or not). For a comprehensive description of what information is available in this field, please refer to the source file: src/search/json_index/json_search.ml}}}
-       {- ["display"], which is a json object. It contains two fields:
+            {- Any information that is specific to it (for instance, a type has kind ["TypeDecl"] and also contains the constraints, manifest, and whether the type is private or not). For a comprehensive description of the information available in this field, please refer to the source file: src/search/json_index/json_search.ml}}}
+       {- ["display"], which is a JSON object. It contains two fields:
           {ul
             {- ["url"], a string. It is the URL to the entry in the documentation, relative to the base of the documentation}
-            {- ["html"], also a string. It is the html odoc uses to display the entry in the search results.}}}
-       {- Additionally, the ["occurrences"] field exists if and only if the [--occurrences] flag was given to the [odoc compile-index] command. When it exists, it contains a json object, with two fields:
+            {- ["html"], also a string. It is the HTML [odoc] uses to display the entry in the search results.}}}
+       {- Additionally, the ["occurrences"] field exists if and only if the [--occurrences] flag was given to the [odoc compile-index] command. When it exists, it contains a JSON object, with two fields:
           {ul
-            {- ["direct"], an integer. It is the number of direct uses of the entry. For instance, [open M] and [Make(M)] contain direct uses of [M], while [1 + M.v] contains an indirect use of [M] and a direct use of [M.v].}
-            {- ["indirect"], an integer containing the number of indirect uses of the entry.}}}}}}
+            {- ["direct"], an integer. It is the number of the entry's direct uses. For instance, [open M] and [Make(M)] contain direct uses of [M], while [1 + M.v] contains an indirect use of [M] and a direct use of [M.v].}
+            {- ["indirect"], an integer containing the number of the entry's indirect uses.}}}}}}
 
-Search engines written in OCaml can also call the [Odoc_model.Fold.unit] and  [Odoc_model.Fold.page] function, in conjunction with [Odoc_search.Entry.entry_of_item] in order to get an OCaml value of each element to be indexed.
+Search engines written in OCaml can also call the [Odoc_model.Fold.unit] and [Odoc_model.Fold.page] function, in conjunction with [Odoc_search.Entry.entry_of_item] to get an OCaml value of each element to be indexed.
 
 {[
 let index_generate ?(ignore_output = false) occurrence_file =
@@ -804,13 +804,13 @@ let index_generate ?(ignore_output = false) occurrence_file =
     add_prefixed_output cmd generate_output "index compilation" lines
 ]}
 
-We turn the JSON index into a javascript file. In order to never block the UI, this file will be used as a web worker by [odoc], to perform searches:
+We turn the JSON index into a JavaScript file. In order to never block the UI, this file will be used as a web worker by [odoc] to perform searches:
 
-- The search query will be sent as a plain string to the web worker, using the standard mechanism of message passing
-- The web worker has to sent back the result as a message to the main thread, containing the list of result. Each entry of this list must have the same form as it had in the original JSON file.
+- The search query will be sent as a plain string to the web worker, using the standard mechanism of message passing.
+- The web worker has to send back the result as a message to the main thread, containing the list of result. Each entry of this list must have the same form it had in the original JSON file.
 - The file must be given to the [odoc-support] URI.
 
-In this driver, we use the minisearch javascript library. For more involved application, we could use [index.js] to call a server-side search engine via an API call.
+In this driver, we use the MiniSearch JavaScript library. For more involved applications, we could use [index.js] to call a server-side search engine via an API call.
 
 {[
   let js_index () =
@@ -833,7 +833,7 @@ In this driver, we use the minisearch javascript library. For more involved appl
  })
 
 
- // Use a unique id since some entries' id are not unique (type extension or
+ // Use a unique ID since some entries' IDs are not unique (type extension or
  // standalone doc comments for instance)
  documents.forEach((entry,i) => entry.entry_id = i)
  miniSearch.addAll(documents);
@@ -940,7 +940,7 @@ html/odoc/odoc_html/Odoc_html/Types
 html/odoc/odoc_html/Odoc_html/Types/index.html
 ]}
 
-Some code to analyze the list of executed commands:
+Some code to analyse the list of executed commands:
 
 {[
 (** Return the list of executed commands where the first argument was [cmd]. *)
@@ -973,7 +973,7 @@ If needed, the list of commands executed so far can be shown by de-commenting th
 # (* List.iter print_cmd (List.rev !commands);; *)
 ]}
 
-If needed, the list of the slowest commands for each subcommands can be shown by de-commenting this block:
+If needed, the list of the slowest commands for each subcommand can be shown by de-commenting this block:
 (for the record, these commands are run from directory `_build/default/doc`)
 
 {[
@@ -982,7 +982,7 @@ If needed, the list of the slowest commands for each subcommands can be shown by
 # (* List.iter print_cmd (k_longest_commands "html-generate" 5) *)
 ]}
 
-This last block analyze the running times so that they can be submitted to
+This last block analyses the running times so that they can be submitted to
 {{:https://github.com/ocurrent/current-bench}current-bench}.
 
 {[
@@ -1022,7 +1022,7 @@ let compute_metric_int prefix suffix description values =
       ];
   ]
 
-(** Analyze the running time of a command. *)
+(** Analyse the running time of a command. *)
 let compute_metric_cmd cmd =
   let cmds = filter_commands cmd in
   let times = List.map (fun c -> c.time) cmds in
@@ -1046,7 +1046,7 @@ let compute_metric_cmd cmd =
       ];
   ]
 
-(** Analyze the size of files produced by a command. *)
+(** Analyse the size of files produced by a command. *)
 let compute_produced_cmd cmd =
   let output_file_size c =
     match c.output_file with
@@ -1061,7 +1061,7 @@ let compute_produced_cmd cmd =
     ("files produced by 'odoc " ^ cmd ^ "'")
     sizes
 
-(** Analyze the size of files outputed to the given directory. *)
+(** Analyse the file size outputed to the given directory. *)
 let compute_produced_tree cmd dir =
   let acc_file_sizes path acc =
     match Bos.OS.Path.stat path with
@@ -1073,7 +1073,7 @@ let compute_produced_tree cmd dir =
   |> get_ok
   |> compute_metric_int "produced" cmd ("files produced by 'odoc " ^ cmd ^ "'")
 
-(** Analyze the running time of the slowest commands. *)
+(** Analyse the running time of the slowest commands. *)
 let compute_longest_cmd cmd =
   let k = 5 in
   let cmds = k_longest_commands cmd k in

From b492a82acc8d3523696be66793e86301e4d0b649 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 05:49:39 -0700
Subject: [PATCH 02/12] singular "file" instead of plural with "or"

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index b8292a5fb4..ad7cfcfb10 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -8,7 +8,7 @@ complete and comprehensive use of [odoc], see the {{: https://github.com/ocaml-d
 the package docs for
 {{: https://ocaml.org/packages} ocaml.org/packages}. The information in this page is specific to
 [odoc] version 2.3 or later. For earlier
-versions, see the [driver.md] or [driver.mld] files in the corresponding source distribution.
+versions, see the [driver.md] or [driver.mld] file in the corresponding source distribution.
 
 First, we need to initialise MDX with some libraries and helpful values:
 

From 60fad566d8cc8e71472d5bdcc852d8cd8842266f Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 05:50:40 -0700
Subject: [PATCH 03/12] remove comma

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index ad7cfcfb10..c481ece3aa 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -93,7 +93,7 @@ Using [odoc] is a three-phase process:
 {ol {- Compilation: odoc compile
 }}
 
-This takes as input either [.mld] files containing pure [odoc] markup, or the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference). For [.mld] files, this step simply translates them into [odoc]'s internal format and writes the corresponding file. For example, given the input [foobar.mld], [odoc] will output [page-foobar.odoc]. There are no dependencies for compiling [.mld] files beyond the parent as outlined above.
+This takes as input either [.mld] files containing pure [odoc] markup or the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference). For [.mld] files, this step simply translates them into [odoc]'s internal format and writes the corresponding file. For example, given the input [foobar.mld], [odoc] will output [page-foobar.odoc]. There are no dependencies for compiling [.mld] files beyond the parent as outlined above.
 
 For modules, compilation is the point where [odoc] performs some initial expansion and resolution operations, a process that usually introduces dependencies. For a given input [/path/to/file.cmti], it will output the file [/path/to/file.odoc] unless the [-o] option is used to override the output file. If there were [.cmi] dependencies required for OCaml to compile a particular module, then there will be equivalent [.odoc] dependencies needed for the [odoc compile] step. [odoc] will search for these dependencies in the paths specified with the [-I] directive on compilation. [odoc] provides a command to help with this: [odoc compile-deps].
 

From b64e5a7769a9647903410d0878c0f570673ce8ab Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 05:57:13 -0700
Subject: [PATCH 04/12] added comma

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index c481ece3aa..7864acfbcd 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -512,7 +512,7 @@ type unit = {
 For [odoc] libraries, we infer the implementation and interface source file path
 from the library name. We list them in a file, passed to [odoc source-tree], to
 generate [src-source.odoc]. This file contains the source hierarchy. It will be
-linked and passed to [html-generate] just as other pages and compilation units.
+linked and passed to [html-generate], just as other pages and compilation units.
 
 It is used as the [source-parent] for all units for which we could provide
 sources.

From 183b7328d661107fc333b40801fa9ce28483313d Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 06:02:30 -0700
Subject: [PATCH 05/12] make "list of results" plural

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index 7864acfbcd..f4c358944f 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -807,7 +807,7 @@ let index_generate ?(ignore_output = false) occurrence_file =
 We turn the JSON index into a JavaScript file. In order to never block the UI, this file will be used as a web worker by [odoc] to perform searches:
 
 - The search query will be sent as a plain string to the web worker, using the standard mechanism of message passing.
-- The web worker has to send back the result as a message to the main thread, containing the list of result. Each entry of this list must have the same form it had in the original JSON file.
+- The web worker has to send back the result as a message to the main thread, containing the list of results. Each entry of this list must have the same form it had in the original JSON file.
 - The file must be given to the [odoc-support] URI.
 
 In this driver, we use the MiniSearch JavaScript library. For more involved applications, we could use [index.js] to call a server-side search engine via an API call.

From 0cef09b01c3d03e18cf7634e8021243a8ad6e17c Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Mon, 29 Jul 2024 06:14:02 -0700
Subject: [PATCH 06/12] line editing ocamldoc_differences.mld

---
 doc/ocamldoc_differences.mld | 54 ++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/doc/ocamldoc_differences.mld b/doc/ocamldoc_differences.mld
index 5c1ce16d7a..238da13004 100644
--- a/doc/ocamldoc_differences.mld
+++ b/doc/ocamldoc_differences.mld
@@ -1,4 +1,4 @@
-{0 Markup Differences from OCamldoc}
+{0 Markup Differences From OCamldoc}
 
 The canonical description of the markup that [odoc] understands is in {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#s%3Aocamldoc-comments}this section}
 of the OCaml reference manual. The eventual aim is to support the in-code markup
@@ -13,20 +13,20 @@ can be seen rendered by [odoc] {{!Odoc_examples.Markup.Foo}here}.
 The following describes the changes between what [odoc] understands and what’s in the OCaml manual.
 
 - Heading levels are more restrictive. In the manual, it suggests any whole number is acceptable. In [odoc],
-  similarly to the HTML spec, we allow headings from 1-5, and heading level [0] for the title
+  similarly to the HTML spec, we allow headings from 1-5. Heading level [0] is for the title
   of [.mld] files. [odoc] emits a warning for heading levels outside this range and caps them.
 
 {3 Omissions}
-- Comments describing class inheritance are not rendered ({{:https://github.com/ocaml/odoc/issues/574}github issue}).
+- Comments describing class inheritance are not rendered ({{:https://github.com/ocaml/odoc/issues/574}GitHub issue}).
 - [odoc] handles ambiguous documentation comments as the compiler does (see {{:https://caml.inria.fr/pub/docs/manual-ocaml/doccomments.html}here})
   rather than treating them as the OCamldoc manual suggests.
-- [odoc] doesn’t ignore tags that don't make sense (e.g., [@param] tags on instance variables are rendered) ({{:https://github.com/ocaml/odoc/issues/575}github issue})
-- {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-formatting}Alignment elements} are not handled ([{C text}], [{L text}] and [{R text}]) ({{:https://github.com/ocaml/odoc/issues/541}github issue})
-- [odoc] does not recognise {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-html-tags}html tags embedded in comments} ({{:https://github.com/ocaml/odoc/issues/576}github issue})
-- [{!indexlist}] is not supported ({{:https://github.com/ocaml/odoc/issues/577}github issue})
+- [odoc] doesn’t ignore tags that don't make sense (e.g., [@param] tags on instance variables are rendered) ({{:https://github.com/ocaml/odoc/issues/575}GitHub issue}).
+- {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#ss:ocamldoc-formatting}Alignment elements} are not handled ([{C text}], [{L text}], and [{R text}]) ({{:https://github.com/ocaml/odoc/issues/541}GitHub issue}).
+- [odoc] does not recognise {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-html-tags}HTML tags embedded in comments} ({{:https://github.com/ocaml/odoc/issues/576}GitHub issue}).
+- [{!indexlist}] is not supported ({{:https://github.com/ocaml/odoc/issues/577}GitHub issue}).
 - The first paragraph is used for synopses instead of the {{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sss:ocamldoc-preamble}first sentence}.
   Synopses are used when rendering declarations (of modules, classes, etc.) and [{!modules:...}] lists.
-  An other difference is that documentation starting with a heading or something that is not a paragraph won't have a synopsis ({{:https://github.com/ocaml/odoc/pull/643}github issue}).
+  Another difference is that documentation starting with a heading or something that is not a paragraph won't have a synopsis ({{:https://github.com/ocaml/odoc/pull/643}GitHub issue}).
 
 {3 Improvements}
 - [odoc] supports writing mathematics and tables with a specific syntax.
@@ -34,10 +34,10 @@ The following describes the changes between what [odoc] understands and what’s
 - Built-in support for standalone [.mld] files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.
 - Structured output: [odoc] can produce output in a structured directory tree rather a set of files.
 - A few extra tags are supported:
-  + [@returns] is a synonym for [@return]
-  + [@raises] is a synonym for [@raise]
-  + [@open] and [@closed] and [@inline] are hints for how 'included' signatures should be rendered
-  + [@canonical] allows a definition of a [module], [module type] or [type] to be marked as canonically elsewhere. 
+  + [@returns] is a synonym for [@return].
+  + [@raises] is a synonym for [@raise].
+  + [@open] and [@closed] and [@inline] are hints for how 'included' signatures should be rendered.
+  + [@canonical] allows a definition of a [module], [module type], or [type] to be marked as canonically elsewhere. 
 
 {2 Reference Syntax}
 [odoc] has a far more powerful reference resolution mechanism than OCamldoc. While it supports the mechanism in OCamldoc used for disambiguating between different types of references,
@@ -46,25 +46,25 @@ where the reference manual suggests the syntax [{!type:Foo.Bar.t}] to designate
 comments would be [{!Foo.Bar.type-t}] and [{!Foo.Bar.val-t}]. This allows [odoc] to disambiguate when there are other ambiguous elements within the path. For example, we can
 distinguish between a type or [value t] within a module or module type with the same name: [{!module-Foo.module-type-Bar.type-t}] or [{!module-type-Foo.module-Bar.val-t}].
 
-Additionally we support extra annotations:
-- [module-type] is a replacement for [modtype]
-- [class-type] is a replacement for [classtype]
-- [exn] is recognised as [exception]
-- [extension] refers to a type extension
-- [extension-decl] refers to the declaration point of an extension constructor
-- [field] is a replacement for [recfield]
-- [instance-variable] refers to instance variables
-- [label] refers to labels introduced in anchors
-- [page] refers to [.mld] pages as outlined above
-- [value] is recognised as [val]
+Additionally, we support extra annotations:
+- [module-type] is a replacement for [modtype].
+- [class-type] is a replacement for [classtype].
+- [exn] is recognised as [exception].
+- [extension] refers to a type extension.
+- [extension-decl] refers to the declaration point of an extension constructor.
+- [field] is a replacement for [recfield].
+- [instance-variable] refers to instance variables.
+- [label] refers to labels introduced in anchors.
+- [page] refers to [.mld] pages as outlined above.
+- [value] is recognised as [val].
 
-Moreover, [odoc] adds support for referencing of polymorphic variants in type
+Moreover, [odoc] adds support for referencing polymorphic variants in type
 aliases such as [type t = [ `A ]]. The [constructor] annotation is extended for
 polymorphic variants.
 
-{3 Referencing items containing hyphens or dots}
+{3 Referencing Items Containing Hyphens or Dots}
 
-If it is necessary to reference a reference that contains hyphens or dots - e.g. if you have a file [docs-with-dashes.mld] or
-[docs.with.dots.mld], to reference them use quotation marks in the reference. For the previous two examples, the references
+If it is necessary to reference a reference that contains hyphens or dots (e.g., if you have a file [docs-with-dashes.mld] or
+[docs.with.dots.mld]) use quotation marks in the reference. For the previous two examples, the references
 would be [{!page-"docs-with-dashes"}] and [{!page-"docs.with.dots"}].
 

From 8308cc430076acbe3db55d63098158ba2efc8308 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Tue, 30 Jul 2024 05:07:54 -0700
Subject: [PATCH 07/12] correct monospace format

Co-authored-by: panglesd <peada@free.fr>
---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index f4c358944f..cc5adb835f 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -38,7 +38,7 @@ let instrument = false
 }{- [odoc/odoc_model/Odoc_model/index.html] : Module page for the module [Odoc_model]
 }{- [odoc/odoc_model/Odoc_model/...] : Further pages for the submodules of [Odoc_model]
 }{- [odoc/odoc_.../index.html] : Other [odoc] library pages
-}{- [odoc/deps/stdlib/index.html] : `Stdlib` main page
+}{- [odoc/deps/stdlib/index.html] : [Stdlib] main page
 }{- [odoc/deps/stdlib/Stdlib/index.html] : Module page for the module [Stdlib]
 }{- [odoc/deps/astring/index.html] : `astring` main page
 }{- [odoc/deps/...] : Other dependencies

From 80ba0119aa5fa16d9eb9440752693b10c5b478e1 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Tue, 30 Jul 2024 05:08:09 -0700
Subject: [PATCH 08/12] correct monospace format

Co-authored-by: panglesd <peada@free.fr>
---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index cc5adb835f..3f679ba00e 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -40,7 +40,7 @@ let instrument = false
 }{- [odoc/odoc_.../index.html] : Other [odoc] library pages
 }{- [odoc/deps/stdlib/index.html] : [Stdlib] main page
 }{- [odoc/deps/stdlib/Stdlib/index.html] : Module page for the module [Stdlib]
-}{- [odoc/deps/astring/index.html] : `astring` main page
+}{- [odoc/deps/astring/index.html] : [astring] main page
 }{- [odoc/deps/...] : Other dependencies
 }{- [odoc/source/...] : Rendered source files
 }}

From 7d858bd21b65eac38be1c74669b4e14274d26011 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Wed, 31 Jul 2024 05:28:39 -0700
Subject: [PATCH 09/12] clarify source tree sentence in 146

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index 3f679ba00e..69a8bda83c 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -140,7 +140,7 @@ directory.
 [odoc] supports compiling {i implementations}. This can be useful to render source
 code, generate links from and to source code, and count occurrences of
 identifiers. The [compile-src] command takes a source-tree parent file and a
-source path, which has to be in the source tree.
+source path that has to be in the source tree.
 
 Linking a file with [odoc] requires the input file and a list of include paths. As
 for compile, we will hard-code the include path.

From 8df720debecc5afe7b98670225d1d5228a96ecc1 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Tue, 30 Jul 2024 04:53:13 -0700
Subject: [PATCH 10/12] minor grammar

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index 69a8bda83c..9d2dd88db1 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -675,7 +675,7 @@ let compile_mlds () =
     ( "page-deps.odoc" :: odocs @ extra_odocs)
 ]}
 
-Now we get to the compilation phase. For each unit, we query its dependencies, then recursively call to compile these dependencies. Once completed, we compile the unit itself. If the unit has already been compiled, we don't do anything. Note that we aren't checking the hashes of the dependencies which a build system should do to ensure that the module being compiled is the correct one. Again we benefit from the fact that we're creating the docs for one leaf package and that there must be no module name clashes in its dependencies. The result of this function is a list of the resulting [odoc] files.
+Now we get to the compilation phase. For each unit, we query its dependencies, then recursively call to compile these dependencies. Once completed, we compile the unit itself. If the unit has already been compiled, we don't do anything. Note that we aren't checking the hashes of the dependencies, which a build system should do to ensure that the module being compiled is the correct one. Again, we benefit from the fact that we're creating the docs for one leaf package and that there must be no module name clashes in its dependencies. The result of this function is a list of the resulting [odoc] files.
 
 {[
 let compile_all () =

From 4215d29745d920bd5fc4011d5fe849f4256e605c Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Tue, 30 Jul 2024 04:53:36 -0700
Subject: [PATCH 11/12] Remove unnecessary words

---
 doc/driver.mld | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index 9d2dd88db1..f34b52e313 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -514,7 +514,7 @@ from the library name. We list them in a file, passed to [odoc source-tree], to
 generate [src-source.odoc]. This file contains the source hierarchy. It will be
 linked and passed to [html-generate], just as other pages and compilation units.
 
-It is used as the [source-parent] for all units for which we could provide
+It is used as the [source-parent] for all units with provided
 sources.
 
 {[

From e7234a323d3d0873baeacf9b99484953e4c58335 Mon Sep 17 00:00:00 2001
From: Christine Rose <christinerose@users.noreply.github.com>
Date: Tue, 30 Jul 2024 04:59:19 -0700
Subject: [PATCH 12/12] make "hardcode" consistent

---
 doc/driver.mld | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/driver.mld b/doc/driver.mld
index f34b52e313..d7da944d5f 100644
--- a/doc/driver.mld
+++ b/doc/driver.mld
@@ -125,7 +125,7 @@ Once the compile and link phases are complete, the resulting [odocl] files may b
 {1 [odoc] Documentation}
 
 In this section [odoc] is used to generate the documentation of [odoc] and some of its dependent packages. We can make a few simplifying assumptions here:
-{ol {- Since we're working with one leaf package, we can assume that there can be no module name clashes in the dependencies. As such, we can afford to put all of our [.odoc] files into one directory and then hard-code the include path to be this directory. When using [odoc] in a context where there may be module name clashes, it requires more careful partitioning of output directories.
+{ol {- Since we're working with one leaf package, we can assume that there can be no module name clashes in the dependencies. As such, we can afford to put all of our [.odoc] files into one directory and then hardcode the include path to be this directory. When using [odoc] in a context where there may be module name clashes, it requires more careful partitioning of output directories.
 }{- We'll do all of the compiling before any linking.
 }}
 
@@ -143,10 +143,10 @@ identifiers. The [compile-src] command takes a source-tree parent file and a
 source path that has to be in the source tree.
 
 Linking a file with [odoc] requires the input file and a list of include paths. As
-for compile, we will hard-code the include path.
+for compile, we will hardcode the include path.
 
 Generating the HTML requires the input [odocl] file and an output path. We will
-hard-code the output path to be [html/]. In the case of implementations, a
+hardcode the output path to be [html/]. In the case of implementations, a
 source file (passed via the [--source] argument) is required.
 
 To get the number of uses of each identifier, we can use the [count-occurrences]
@@ -313,7 +313,7 @@ We'll now make some library lists. We have not only external dependency
 libraries, but [odoc] itself is also separated into libraries. These two
 sets of libraries will be documented in different sections, so we'll keep them
 in separate lists. Moreover, [odoc] libraries will include the source code via
-a hard-coded path.
+a hardcoded path.
 
 Additionally, we'll construct a list containing the extra documentation pages. Finally let's create a list mapping the section to its parent, which matches
 the hierarchy declared above.