[GitHub] [pulsar] Anonymitaet commented on a change in pull request #13401: [Doc] Add docs on how to install the Pulsar Wireshark dissector

[GitBox <gi...@apache.org>]

Anonymitaet commented on a change in pull request #13401:
URL: https://github.com/apache/pulsar/pull/13401#discussion_r772936702



##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```

Review comment:
       ```suggestion
   Based on your operating system, run the following command.
   
   - macOS
   xxx
   
   - Ubuntu
   xxx
   ```
   
   suggest using unordered lists since they do not deserve "headings“

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```

Review comment:
       same comments

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.
+
+### Install Wireshark dissector
+
+Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+
+#### Find the Personal Plugins Location
+
+1. Open Wireshark
+2. Click About Wireshark
+3. Find Folders tab

Review comment:
       ```suggestion
   3. Click **Folders** tab.
   ```
   do you mean this?

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.
+
+### Install Wireshark dissector
+
+Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+
+#### Find the Personal Plugins Location
+
+1. Open Wireshark
+2. Click About Wireshark
+3. Find Folders tab
+
+You can see the Personal Plugins Location, which is important for the next step.
+
+#### Copy Wireshark dissector to appropriate location
+
+Example for Wireshark 3.6.0 on macOS (This Location should be the previous step got Personal Plugins Location):
+
+~/.local/lib/wireshark/plugins/3-6/
+
+```shell
+cd ~/.local/lib/wireshark/plugins/3-6/
+mkdir -p ~/.local/lib/wireshark/plugins/3-6/epan
+cd pulsar-client-cpp/wireshark
+cp pulsar-dissector.so ~/.local/lib/wireshark/plugins/3-6/epan
+```
+
+#### Complete installation
+
+Reboot Wireshark, you should be able to see the pulsar-dissector in:

Review comment:
       ```suggestion
   Reboot Wireshark. You can see the pulsar-dissector in **View > Internals > Dissector Tables**.
   ```

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.

Review comment:
       ```suggestion
   > **NOTE**
   > Make sure the Wireshark application version is the same as the Wireshark headers version.
   ```
   
   Do not use **please** in technical information. Technical information requires an authoritative tone. Terms of politeness are superfluous, convey the wrong tone for technical material, and are not regarded the same way in all cultures. In marketing information, terms of politeness might be appropriate. Use the imperative mood in the first sentence of each step.
   
   Details see https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#bookmark=id.x24xr2yx9b9t

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,

Review comment:
       is this a tip? if so, we can update it as:
   ```suggestion
   > **Tip**
   > If the compiler cannot find the Wireshark headers, add the include path manually.
   > `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>`
   ```

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.

Review comment:
       ```suggestion
   This creates the `pulsar-dissector.so` plugin library in the Wireshark directory.
   ```
   Write in the simple present tense as much as possible if you are covering facts that were, are, and forever shall be true. Details see https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#bookmark=id.e8uqh1awkcnp
   

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.

Review comment:
       ```suggestion
   To build the Wireshark plugin, install Wireshark with the development headers
   ```
   
   do you mean this?

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.
+
+### Install Wireshark dissector
+
+Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+
+#### Find the Personal Plugins Location
+
+1. Open Wireshark
+2. Click About Wireshark

Review comment:
       ```suggestion
   2. Click **About Wireshark**
   ```
   
   Use bold for menus, menu items, separator symbols, items in the navigation tree, and the greater than symbol. If a menu contains variable menu items, use lowercase bold italic. 
   
   https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#bookmark=id.7x9g7hiebz8x
   
   

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.
+
+### Install Wireshark dissector
+
+Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+
+#### Find the Personal Plugins Location
+
+1. Open Wireshark
+2. Click About Wireshark
+3. Find Folders tab
+
+You can see the Personal Plugins Location, which is important for the next step.

Review comment:
       should we capitalize each word for "Personal Plugins Location"? is it a proper noun?

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark

Review comment:
       should we use ## instead of ###?

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:
+
+```shell
+cd pulsar-client-cpp
+cmake -DBUILD_WIRESHARK=ON .
+make pulsar-dissector
+```
+
+This will create the `pulsar-dissector.so` plugin library in Wireshark directory.
+
+### Install Wireshark dissector
+
+Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+
+#### Find the Personal Plugins Location
+
+1. Open Wireshark
+2. Click About Wireshark
+3. Find Folders tab
+
+You can see the Personal Plugins Location, which is important for the next step.

Review comment:
       How about changing it as below?
   
   You can see the location of personal plugins, which is important for the next step.
   
   Example
   
   Wireshark 3.6.0 on macOS
   
   ```
   ~/.local/lib/wireshark/plugins/3-6/
   ```
   

##########
File path: pulsar-client-cpp/wireshark/README.md
##########
@@ -0,0 +1,84 @@
+# Pulsar Wireshark dissector
+
+The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
+and visualize useful debug information (linking requests with responses, latency stats, etc.)
+
+### Install Wireshark
+
+#### macOS
+
+Recommend use this way to install Wireshark in macOS.
+
+```bash
+brew install homebrew/cask/wireshark
+```
+
+#### Ubuntu
+
+```bash
+sudo apt install wireshark
+```
+
+### Install dependencies
+
+Install Wireshark with the development headers, necessary in order to build the plugin.
+
+**NOTE**: Please make sure the Wireshark application version is the same as the Wireshark Headers version.
+
+#### macOS
+
+```shell
+$ brew install wireshark
+```
+
+#### Ubuntu
+
+```shell
+$ sudo apt install wireshark-dev
+```
+
+### Compile the dissector
+
+> If the compiler cannot find the wireshark headers,
+> please use `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>` to manually add include path.
+
+Compile the dissector:

Review comment:
       ```suggestion
   Compile the dissector.
   ```
   Use a period (rather than colon) at the end of a sentence.
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org