line edits for driver.mld

Signed-off-by: Christine Rose <[email protected]>

Author: christinerose

doc/driver.mld

@@ -1,14 +1,14 @@
-{0 How to drive [odoc]}
+{0 How to Drive [odoc]}
 
 This 'live' document describes how to use [odoc] to produce the documentation of [odoc] itself. The aim is
 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
-the package docs for
-{{: https://v3.ocaml.org/} v3.ocaml.org}.
+complete and comprehensive use of [odoc], see the {{: https://github.com/ocaml-doc/voodoo} Voodoo project}, 
+the tool used to build the 
+{{: https://v3.ocaml.org/} v3.ocaml.org} package docs.
 
-First we need to initialise MDX with some libraries and helpful values.
+First, we need to initialise MDX with some libraries and helpful values:
 
 {[
 (* Prelude *)
@@ -24,7 +24,8 @@ let get_ok = function | Ok x -> x | Error (`Msg m) -> failwith m
 
 {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:
+[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/odoc_model/index.html] : [odoc] model library subpage
@@ -37,9 +38,14 @@ let get_ok = function | Ok x -> x | Error (`Msg m) -> failwith m
 }{- [odoc/deps/...] : other dependencies
 }}
 
-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) or {e modules} (from [.cmti] files). 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].
+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) or {e modules} (from [.cmti] files). 
+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:
+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:
 
 {[
 odoc compile odoc.mld --child page-odoc_model --child deps ...
@@ -57,16 +63,25 @@ The file [odoc_model.mld] will have a child module [Odoc_model]. It will be comp
 odoc compile odoc_model.mld -I . --parent `odoc` --child module-Odoc_model
 ]}
 
-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.
+The parent page must exist before the child page is created, and it must have had the child specified 
+when it was initially compiled.
 
 {1 Document Generation Phases}
 
 Using [odoc] is a three-phase process:
 {ol {- Compilation: [odoc compile]
 
-This takes the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference), translates it into [odoc]'s internal format, and performs some initial expansion and resolution operations. 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 these files, 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]:
+This takes the output from the compiler in the form of [.cmti], [.cmt], or [.cmi] files (in order of preference), 
+translates it into [odoc]'s internal format, and performs some initial expansion and resolution operations. 
+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 these files, 
+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]:
 
@@ -79,27 +94,35 @@ Stdlib__uchar ab6f1df93abf9e800a3e0d1543523c96
 Odoc_xref2__Compile e0d620d652a724705f7ed620dfe07be0
 ]}
 
-so we can see we will need to run [odoc compile] against several [Stdlib] modules before we can compile [odoc_xref2__Compile.cmti]
+It's necessary to run [odoc compile] against several [Stdlib] modules before we can compile [odoc_xref2__Compile.cmti]
 }
 {- Linking: [odoc link]
 
 
-This takes the [odoc] files produced during the compilation step and performs the final steps of expansion and resolution. It is during this phase that all the references in the documentation comments are resolved. In order for these to be resolved, everything that is referenced must have been compiled already, and their [odoc] files must be on the
-include path as specified by the [-I] arguments to [odoc link]. In this example, we achieve that by compiling all modules and [.mld] files before linking anything. The output of the
+This takes the [odoc] files produced during the compilation step and performs the final steps of 
+expansion and resolution. It's during this phase that all the references in the documentation comments are 
+resolved. In order for these to be resolved, everything that's referenced must have been compiled already, 
+and their [odoc] files must be on the include path as specified by the [-I] arguments to [odoc link]. 
+In this example, we achieve that by compiling all modules and [.mld] files before linking anything. The output of the
 link step is an [odocl] file, which is in the same path as the original [odoc] file by default.
 
 Please note: it's only necessary to link the non-hidden modules (i.e., without a double underscore).
 }
 {- 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}
 
-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.
+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.
 }{- We'll do all of the compiling before any linking.
 }}
 
@@ -180,9 +203,10 @@ let support_files () =
 ]}
 
 We'll now make some library lists. We have not only external dependency libraries, but
-[odoc] itself is also separated into libraries too. These two sets of libraries will be
+[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.
-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.
 
 {[
@@ -253,7 +277,8 @@ let parents =
   add_parent "deps" dep_libraries @ add_parent "odoc" odoc_libraries
 ]}
 
-[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.
+[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:
 
 {[
@@ -273,7 +298,7 @@ let lib_paths =
 ]}
 
 We need a function to find [odoc] inputs given a 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, and the following
 function finds all matching files given a search path. Then it returns an [Fpath.Set.t]
 that contains the [Fpath.t] values representing the absolute file path, without its extension.
 
@@ -304,7 +329,7 @@ let best_file base =
   |> List.find (fun f -> Bos.OS.File.exists f |> get_ok)
 ]}
 
-Many of the units will be 'hidden' -- that is, their name will be mangled by Dune
+Many of the units will be 'hidden', meaning that Dune will mangle their name
 in order to namespace them. This is achieved by prefixing the namespace module and
 a double underscore, so we can tell by the existence of a double underscore that
 a module is intended to be hidden. The following predicate tests for that condition:
@@ -313,7 +338,8 @@ a module is intended to be hidden. The following predicate tests for that condit
 let is_hidden path = Astring.String.is_infix ~affix:"__" (Fpath.to_string path)
 ]}
 
-To build the documentation, we start with these files. With the following function, we'll call [odoc compile-deps] on the file to
+To build the documentation, we start with these files. With the following function, we'll 
+call [odoc compile-deps] on the file to
 find all other compilation units upon which it depends:
 
 {[
@@ -362,7 +388,9 @@ let all_units =
   odoc_units @ lib_units |> List.flatten
 ]}
 
-Now we'll compile all of the parent [.mld] files. To ensure that the parents are compiled before the children, we start with [odoc.mld], then [deps.mld], and so on. The result of this file is a list of the resulting [odoc] files.
+Now we'll compile all of the parent [.mld] files. To ensure that the parents are 
+compiled before the children, we start with [odoc.mld], then [deps.mld], and so on. The result 
+of this file is a list of the resulting [odoc] files.
 
 {[
 let compile_mlds () =
@@ -400,7 +428,13 @@ let compile_mlds () =
     ("page-odoc.odoc" :: "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 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.
 
 {[
 let compile_all () =
@@ -435,7 +469,9 @@ let compile_all () =
   @ mld_odocs
 ]}
 
-Linking is now straightforward. We only need to link non-hidden [odoc] files, as any hidden are almost certainly aliased inside the non-hidden ones (a result of namespacing usually, and these aliases will be expanded).
+Linking is now straightforward. We only need to link non-hidden [odoc] files, as 
+any hidden ones are almost certainly aliased inside the non-hidden ones 
+(a result of namespacing, usually, and these aliases will be expanded).
 
 {[
 let link_all odoc_files =
@@ -455,7 +491,7 @@ let generate_all odocl_files =
   support_files ()
 ]}
 
-The following code actually executes all of the above, and we're done!
+The following code executes all of the above, and we're done!
 
 {[
 let compiled = compile_all () in