manual: Copyedit

docs/forge.org

@@ -51,7 +51,7 @@ and additional hosts can easily be supported by adding entries to the
 option ~forge-alist~ (see [[*Repository Detection]]).
 
 For more details about the caveats mentioned below (and some others)
-also see [[*Getting Started]].
+see also [[*Getting Started]].
 
 ** Supported Forges
 *** Github
@@ -60,7 +60,7 @@ also see [[*Getting Started]].
 :END:
 
 Forge's support for Github can be considered the "reference
-  implementation".  Support for other forges can lag behind a bit.
+implementation".  Support for other forges can lag behind a bit.
 
 **** Github Caveats
 
@@ -254,9 +254,9 @@ documented in [[info:ghub#Getting Started]].
 
 Ghub used to provide a setup wizard, but that had to be removed for
 reasons given in the manual just mentioned.  Nowadays there is no way
-around reading the documentation and doing this manually I am afraid.
+around reading the documentation and doing this manually, I am afraid.
 
-  Forge requires the following token scopes.
+Forge requires the following token scopes.
 
 - For Github these scopes are required.
 
@@ -275,42 +275,43 @@ around reading the documentation and doing this manually I am afraid.
 
 ** Initial Pull
 
-To start using Forge in a certain repository visit the Magit status
-buffer for that repository and type ~f n~ (~forge-pull~).  Alternatively,
-you can use ~M-x forge-add-repository~, which makes it possible to add a
-forge repository without pulling all topics and even without having to
-clone the respective Git repository.
-
 You must set up a token *before* you can add the first repository.
 See [[*Token Creation]].
 
-The first time ~forge-pull~ is run in a repository, an entry for that
-repository is added to the database and a new value is added to the
-Git variable ~remote.<remote>.fetch~, which fetches all pull-requests.
-(~+refs/pull/*/head:refs/pullreqs/*~ for Github)
+After that, to start using Forge in a certain repository visit the
+Magit status buffer for that repository and type ~N / a~
+(~forge-add-repository~).  You are given a choice to pull all topics,
+all topics that were updated after a certain date, or only individual
+topics.
+
+Beside adding the repository to the database, this also adds a new
+value to the Git variable ~remote.<remote>.fetch~, which causes all
+pull-request refs (~+refs/pull/*/head:refs/pullreqs/*~ for Github)
+to be fetched by Git.
 
-~forge-pull~ then fetches topics and other information using the forge's
-API and pull-request references using Git.
+Note that it is possible to add a repository to the database, without
+cloning the Git repository first.  The entry point is the same as
+described above.
 
 The initial fetch can take a while but most of that is done
 asynchronously.  Storing the information in the database is done
 synchronously though, so there can be a noticeable hang at the end.
 Subsequent fetches are much faster.
 
 Fetching issues from Github is much faster than fetching from other
-forges because making a handful of GraphQL requests is much faster
+forges, because making a handful of GraphQL requests, is much faster
 than making hundreds of REST requests.
 
 ** Repository Detection
 
 Ghub does *not* associate a given local repository with a repository on
 a forge.  The Forge package itself takes care of this.  In doing so it
 ignores the Git variable ~ghub.host~ and other ~*.host~ variables used by
-Ghub.  (But ~github.user~ and other variables used to specify the user
+Ghub.  (But ~github.user~, and other variables used to specify the user,
 are honored).
 
-Forge associates the local repository with a forge repository by first
-determining which remote is associated with the upstream repository
+Forge associates the local repository with a forge repository, by first
+determining which remote is associated with the upstream repository,
 and then looking that up in ~forge-alist~.
 
 If only one remote exists, then Forge uses that unconditionally.  To
@@ -330,8 +331,8 @@ Note, however, that even though a surprising number of people do just
 that, it does not make any sense to use the name "origin" to refer to
 a fork; not even to your own fork.  A fork is a *copy* of the original,
 "copy" is an antonym for "original", and the word "origin" is not only
-closely related to but even contained in the word "original".  Naming
-a fork the "origin" is at best extremely confusing.
+closely related to but is even contained in the word "original".
+Naming a fork the "origin" is at best extremely confusing.
 
 - copy :: a thing made to be similar or identical to another.
 
@@ -381,13 +382,14 @@ which case "upstream" must be preferred).
   This command changes the value of the ~forge.remote~ Git variable in
   the current repository.
 
+TODO is this still accurate?
 If this variable is set, then Forge uses the remote by that name, if
-it exists, the same way it may have used ~origin~ if the the variable
-were undefined.  I.e., it does not fall through to try ~origin~ if no
-remote by your chosen name exists.
+it exists, the same way it may have used ~origin~ if the variable were
+undefined.  I.e., it does not fall through to try ~origin~ if no remote
+by your chosen name exists.
 
 Once the upstream remote has been determined, Forge looks it up in
-~forge-alist~, using the host part of the URL as the key.  For example
+~forge-alist~, using the host part of the URL as the key.  For example,
 the key for [email protected]:magit/forge.git~ is ~github.com~.
 
 - User Option: forge-alist ::
@@ -423,16 +425,16 @@ the key for [email protected]:magit/forge.git~ is ~github.com~.
 ** Caveats
 
 - Fetched information is stored in a database.  The table schemata of
-  that database have not been finalized yet.  Until that has happened
-  it will occasionally have to be discarded.  That isn't such a huge
-  deal because for now the database does not contain any information
-  that cannot simply be fetched again, see [[*Initial Pull]].
+  that database have not been finalized yet.  So far it was possible
+  to automatically update existing databases to new schemata, but
+  there soon will come a day, when I have to make more drastic changes
+  to address the accumulated deficiencies.
 
 - Fetching is implemented under the assumption that the API can be
   asked to list the things that have changed since we last checked.
   Unfortunately the APIs are not bug-free, so this is not always the
-  case.  If in doubt, then re-fetch an individual topic to ensure it
-  is up-to-date using the command ~forge-pull-topic~.
+  case.  If in doubt, you can re-fetch an individual topic to ensure
+  it is up-to-date, using the command ~forge-pull-topic~.
 
 - Some other, forge-specific, caveats are mentioned in [[*Supported
   Forges and Hosts]].
@@ -445,11 +447,11 @@ and "Issues" to Magit's status buffer.  It is also possible to add a
 repository to the local database without pulling all the data, which
 is useful if you want to create a single pull-request.
 
-- Key: N a (forge-add-repository) ::
+- Key: N / a (forge-add-repository) ::
 
   This command adds a repository to the database.
 
-  It offers to either pull topics (now and in the future) or to only
+  It offers to either pull topics (now and in the future) or to only UPDATE
   pull individual topics when the user invokes ~forge-pull-topic~.
 
 Some of Forge's commands are only bound when point is within one of
@@ -469,58 +471,56 @@ Magit's status buffer and/or from Magit's transient commands.
 
 ** Pulling
 
-The commands that fetch forge data are available from the same
-transient prefix command (~magit-fetch~ on ~f~) that is used to fetch Git
-data.  If option ~magit-pull-or-fetch~ is non-nil, then they are also
-available from the ~magit-pull~ transient (on ~F~).
+The commands that fetch forge data, are available from the same
+transient prefix command (~magit-fetch~ on ~f~), which is used to fetch
+Git data.  If option ~magit-pull-or-fetch~ is non-nil, then they are
+also available from the ~magit-pull~ transient (on ~F~).
 
 - Key: f n (forge-pull) ::
 - Key: N f f ::
 
   This command uses a forge's API to fetch topics and other
-  information about the current repository and stores the fetched
-  information in the database.  It also fetches notifications for all
-  repositories from the same forge host.  (Currently this is limited
-  to Github.)  Finally it fetches pull-request references using Git.
+  information about the current repository, and stores the fetched
+  information in the local database.  It also fetches notifications
+  for all repositories from the same forge host.  (Currently this is
+  limited to Github.)  Finally, it fetches pull-request references
+  using Git.
 
-  After using this command for the first time in a given repository
-  the status buffer for that repository always lists the pull-requests
-  and issues.  See [[*Initial Pull]].
+  After using this command for the first time in a given repository,
+  the status buffer for that repository lists its open and/or pending
+  pull-requests and issues.  See [[*Initial Pull]].
 
 - Key: f N (forge-pull-notifications) ::
 - Key: N f n ::
 
   This command uses a forge's API to fetch all notifications from that
-  forge including, but not limited to, the notifications for the current
-  repository.
+  forge, including, but not limited to, the notifications for the
+  current repository.
 
   Fetching all notifications fetches associated topics even if you
   have not started fetching *all* topics for the respective repositories
   (using ~forge-pull~), but it does not cause the topics to be listed in
   the status buffer of such "uninitialized" repositories.
 
 Note how pulling data from a forge's API works the same way as pulling
-Git data does; you do it explicitly when you want to see the work done
+Git data does; you do it explicitly, when you want to see the work done
 by others.
 
-This is less disruptive, more reliable, and easier to understand than
+This is less disruptive, more reliable, and easier to understand, than
 if Forge did the pulling by itself at random intervals.  It might
-however mean that you occasionally invoke a command expecting the most
-recent data to be available and then have to abort to pull first.
-The same can happen with Git, e.g., you might attempt to merge a branch
-that you know exists but haven't actually pulled yet.
+however mean, that you occasionally invoke a command, expecting the
+most recent data to be available, and then have to abort and pull
+first.  The same can happen with Git, e.g., you might attempt to merge
+a branch, that you know exists, but haven't actually pulled yet.
 
 - Key: N f t (forge-pull-topic) ::
 
-  This command uses a forge's API to fetch a single pull-request and
-  stores it in the database.
-
-  Normally you wouldn't want to pull a single pull-request by itself,
-  but due to a bug in the Github API you might sometimes have to do
-  so.
+  This command uses a forge's API to fetch a single topic and stores
+  it in the database.
 
-  Fetching is implemented under the assumption that the API can be
-  asked to list the things that have changed since we last checked.
+  TODO since with identical above
+  Fetching is implemented under the assumption, that the API can be
+  asked to list the things that have changed, since we last checked.
   Unfortunately the APIs are not bug-free, so this is not always the
   case.  If in doubt, then re-fetch an individual topic to ensure it
   is up-to-date using the command ~forge-pull-topic~.
@@ -529,7 +529,7 @@ that you know exists but haven't actually pulled yet.
 
 Forge provides commands for creating and checking out a new branch or
 work tree from a pull-request.  These commands are available from the
-same transient prefix commands as the suffix commands used to create
+same transient prefix commands as the suffix commands, used to create
 and check out branches and work trees in a more generic fashion
 (~magit-branch~ on ~b~ and ~magit-worktree~ on ~%~).
 
@@ -627,11 +627,11 @@ and check out branches and work trees in a more generic fashion
 
   This command creates and configures a new branch from a pull-request
   the same way ~forge-branch-pullreq~ does.  Additionally it checks out
-  the new branch using a new working tree.
+  the new branch, using a new working tree.
 
 - User Option: forge-checkout-worktree-read-directory-function ::
 
-  This function is used by ~forge-checkout-worktree~ to read the new
+  This function is used by ~forge-checkout-worktree~, to read the new
   worktree directory where it checks out the pull-request.  It takes
   the pull-request as the only argument and must return a directory.
 
@@ -645,6 +645,7 @@ Note that you have to delete the local branch (e.g., "feature") for
 this to work.  If you delete the tracking branch (e.g., "fork/feature"),
 then the remote is never removed.
 
+TODO continue here
 ** Working with Topics
 
 We call both issues and pull-requests "topics".  The contributions to
@@ -961,7 +962,7 @@ The following commands are available in buffers used to edit posts:
 :APPENDIX:   t
 :END:
 
-This section lists some frequently asked questions.  Please also see
+This section lists some frequently asked questions.  Please see also
 https://github.com/magit/forge/wiki/FAQ for an extended list of common
 issues.