Overhauling the README #301

bridadan · 2018-02-02T21:56:08Z

This is loooooong overdue! I had to put this up in a rush, so apologies for the typos. Just let me know and I'll fix them!

Could you please take a look @AnotherButler? Thanks!

coveralls · 2018-02-02T21:57:47Z

Coverage remained the same at 74.775% when pulling 7e04be6 on bridadan:update_readme into fcfc075 on ARMmbed:master.

coveralls · 2018-02-02T21:57:47Z

Coverage remained the same at 74.775% when pulling 6ecf874 on bridadan:update_readme into fcfc075 on ARMmbed:master.

Copy edit for active voice, consistent tense and person and spelling.

AnotherButler

@bridadan This looks great. I've left a few comments and queries for you to address that I was confused about.

AnotherButler · 2018-02-06T17:01:06Z

README.md

-```mbed-ls``` provides these points of information for all connected boards at once in a simple console (terminal) output.
+# mbed-ls
+
+`mbed-ls` is a Python (2 and 3) module that detects and lists Mbed Enabled devices connected to the host computer. It is delivered as a redistributable Python module (package) and command-line tool. It works on all major operating systems (Windows, Linux and Mac OS X).


Query: Who or what delivers this as a redistributable Python module (package) and command-line tool? Mbed OS? The Mbed team? Something else? Please clarify for active voice.

Could we change this to: Mbed LS is published by the Mbed OS team on PyPI

AnotherButler · 2018-02-06T17:01:59Z

README.md

-Now you are ready to install mbed-ls.
+### Result formats
+
+The command-line is able to list the results in a number of formats.


Query: Would it be accurate to say "list the results in many formats"? If so, please change. If not, please delete "a number of".

Yes. I would write this as: The Mbed LS command line accepts a few arguments to change the format of the results. The default format is a table. You may pass --simple to simplify this table format, and --json to print the table as a json list of the rows.

AnotherButler · 2018-02-06T17:02:40Z

README.md


-To test if your installation succeeded try the ```mbedls``` command:
+When developing new a platform, it is possible to override the default name `mbed-ls` assigns. This is done with the `--mock` parameter:


Query: Are you (the user) doing this with the --mock parameter, or is something else? Please clarify for active voice.

Yes, the user uses the --mock parameter. I would avoid the use of "default" here, as it adds no meaning.

AnotherButler · 2018-02-06T17:04:09Z

README.md


-* Note: This feature in implicitly ON.
-* Note: This feature can be turned off with command line switch ```--skip-retarget```.
+This controls whether a unique name is assigned to each platform. The unique name takes the form of `K64F[0]`, where the number between the brackets is an incrementing value. This name is accessible through the dictionary member `platform_unique_name` in the returned platform data. It defaults to `False`.


Query: Who or what assigns a unique name to each platform? You, the user? Or something else? Please clarify for active voice.

AnotherButler · 2018-02-06T17:04:37Z

README.md

-    }
-]
-```
+This controls whether more data is pulled from the file system on each device. It can provide useful management data but also takes more time to execute.


Query: Who or what pulls data from the file system on each device?

AnotherButler · 2018-02-06T17:06:00Z

README.md

-* Remove masking with '!' prefix: `$ mbedls --mock !MID`
-* Remove all maskings using !* notation: `$ mbedls --mock !*`
-* Combine above using comma (`,`) separator: `$ mbedls --mock MID1:PLATFORM_NAME1,!MID2`
+The name of the platform that is returned for any platform that has a `target_id` that matches the first four characters specified in `mid`.


Query: Could we rewrite this for clarity? Is it saying that mid specifies characters, and that any platform with a target_id that matches the first four characters that mid specifies returns its own name? Or it returns the name of a different platform?

AnotherButler · 2018-02-06T17:07:52Z

README.md

-$ cat $HOME/.mbed-ls/.mbedls-mock
-{}
-```
+All tests are contained within the `/test` directory. You can run the tests with the following command:


Note to self: Change first sentence to "The /test directory contains all tests." for active voice after responses to comments, so you don't lose comments.

bridadan · 2018-02-09T15:26:23Z

README.md

-        "target_id_usb_id": "0240022648cb1e77000000000000000000000000b512e3cf"
-    }
-}
+### `mock_manufacture_id(...)`


Note to self: Prefix this function call with mbeds. just like mbeds.list_mbeds().

theotherjimmy · 2018-02-09T15:10:16Z

README.md


-Clone the mbed-ls repository. The following example uses the GitHub command line tools, but you can do this directly from the website:
+To install the `mbed-ls` module, first clone the `mbed-ls` repository. The following example uses the GitHub command-line tools, but you can do this directly from the website:


"but" -> "and/or"/delete the whole clause.

Eww, not sure how this got left behind. This was from the old readme. I'll clean it up, thanks

theotherjimmy · 2018-02-09T15:10:57Z

README.md

 ```

-Change the directory to the mbed-ls repository directory:
+# Use


Remove this from the top level?

theotherjimmy · 2018-02-09T15:11:29Z

README.md

-$ cd mbed-ls
+## Command-line
+
+The command-line tool is available with the command `mbedls`:


Should we call out the lack of space so that people don't get confused with mbed ls?

theotherjimmy · 2018-02-09T15:14:12Z

README.md

-Now you are ready to install mbed-ls.
+### Result formats
+
+The command-line is able to list the results in a number of formats.


Yes. I would write this as: The Mbed LS command line accepts a few arguments to change the format of the results. The default format is a table. You may pass --simple to simplify this table format, and --json to print the table as a json list of the rows.

theotherjimmy · 2018-02-09T15:15:27Z

README.md


-To test if your installation succeeded try the ```mbedls``` command:
+When developing new a platform, it is possible to override the default name `mbed-ls` assigns. This is done with the `--mock` parameter:


Yes, the user uses the --mock parameter. I would avoid the use of "default" here, as it adds no meaning.

theotherjimmy · 2018-02-09T15:29:12Z

README.md


-Example TargetID coding:
-* Freescale `K64F` TargetID: `0240000033514e450019500585d40008e981000097969900`
+The Python API is available through the `mbed_lstools` module.


Could you move this sentence into the Python API heading?

theotherjimmy · 2018-02-09T15:30:03Z

README.md


-We can see the mounting result in the usb-id directories in Ubuntu's file system under ```/dev/```. To list mbed boards mounted to serial ports (CDC) via USB, we use the general Linux command:
+If set to `True`, this skips the retargetting step, and the results are unmodified.


Maybe mention the connection to --skip-retarget?

theotherjimmy · 2018-02-09T15:30:22Z

README.md

-lrwxrwxrwx root  13 Feb 19 12:35 usb-STMicroelectronics_STM32_STLink_066EFF525257775087141721-if02 -> ../../ttyACM2
-lrwxrwxrwx root  13 Feb 19 12:35 usb-STMicroelectronics_STM32_STLink_066EFF534951775087215736-if02 -> ../../ttyACM1
-```
+If set to `True`, this includes unmounted platforms in the results.


Mention the connection to -u?

theotherjimmy · 2018-02-09T15:31:41Z

README.md


-From this we know that the target platform has these properties:
+- `FSInteraction.NEVER` - This is the fastest option but also potentially the least accurate. It never touches the file system of the devices and uses only the information available through the OS. This is appropriate for use in a highly controlled environment (such as an automated Continuous Integration setup). **This has the potential to provide incorrect names and data. It may also lead to devices not being detected at all.**


Nit: the filesystem is available through the OS. Could you rewrite "OS" to "USB descriptors"?

theotherjimmy · 2018-02-09T15:32:23Z

README.md

-* The unique target platform identifier is ```066E```.
-* The serial port is ```ttyACM2```.
-* The mount point is ```sdd```.
+##### `filter_function`


Could you move this above fs_interaction?

bridadan · 2018-02-09T23:46:12Z

Ok, all edits implemented! It might be a good idea to do one more once over. I hadn't realized you had pushed to my fork @AnotherButler so I had to rebase my edits, so hopefully I didn't mess up your awesome work!

Copy edit file for active voice, consistent tense and minor grammar fixes.

AnotherButler

👍 Nice work on this

theotherjimmy · 2018-02-16T20:50:56Z

README.md

@@ -245,13 +245,13 @@ This argument controls the accuracy and speed of this function. There are three

 **Default:** `False`.

-Mbed LS will assign a unique name to each platform if this is set to `True`. The unique name takes the form of `K64F[0]`, where the number between the brackets is an incrementing value. This name is accessible through the dictionary member `platform_unique_name` in the returned platform data.
+Mbed LS assigns a unique name to each platform if this is set to `True`. The unique name takes the form of `K64F[0]`, where the number between the brackets is an incrementing value. This name is accessible through the dictionary member `platform_unique_name` in the returned platform data.


if -> when?

theotherjimmy · 2018-02-16T20:51:31Z

README.md


 #### `read_details_txt`

 **Default:** `False`

-Mbed LS will pull more data from the files ystem on each device if this is set to `True`. It can provide useful management data, but also takes more time to execute.
+Mbed LS pulls more data from the file system on each device if this is set to `True`. It can provide useful management data but also takes more time to execute.


pulls -> reads.

bridadan · 2018-02-16T21:02:21Z

Thanks for the changes @AnotherButler and the review @theotherjimmy. I pushed up some changes.

AnotherButler · 2018-02-16T21:35:57Z

Looks good @bridadan

Overhauling the README

7e04be6

bridadan force-pushed the update_readme branch from 06fcede to 7e04be6 Compare February 2, 2018 21:57

Copy edit README.md

c5358c9

Copy edit for active voice, consistent tense and person and spelling.

AnotherButler reviewed Feb 6, 2018

View reviewed changes

bridadan commented Feb 9, 2018

View reviewed changes

theotherjimmy reviewed Feb 9, 2018

View reviewed changes

bridadan added 3 commits February 9, 2018 17:36

Edits to README after review

6aad4ca

Removing last instances of 'mbed-ls' name in README

28ba02d

Removing unneccessary horizontal rules

c2cab9e

theotherjimmy approved these changes Feb 13, 2018

View reviewed changes

Copy edit README.md

5f4059b

Copy edit file for active voice, consistent tense and minor grammar fixes.

AnotherButler approved these changes Feb 16, 2018

View reviewed changes

theotherjimmy reviewed Feb 16, 2018

View reviewed changes

Tense change and moving 'if's to 'when's

6ecf874

theotherjimmy approved these changes Feb 16, 2018

View reviewed changes

AnotherButler approved these changes Feb 16, 2018

View reviewed changes

theotherjimmy merged commit 08f2bcb into ARMmbed:master Feb 20, 2018

AnotherButler deleted the update_readme branch March 1, 2018 01:55

theotherjimmy mentioned this pull request Mar 1, 2018

Readme section Extended mbedls API example section outdated #275

Closed


		To test if your installation succeeded try the ```mbedls``` command:
		When developing new a platform, it is possible to override the default name `mbed-ls` assigns. This is done with the `--mock` parameter:


		Clone the mbed-ls repository. The following example uses the GitHub command line tools, but you can do this directly from the website:
		To install the `mbed-ls` module, first clone the `mbed-ls` repository. The following example uses the GitHub command-line tools, but you can do this directly from the website:


		We can see the mounting result in the usb-id directories in Ubuntu's file system under ```/dev/```. To list mbed boards mounted to serial ports (CDC) via USB, we use the general Linux command:
		If set to `True`, this skips the retargetting step, and the results are unmodified.


		From this we know that the target platform has these properties:
		- `FSInteraction.NEVER` - This is the fastest option but also potentially the least accurate. It never touches the file system of the devices and uses only the information available through the OS. This is appropriate for use in a highly controlled environment (such as an automated Continuous Integration setup). This has the potential to provide incorrect names and data. It may also lead to devices not being detected at all.

Overhauling the README #301

Overhauling the README #301

Uh oh!

Conversation

bridadan commented Feb 2, 2018

Uh oh!

coveralls commented Feb 2, 2018

Uh oh!

coveralls commented Feb 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bridadan commented Feb 9, 2018

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bridadan commented Feb 16, 2018

Uh oh!

AnotherButler commented Feb 16, 2018

Uh oh!

Uh oh!

coveralls commented Feb 2, 2018 •

edited

Loading