Line edits for Manual doc #5641

christinerose · 2023-08-24T10:30:03Z

Please update master_changes.md file with your changes.

As requested in my previous PR, I've separated commits between Capitalisation, Grammar/Punctuation, and Syntax/Rewording. Hopefully it's less tedious for reviewers.

Please ensure my changes are still accurate. I'll have more questions in the PR to establish clarity in several places as well.

christinerose · 2023-08-24T10:38:40Z

Need clarification:

li 87-90

Repository selection is always ordered, with the
definition of a given version of a package being taken from the repository with
the lowest index where it is found.

Would it be correct to say: "Repository selection is always ordered. The
definition of a given package version is taken from the repository with
the lowest index where it is found."

Even this is still a little confusing. What does does "where it is found" mean? In the same directory?

christinerose · 2023-08-24T10:50:29Z

There are several other comments/questions I have about this doc, mostly for clarification, but I'll wait to ask any more until these are addressed (to avoid too much noise and confusion all at once!)

christinerose · 2023-09-04T11:24:13Z

Before I forget my other questions, I'll add them now, so they maintainers can get to these comments/suggestions when they have time.

Do these suggestions this make it more clear?

christinerose · 2023-08-24T10:48:08Z

doc/pages/Manual.md

+- For local switches, which are external to the opam root, when in the directory
+  where the switch resides or a descendant
+- By setting the `OPAMSWITCH=<switch>` environment variable, to set it within a
  single shell session. This can be done by running `eval $(opam env --switch


Suggested change

- For local switches, which are external to the opam root, when in the directory

where the switch resides or a descendant

- By setting the `OPAMSWITCH=<switch>` environment variable, to set it within a

single shell session. This can be done by running `eval $(opam env --switch

- For local switches, which are external to the opam root, when in the directory

where the switch resides or a descendant

- By setting the `OPAMSWITCH=<switch>` environment variable, to set it within a

single shell session. This can be done by running `eval $(opam env --switch

This could use some clarification.
"For local switches..." there is no action here. It doesn't say how to select it, or if it does, it's not clear.
There is also no action in the second one: "by setting the ...."
Would you mind explaining these further?

Also, should opam root be opam root?

christinerose · 2023-09-04T11:31:51Z

doc/pages/Manual.md

-  This is generally done through `sudo`, and always after prompting the user
-  (unless `--yes` was specified). if disabled, the installation command is
+  This is generally done through `sudo` and always after prompting the user
+  (unless `--yes` was specified). If disabled, the installation command is
  printed to stdout, and opam pauses to let the user proceed.


Suggested change

printed to stdout, and opam pauses to let the user proceed.

printed to `stdout`, and opam pauses to let the user proceed.

christinerose · 2023-09-04T11:35:41Z

doc/pages/Manual.md

    modified during the installation of the package.
-    Note that this hook is run after the scan for installed files is
-    done, so any additional installed files won't be recorded and must be taken
+    Note that this hook is run after the scan for installed files completes, so any additional installed files won't be recorded and must be taken
    care of by a `pre-remove-commands` hook. However, modified or deleted installed
    files during the `post-install-commands` will be handled correctly by `opam`.


Suggested change

files during the `post-install-commands` will be handled correctly by `opam`.

files during the `post-install-commands` will be handled correctly by opam.

No monospace until you're talking about the opam file specifically. It sounds like this is talking about the pkg mgr in general. Is that correct?

christinerose · 2023-09-04T11:39:09Z

doc/pages/Manual.md

  specify commands that will be run just after processing the package's commands
  for the corresponding action, and the `<pkgname>.install` file in the case of
-  install and remove, on any package. The post commands are run wether or not
+  install and remove, on any package. The post commands are run whether or not


Do these items "specify commands that will be run...for the corresponding action" and specify commands for the "<pkgname>.install file (in the case of install and remove)"

Does the "on any package" part refer to both of the above (corresponding action and install file) or just one or the other?

christinerose · 2023-09-04T11:40:42Z

doc/pages/Manual.md

+  for context. If set to a single `<ident>` element that may point to a
+  built-in solver or one of the `aspcud`, `packup`, or `mccs` predefined


This has an If... but no then -- the thought is incomplete. If it's set to single <ident> ... then what happens?

christinerose · 2023-09-04T12:02:15Z

doc/pages/Manual.md

 `build`.

 When the version formula reduces to `false`, as would be the case here when
 `build=false`, the dependency is removed from the formula.

 ### Interpolation

-Some files can be rewritten using variable interpolation expansion: in cases
+Some files can be rewritten using variable interpolation expansion. In cases
 where this is available, when looking for `file` and `file.in` is found, any


Is "when looking for file and file.in is found" an example of "where this is available"?
If so, let's write it like this; "In cases where this is available, i.e., when looking for ..."

...or does this mean "in cases where this is available and when looking for..., any interpolations found are replaced..."?

christinerose · 2023-09-04T12:04:20Z

doc/pages/Manual.md


    This field follows the exact same format as `build:`. It is used to move
    products of `build:` from the build directory to their final destination
-    under the current `prefix`, and do any required additional setup. Commands
-    in `install:` are executed sequentially, from the root of the source tree
+    under the current `prefix`; they do any required additional setup. Commands


Could we change "do any required..." to "perform any required..."?

christinerose · 2023-09-04T12:05:38Z

doc/pages/Manual.md

@@ -994,7 +991,7 @@ files.
  dependencies of the package toward packages external to the <span class="opam">opam</span>


Should this be "the package's external dependencies"?
Do the external dependencies belong to the package?

christinerose · 2023-09-04T12:07:28Z

doc/pages/Manual.md

      explicitely. This can be affected by the
      [solver criteria](#configfield-solver-criteria). This can be useful for
-      beta releases, or to discourage installation of releases with known bugs.
+      beta releases or to discourage installation of releases with known bugs.

      Note that this behaviour is disabled when a flagged version of the package
      is already installed.


Should the following lines be:

- <a id="opamflag-deprecated">`deprecated`</a>: this flag is equivalent to [`avoid-version`](#opamflag-avoid-version), except for the addition of a deprecation message after the package is installed. It should also be marked as deprecated in the solution shown to the user upon installation.

The way it reads now is a little confusing.

christinerose · 2023-09-04T12:11:52Z

doc/pages/Manual.md

@@ -614,22 +611,22 @@ For example, a dependency on `"foo" { = version }` will require package `foo` at
 the version defined by variable `version` (which is the version of the package


This sentence is quite confusing.

"For example, a dependency on "foo" { = version } will require package foo at
the version defined by variable version (which is the version of the package being defined)."

How can we clarify this further?
Maybe:

"For example, a dependency on "foo" { = version } will require package foo at
the version, which is defined by variable version (the package version being defined)."

What is meant by "at the version" --- is this in the command or in a directory? a file?

christinerose added 5 commits August 23, 2023 01:51

Capitalization

e181ee3

punctuation & grammar

79d0f9a

More capitalisation

da8850c

tightening syntax / rewording

6914296

Please ensure my changes are still accurate. I'll have more questions in the PR to establish clarity in several places as well.

Formatting, mostly monospace

4e1df7d

Clarification needed for 113-117

f6843c6

Do these suggestions this make it more clear?

christinerose commented Sep 4, 2023

View reviewed changes

fix oversight

a6247cd

rjbou added the PR: WAITING FOR REVIEW label Dec 12, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Line edits for Manual doc #5641

Line edits for Manual doc #5641

christinerose commented Aug 24, 2023

christinerose commented Aug 24, 2023

christinerose commented Aug 24, 2023

christinerose commented Sep 4, 2023

christinerose Aug 24, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

christinerose Sep 4, 2023

	printed to stdout, and opam pauses to let the user proceed.
	printed to `stdout`, and opam pauses to let the user proceed.

	files during the `post-install-commands` will be handled correctly by `opam`.
	files during the `post-install-commands` will be handled correctly by opam.

		for context. If set to a single `<ident>` element that may point to a
		built-in solver or one of the `aspcud`, `packup`, or `mccs` predefined

		@@ -994,7 +991,7 @@ files.
		dependencies of the package toward packages external to the <span class="opam">opam</span>

		@@ -614,22 +611,22 @@ For example, a dependency on `"foo" { = version }` will require package `foo` at
		the version defined by variable `version` (which is the version of the package

Line edits for Manual doc #5641

Are you sure you want to change the base?

Line edits for Manual doc #5641

Conversation

christinerose commented Aug 24, 2023

christinerose commented Aug 24, 2023

christinerose commented Aug 24, 2023

christinerose commented Sep 4, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment