Clean/Fixup Readme

.gitignore

@@ -5,3 +5,5 @@
 # Locally built binaries
 /native_application/gorecv
 /example_client/gosend
+
+/web-ext-artifacts

README.md

@@ -1,38 +1,64 @@
 # Native Inserter
 
 Fork of the Clipboard Inserter whose purpose it is to automatically insert the
-data received by an in this repository included native application into a
+data received by a native application into a broswer page.
-broswer page.
 
 It is useful for use with text extraction tools like Textractor for looking up
 words in the browser.
 
-This repository contains the browser plugin, native application and native
+This repository contains the browser plugin, native application, native
-manifest. Textractor plugin is not included.
+messaging manifest and an example client. Textractor plugin is not included.
 
-Currently this addon is not available on any of the browsers Addon Store.
+Currently this addon is not available on any of the browsers addon stores, nor
+are releases past the fork signed by our benevolent overlords at
+Mozilla/Google.
 
-Only tested on GNU/Linux with Firefox.
+Only tested on GNU/Linux with Firefox 91 ESR.
 
 ## Install
 
 You will need:
 
- - This code
+- This code
- - A go compiler
+- A go compiler
- - A browser supporting native extensions (eg modern Firefox, Chrome)
+- A browser supporting native extensions (eg modern Firefox, Chrome)
 
 1) Compile and install the native application
-2) Put the native application manifest into your browsers expected directory
+2) Edit `native_inserter.json` to find the native application
-3) Install the addon in your browser
+3) Put `native_inserter.json` into your browsers native messaging manifest directory
+4) Build and install the addon in your browser
 
-For this to be useful you will also need a sender, for example a Textractor
+For this to be useful you will also need a sender, for example a [Textractor
-plugin (not included) and a browser page that the can be inserted to.
+plugin](https://github.com/45Tatami/Textractor-TCPSender) and a HTML page ([for
+example](https://pastebin.com/raw/DRDE075L)) that the can be inserted into.
+
+### Firefox
+
+This addon is not signed. From the [official Firefox
+documentation](https://extensionworkshop.com/documentation/publish/signing-and-distribution-overview/):
+
+> Unsigned extensions can be installed in Developer Edition, Nightly, and ESR
+> versions of Firefox, after toggling the xpinstall.signatures.required
+> preference in about:config.
+
+You can download the unsigned build from the releases or follow the official
+instruction for building addons, for example via `web-ext`:
+
+```
+$ npm install -g web-ext
+$ web-ext build
+```
+
+You can then install the resulting zip via the `Install Add-On From File`
+dialog under `about:addons`.
+
+The native messaging manifest directory under linux is
+`~/.mozilla/native-messaging-hosts`.
 
 ## How does it work
 
 The browser plugin starts a native application which creates a raw TCP listen
-socket for incoming connections.
+socket currently on all interfaces on port 30501 for incoming connections.
 
 One or more applications (eg Textractor plugin) will connect to this socket and
 send messages. Messages consist of a 4 Byte little-endian length header and
@@ -47,7 +73,12 @@ version.
 The native application is writing to stderr. Browsers usually forward this to
 their default log.
 
-The browser addon itself 
+The browser addon itself will log to the console. Problems with the native
+messaging manifest might not necessarily be logged.
+
+If the native application does not run in the background after loading the
+add-on, double-check if the native messaging manifest is in the correct
+directory and has the binary path set correctly.
 
 ## (Not so) FAQ
 
@@ -73,13 +104,15 @@ this has two drawbacks:
 server. This would mean the sending side would need to be the server and the
 native application the client, which would not work with multiple senders.
 
-2) The sending side (eg C++ Textractor plugin) will need to implement a
+2) The sending side (eg C++ Textractor plugin) would need to implement a
 Websocket server which is a lot more work than raw tcp.
 
 ## Bugs
 
-- Native messaging requires native host order prefixed messages. Golang does
+- Native messaging expects the length prefix in native byte order. Go does
-  not have an easy way to retrieve this information. The native application
+  neither have a non-unsafe way to convert an integer to a byte stream in
-  will use little-endian which is the default on most common architectures
+  native order for writing nor a way to detect endianness. The native
+  application will write in little-endian, which will break the protocol on
+  big-endian machines
 - Messages over the native-messaging 1MB limit will be discarded instead of
   split up