Copyediting

src/sw_sup/afws_client.md

@@ -6,22 +6,22 @@ This article is intended to help with using the `afws_client` command properly.
 
 ### What is AFWS
 
-AFWS (ARTIQ FirmWare Service) - a service, that allows building customer tailored firmware and gateware (binaries) on M-Labs's servers, 
+AFWS (ARTIQ FirmWare Service): a service which allows building customer-tailored firmware and gateware (binaries) on M-Labs's servers
 and receive these binaries in ready-to-flash format. Subscription to this service also includes helpdesk support,
-and thus is paid on yearly basis (contact sales for prices). It is also typically included when purchasing Carrier (Kasli/Kasli-SoC) for a year, 
+and thus is paid on a yearly basis (contact sales for prices). It is also typically included when purchasing Carrier (Kasli/Kasli-SoC) for a year,
 or one-time when purchasing standalone cards for existing crate. Each variant/carrier requires its own subscription.
 
 ### What do I need for obtaining binaries
 
-You'll need to have credentials - username and password, which you can obtain from helpdesk, if you haven't yet. 
+You'll need to have credentials - username and password, which you can obtain from helpdesk, if you haven't yet.
 Don't forget to specify variant (sticker on top of the crate) that you need to obtain binaries for.
 
 ### When do I need to update
 
 In most cases there is no need to update the firmware, unless you encountered a bug and the fix was backported to your version.
-However, if you: changed the layout of the cards - either moved EEM connections, added or deleted cards; 
+However, if you changed the layout of the cards (either moved EEM connections, added or removed cards) or
-changed modes/configurations of the cards (e.g. enable/disable SUServo, synchronization, edge counter, SED lanes etc.).
+changed modes/configurations of the cards (e.g. enable/disable SUServo, synchronization, edge counter, SED lanes etc.), you also
-In such cases, these changes need to be authorized through helpdesk.
+need to update the firmware. In such cases, the changes need to be authorized through helpdesk.
 
 ### How to
 
@@ -32,21 +32,21 @@ afws_client <username> build <afws_directory> <variant>
 
 Where (remove `<` and `>`):
 * `<username>` - your username from credentials
-* `<afws_directory>` - the directory/folder, into which you wish to save the binaries
+* `<afws_directory>` - the directory/folder into which you wish to save the binaries
-* `<variant>` - name of the crate/variant. It's optional if you have only one variant in the account
+* `<variant>` - name of the crate/variant, optional if you have only one variant for the account
 
 After running this command, it will ask you for the password (the line will remain blank for security reasons).
-If everything matches (username and password are correct, specified variant is in your account and not expired), 
+If everything matches (username and password are correct, specified variant is in your account and not expired),
-AFWS will start building the firmware, which takes 10-15 minutes. Sometimes there might be some problems, in which 
+AFWS will start building the firmware, which takes 10-15 minutes. Sometimes there might be some problems, in which
 case don't hesitate to contact helpdesk.
 
-After the build done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which 
+After the build is done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which
 you can flash them into your Carrier.
 
 #### View build logs
 
-You may want to view the build logs (for example, in case of problems with configuration). 
+You may want to view the build logs (for example, in case of problems with configuration).
-For this, add `--log` option after build:
+For this, add the `--log` option after `build`:
 
 ```shell
 afws_client <username> build --log <afws_directory> <variant>
@@ -54,9 +54,9 @@ afws_client <username> build --log <afws_directory> <variant>
 
 #### Specify version
 
-By default, AFWS client tries to figure out the installed ARTIQ version. However it works only for Kasli, and not Kasli-SoC.
+By default, the AFWS client tries to figure out the installed ARTIQ version. However, it works only for Kasli, and not Kasli-SoC.
-It also may fail to determine ARTIQ version if you are using AFWS client without ARTIQ installation.
+It may also  fail to determine ARTIQ version if you are using the AFWS client without an ARTIQ installation.
-Additionally, you may want to specify version regardless of installed version.
+Additionally, you may want to specify a version different to the installed version.
 In all these cases, you'll need to specify **both** `--major-ver` and `--rev` arguments, so your command will look like this:
 
 ```shell
@@ -64,18 +64,18 @@ afws_client <username> build --major-ver <MAJOR_VER> --rev <REV> <afws_directory
 ```
 
 Where:
-* `MAJOR_VER` - ARTIQ major version,  either `7` (legacy), `8` (current stable), 
+* `MAJOR_VER` - ARTIQ major version,  either `7` (legacy), `8` (current stable),
   `9` (current beta) or `10` (experimental with `nac3` compiler)
 * `REV` - revision from respective branch and repository - i.e. commit hash. You may obtain it either from:
-  * [ARTIQ repository](https://github.com/m-labs/artiq) (for Kasli 2.0 and earlier) by 
+  * [ARTIQ repository](https://github.com/m-labs/artiq) (for Kasli 2.0 and earlier) by
     [selecting branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository)
-    and selecting `XXX commits` above list of files. From here, the list of commits in specified branch will appear 
+    and selecting `XXX commits` above the list of files. From here, the list of commits in the specified branch will appear
-    and you will be able to choose the commit and press ["Copy full SHA for YYY"](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits#using-the-file-tree) 
+    and you will be able to choose the commit and press ["Copy full SHA for YYY"](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits#using-the-file-tree)
     button in the right side.
-  * [ARTIQ on Zynq repository](https://git.m-labs.hk/M-Labs/artiq-zynq) (for Kasli-SoC). In similar way to GitHub, 
+  * [ARTIQ on Zynq repository](https://git.m-labs.hk/M-Labs/artiq-zynq) (for Kasli-SoC). In a similar way to GitHub,
-    you can choose branch, commit history and copy SHA1 of the commit.
+    you can choose branch, commit history and copy SHA1 of the commit on Gitea.
 
-The branches currently map as following:
+The branches currently map as follows:
 * ARTIQ-7 - release-7
 * ARTIQ-8 - release-8
 * ARTIQ-9 - master
@@ -87,21 +87,21 @@ cache (i.e. not rebuilt).
 
 #### Change password
 
-After you received credentials from us, we strongly recommend changing the password as soon as possible via 
+After you receive credentials from us, we strongly recommend changing the password as soon as possible via
-`afws_client <username> passwd` command. This command will ask you for existing password and new desired password.
+`afws_client <username> passwd` command. This command will ask you for the existing password and new desired password.
 
-The passwords are stored in a hashed way (i.e. cannot be decrypted back), however it's your responsibility to choose good passwords.
+The passwords are stored in a hashed way (i.e. cannot be decrypted back); however, it's your responsibility to choose good passwords.
-Just keep in mind, that password may contain only alpha-numeric symbols and underscore `[a-zA-Z0-9_]`.
+Just keep in mind that the password can contain only alphanumeric symbols and underscores: `[a-zA-Z0-9_]`.
-If you cannot login, we may reset your password if you email us at helpdesk.
+If you cannot log in, we can reset your password if you email us at helpdesk.
 
 #### Get variants
 
-You may get variants, which are tied to your account by using `get_variants` command:
+You may get a list of the variants tied to your account by using `get_variants` command:
 ```shell
 afws_client <username> get_variants
 ```
 
-It will ask for password and output the variants and their respective expiry date:
+It will ask for a password and output the variants and their respective expiry date:
 
 ```text
 +-----------+-------------+
@@ -114,15 +114,15 @@ It will ask for password and output the variants and their respective expiry dat
 
 #### Get JSONs
 
-Sometimes you may want to view the JSON description, from which AFWS is building the variant. With the JSON, you can
+Sometimes you may want to view the JSON description from which AFWS is building the variant. With the JSON, you can
-later build the firmware by yourself and/or generate device_db file. The command looks like this (variant 
+later build the firmware by yourself and/or generate a `device_db` file. The command looks like this (variant
 needs to be valid, i.e. not expired and authorized in your account):
 
 ```shell
 afws_client <username> get_json [-o <OUT>] [-f] <variant>
 ```
 
-Specify output file `-o <OUT>`, if you want to save it directly to file `<OUT>`, use `-f` if you want to force 
+Specify output file `-o <OUT>`, if you want to save it directly to file `<OUT>`; use `-f` if you want to force
 overwrite. If you do not specify any of these options, you'll get the JSON description directly in stdin (i.e. in your
 console/terminal).