Merge pull request #19 from McBen/docs_rephrase

Docs rewrite

Author: McBen

docs/1-creating-the-plugin.md

@@ -1,34 +1,36 @@
 # 1. Creating the Plugin
 
-Create a directory for your project, something like `countPortals`, and move into it.
+Start by creating a new project directory (for example, `countPortals`) and navigate into it.
 
 ## Install the Plugin Kit
 
-open a terminal window and run:
+Open a terminal and run:
 
 ```yarn add iitcpluginkit```
 
-This will install all required software (inside a `node_modules` directory) and might take a little bit. 
-You can ignore the warnings about deprecated dependencies.
-If you got an error it's most likely about an incompatible node version.
+This installs all required dependencies into a `node_modules` directory and may take a few moments. Deprecated dependency warnings can be safely ignored. If you encounter errors, check that your Node.js version is compatible.
 
 ## Create the initial layout
 
-- let IITCPluginKit create a default plugin layout for you:  
-`yarn ipk`
+Generate a default plugin structure:
 
-- Enter `CountPortals` (case-sensitive!) for the plugin name and leave the rest default.
+```
+yarn ipk
+```
+
+When prompted, enter `CountPortals` (case-sensitive) as the plugin name and use the default settings for all other options.
 
 ## Add some code
 
-- Open `/src/Main.ts` and replace the  _**// FILL ME**_ with `alert("Hello World");`
+1. Open `/src/Main.ts` and replace the `// FILL ME` comment with `alert("Hello World");`
 
-- save and run:  
-`yarn autobuild`
+2. Save the file and run:
 
-This will start building your code everytime you save your changes. Additionally, it provides a small fileserver to ease installation.
-Wait a little moment until you see the compilation is finished.  
-Something like:
+```
+yarn autobuild
+```
+
+This command automatically rebuilds your code whenever you make changes and provides a local file server for easy installation. Wait for the build to complete—you'll see output like this:
 
 ```shell
 [0] Built at: 2020-07-11 22:35:01
@@ -38,21 +40,25 @@ Something like:
 
 ## Installation
 
-- Open [http://localhost:8100](http://localhost:8100) and install your freshly created Plugin.
+1. Navigate to [http://localhost:8100](http://localhost:8100) in your browser to install your new plugin.
 
 ![Browser window](/images/tut-1.png)
 
-- Open or reload your iitc browser window.
-
-You should see the good old "Hello World" message.
+2. Open or refresh your IITC window.
 
-Congratulation for your first IITC-Plugin! :tada:
+You should now see the "Hello World" alert message. Congratulations on creating your first IITC plugin! 🎉
 
 ## Updating
-You won't need that now but sooner or later you'll need to update the IITCPluginKit.  
-`yarn outdated` will show you if you're still up to date  
-`yarn upgrade` will do all minor version upgrades  
 
-Sometimes the upgrade may break your code (like renamed function,...).  
-Run `yarn add iitcpluginkit` to do the bigger step and see if your code still compiles well.
-Maybe you should look at the [changelog](https://github.com/McBen/IITCPluginKit/blob/master/changelog.txt)
+Eventually, someday, you may need to update IITCPluginKit:
+
+- `yarn outdated` — Check for available updates
+- `yarn upgrade` — Apply minor version updates
+
+Major updates may require code changes. For these, run:
+
+```
+yarn add iitcpluginkit
+```
+
+Then verify your code compiles. Check the [changelog](https://github.com/McBen/IITCPluginKit/blob/master/changelog.txt) for details on breaking changes.

docs/2-starting-buttons.md

@@ -4,7 +4,8 @@ Expect the unexpected: the function `init()` is called on startup.
 So put there all the stuff you want to run on start.
 
 ## Toolbutton
-Having the alert text popping up on every start is really annoying. Let's hide it behind a toolbox button - a link below the portal-detail view. Where most plugins will add a link:
+
+Showing the alert on every startup is annoying. Instead, let's hide it behind a toolbox button—a link below the portal detail view:
 
 :::code-group
 ```typescript {7-12,15-17} [src/Main.ts]
@@ -29,19 +30,19 @@ class CountPortals implements Plugin.Class {
 ```
 :::
 
-The `$` is JQuery. JQuery is a good old google framework helping us doing html stuff. Modern developers will tell you not to use it. And yes, they are right and wrong. Anyway, it's already included in IITC so let's make use of it to ease HTML creations. 
+The `$` symbol represents jQuery, a popular library for HTML manipulation. While modern developers often prefer alternatives, jQuery is already included in IITC, so we use it here to simplify HTML creation.
 
-Here we create an `<a>` tag and add a "click" handler. This will call our new function which will hold our old `alert`.
+This code creates an `<a>` tag with a click handler that calls our new `doCount()` function.
 
 ![Hello world!](/images/tut-2.png)
 
 ## Toolbar Button
-Some people prefer a quick access button on the left side of the map. Please think twice before adding it. Only use it for stuff that a user will use daily.
-But hey, this is a tutorial: let's do it
 
-- First we need an icon. Download and place it in your /src/ directory -> ...
-Here we use SVG because it's simple and small, but you're free to use any web-format you like.
-- Import it at the top of your Main.ts:
+Some users prefer a quick access button on the left side of the map. Use this sparingly—only for features that users will access daily. For this tutorial, let's add one:
+
+1. First, create an icon. Download an icon and place it in your `/src/` directory. We'll use SVG for simplicity and small file size, but any web format works.
+
+2. Import it at the top of `Main.ts`:
 
 ```typescript {3}
 import * as Plugin from "iitcpluginkit";
@@ -53,7 +54,7 @@ class CountPortals implements Plugin.Class {
 }
 ```
 
-- Then create the toolbar button.
+3. Then create the toolbar button:
 
 ```typescript {14-24}
 class CountPortals implements Plugin.Class {
@@ -84,14 +85,13 @@ class CountPortals implements Plugin.Class {
 }
 ```
 
-We created a `<div>` for a new toolbar group and a `<a>` for a button with the image. 
-Finally attached them to the global map container.
+This code creates a toolbar group `<div>` and a button `<a>` with your icon, then attaches them to the map container.
 
-Make sure your "autobuild" command is still running. Open _**localhost:8100**_, update your script and reload iitc.
-As you see you'll need these often. It's a good thing to keep localhost and iitc open in different tabs.
+Ensure your "autobuild" command is still running. Navigate to [http://localhost:8100](http://localhost:8100), update your script, and reload IITC. It's helpful to keep localhost and IITC open in separate tabs.
 
 ## CSS
-Let's keep our code clean and move the styles into another file. We already have one which is still empty: `styles.css`
+
+Let's keep our code clean by moving styles into the CSS file. You already have `styles.css`—let's use it:
 
 :::code-group
 ```css [styles.css]
@@ -114,8 +114,7 @@ const toolbarGroup = $("<div>", { class: "leaflet-bar leaflet-control" })
 ```
 :::
 
-You will see an error message in your terminal window because the icon import is no longer required in `Main.ts`.
-So remove this import line.
+You'll see an error message in your terminal because the icon import is no longer needed in `Main.ts`. Remove this import line:
 
 :::code-group
 ```typescript [Main.ts]
@@ -131,7 +130,7 @@ class CountPortals implements Plugin.Class {
 
 ## Refactoring
 
-Last but not least let's do a little cleanup and move our stuff to an extra function to keep the `init()` function easy to read:
+Let's clean up the code and move button creation to a separate function to keep `init()` easy to read:
 
 :::code-group
 ```typescript {7,10-28} [Main.ts]
@@ -167,5 +166,4 @@ class CountPortals implements Plugin.Class {
 ```
 :::
 
-The `private` will let the compiler know no one else will use this function. You can mark most of your functions private.
-It won't help in final javascript but will help you track down obsolete functions. 
+The `private` keyword tells the compiler that this function is only used internally. Mark most of your functions as `private`—it won't affect the final JavaScript but helps identify unused code. 

docs/3-the-calculation.md

@@ -1,7 +1,6 @@
 # 3. The Calculation
 
-Let's fill the plugin with the real magic.
-I prefer to solve things top-down. So we start with the expected result:
+Let's implement the core functionality. We'll work top-down, starting with the expected result:
 ```typescript
 doCount(): void {
 
@@ -14,10 +13,9 @@ doCount(): void {
     alert(`Portals in Hack range: ${portals.length}`)
 }
 ```
-We check if the drawtool-plugin is installed. Then we need something that will give us a list of portals.
-And last-but-not-least print the result to the user.
+We check if the DrawTools plugin is installed, then retrieve a list of hackable portals, and finally display the result to the user.
 
-One step deeper: Loop through all portals and check if they are in range:
+One level deeper, we loop through all portals and check if they're within range:
 ```typescript
 private findHackablePortals(): IITC.Portal[] {
 
@@ -38,12 +36,10 @@ private findHackablePortals(): IITC.Portal[] {
 }
 ```
 
-window.portals is the object IITC stores all portals. IITC.Portal is a helper type defintion IITCPluginKit provides you.
-Maybe you want to take a look at all type definitions resikit included? see: ./node_modules/iitcpluginkit/src/types/iitc
-It's still incomplete but should cover most function and types you need for a plugin.
-".distanceTo" is a Leaflet function and will calculate the distance between points in meters.
+`window.portals` is where IITC stores all portal data. `IITC.Portal` is a type definition provided by IITCPluginKit. If you like you can explore all available type definitions in `./node_modules/iitcpluginkit/src/types/iitc` or most IDEs will give you a tooltip hint. 
+The `.distanceTo()` method is a Leaflet function that calculates the distance between points in meters.
 
-Another step deeper: Loop through all drawed polylines.
+Going deeper, we loop through all drawn polylines:
 
 ```typescript
 private findNearestPoint(pos: L.LatLng): L.LatLng | undefined {
@@ -73,12 +69,11 @@ private findNearestPoint(pos: L.LatLng): L.LatLng | undefined {
 }
 ```
 
-"drawnItems" is the layer DrawTools puts all it's stuff. The `<L.LayerGroup<any>>` tells Typescript what type it is.
-It's not only removing a warning. It's also helps with code completion.
-Long story short: We loop through all drawn items. Pick every item which is a GeodesicPolyline. Get all positions of the line.
-Then loop through the positions to find the nearest point on the line to the portal position
+`drawnItems` is the layer where DrawTools stores all its content. The `<L.LayerGroup<any>>` syntax tells TypeScript the variable's type, which helps with code completion and eliminates warnings.
 
-And finally some math stuff:
+In summary: we iterate through all drawn items, find those that are GeodesicPolylines, get their positions, and find the nearest point on each line to our portal position.
+
+Finally, some mathematical utilities:
 
 ```typescript
 private closedPoint(a: L.LatLng, b: L.LatLng, x: L.LatLng): L.LatLng {
@@ -103,12 +98,11 @@ private distance2(a: L.LatLng, b: L.LatLng): number {
 }
 ```
 
-To make things easy we assume that these geolines are straight lines. This is not correct and may lead to some error for long polylines.
-But it saves a bunch of calculation stuff and most people won't hardly ever recognize it.
-"closedPoint" calculates the point on the line a to b which is closest to x. 
-"distance2" returns the squared 2d-distance between two points.
+For simplicity, we treat these (Geodesic) Curved lines as straight lines. This isn't technically correct and may introduce small errors for very long polylines, but it saves computation and is imperceptible to most users.
+
+`closedPoint()` calculates the closest point on line segment a-b to point x. `distance2()` returns the squared 2D distance between two points.
 
-One last thing: lets replace the constant "40" in findHackablePortals with a more descripting word.
+Finally, let's replace the hard-coded value `40` in `findHackablePortals()` with a named constant:
 
 ```typescript
 if (closestPoint && position.distanceTo(closestPoint) <= HACK_RANGE) 

docs/4-the-dialog.md

@@ -1,6 +1,6 @@
 # 4. The Dialog
 
-A simple `alert` dialog is fine for a quick message. If we want to provide better user experience we should use a better approach: a real dialog
+A simple `alert()` dialog works for quick messages, but a proper dialog provides a better user experience:
 
 ```typescript {10-29}
 doCount(): void {
@@ -35,18 +35,19 @@ doCount(): void {
 }
 ```
 
-We created a table with more details of the found portals.
+We've created a table displaying detailed information about the found portals.
 
-### Portal-Data - side story
-Many plugins use portal data, and so we should take a deeper look.
+### Portal Data—A Closer Look
 
-All portals are stored in the window.portals object with the GUID as key. It includes all visible portals plus some outside of your view.
+Since many plugins work with portal data, it's worth understanding the structure in detail.
 
-These portal uses the IITC.Portals format. In fact these are Leaflet markers with more data stored in `options`. And to increase confusions this has another sub-structure `data` which hold more detail information about the portal. 
+All portals are stored in the `window.portals` object, keyed by GUID. This includes visible portals plus some outside your current view.
 
-There is even another data-structure `ent` but this one we shouldn't touch. IITC has already processed this raw-data.
+These portals use the `IITC.Portal` format, which are Leaflet markers with additional data stored in `options`. There's also a nested `data` structure containing more detailed information.
 
-Without the leaflet stuff:
+There is another data structure called `ent`, but it should not be modified—IITC has already processed this raw data.
+
+Simplified structure:
 ```typescript
  interface IITC.Portal {
      options:  {
@@ -74,20 +75,18 @@ Without the leaflet stuff:
 }
 ```
 
-This is the data you'll get for all portals on the map. Portal-Detail data are handled separately.
+This is the data structure for all portals on the map.  Portal-Detail data is handled separately.
 
-Be aware that Portals in 'Link-Zoom' have no data. They not even exists. IITC creates dummy-portals at the end of links. They only contain Position, GUID and Faction. So before processing check if data is available - like check if name is present.
+Be aware that portals in 'Link-Zoom' are dummy portals created by IITC at link endpoints. They contain only position, GUID, and faction information. Always check if data is available (e.g., verify the name exists) before processing portal details.
 
 
-### Back to our dialog
-First we count portals by each faction (portal.options.team). Then count these by level 8 to 1 (portal.options.data.level).
+### Back to Our Dialog
 
-All the <> stuff is for creating a html-table stored as HTML-String in `contents`. 
+We count portals by faction using `portal.options.team`, then count them by level (8 to 1) using `portal.options.data.level`.
 
-At last, we have to create the dialog by using IITC dialog helper. It's a IITC-wrapper for JQuery Dialogs.
-This is the function you'll use a lot for your dialogs. 
+The HTML string in `contents` builds a table. Finally, we create the dialog using IITC's dialog helper, which wraps jQuery dialogs. This is a function you'll use frequently for dialogs.
 
-Because we gave it an ID IITC will make sure that only one of our dialog is open at the same time.
+By providing an ID, IITC ensures only one instance of our dialog is open at a time.
 
 The table itself looks really boring. Let's add some CSS styling:
 
@@ -131,13 +130,11 @@ contents += "</table>"
 ```
 :::
 
-The CSS file we use here is processed by [postCSS](https://postcss.org/). This allows us to add some more elegant handling in our CSS like nested rules.
-VS-code won't know that our CSS uses the postCSS format. For better syntax highlighting install a postCSS extension (like: postcss-sugarss-language) and switch file type from css to postcss in the lower right corner of the editor.
+The CSS file is processed by [PostCSS](https://postcss.org/), which allows more elegant syntax like nested rules. VS Code won't recognize PostCSS by default. For better syntax highlighting, install a PostCSS extension (such as postcss-sugarss-language) and switch the file type from CSS to PostCSS in the editor's bottom right corner.
 
 What we did here:
-- our table uses the class "countTable"
-- evey odd row uses a different background color
-- added a special row (class "sep") as a separator
+- Applied the class `countTable` to our table
+- Alternated background colors on odd rows
+- Added a separator row with the `sep` class
 
-Instead of constructing this in an HTML-String we could have use JQuery of plain 'createElement's. 
-I usually start with a quick HTML-String and then rewrite these in JQuery to ease event handling. But that's up to you.
+Instead of building the HTML as a string, you could use jQuery or `createElement()`. I typically start with quick HTML strings and refactor to jQuery for better event handling, but that's your preference.