From 52d9b8103a3a659c077b19427e2701127247e9df Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Fri, 2 Sep 2022 17:02:35 +0100
Subject: [PATCH] READMEs: Run maint/readmes (to update READMEs from lib.rs)

---
 crates/arti-client/README.md |  3 +-
 crates/arti/README.md        | 57 ++++++++++++++++++++++++++++++++++--
 2 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/crates/arti-client/README.md b/crates/arti-client/README.md
index f3d4e2ca7..466dc5bcd 100644
--- a/crates/arti-client/README.md
+++ b/crates/arti-client/README.md
@@ -25,7 +25,8 @@ right now your best bet is probably to spawn the
 [`arti` CLI](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html)
 SOCKS proxy,
 as a subprocess.
-We don't yet offer an API that would be nice to expose via FFI.
+We don't yet offer an API that would be nice to expose via FFI;
+we intend to add this in the future.
 
 ### ⚠ Warnings ⚠
 
diff --git a/crates/arti/README.md b/crates/arti/README.md
index aeb8db825..d63ea0c59 100644
--- a/crates/arti/README.md
+++ b/crates/arti/README.md
@@ -14,10 +14,10 @@ It will listen on port 9150 by default,
 but you can override this in the configuration.
 You can direct programs to connect via that SOCKS port,
 and their connections will be anonymized via Tor.
-NB you might not want to run a conventional web browser this way.
+Note: you might not want to run a conventional web browser this way.
 Browsers leak much private information.
 To browse the web anonymously,
-we recommend using [`Tor Browser`](https://www.torproject.org/download/).
+we recommend [using Tor Browser](#using-arti-with-tor-browser).
 
 Arti is still advancing rapidly; we are adding features and eventually
 we hope it will be able to replace C Tor.
@@ -54,6 +54,59 @@ More detailed information about for the individual fields is available in the do
 for the Rust APIs [`ApplicationConfigBuilder`] and
 [`TorClientConfigBuilder`](arti_client::config::TorClientConfigBuilder).
 
+## Using Arti with Tor Browser
+
+It is possible to hook up Arti with
+[Tor Browser](https://www.torproject.org/download/).
+
+To do so, we will launch arti independently from Tor Browser. Build arti with
+`cargo build --release`.  After that launch it with some basic
+configuration parameters:
+
+```
+$ ./target/release/arti proxy -l debug -p 9150
+```
+
+This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
+Tor Browser and instruct it to use that SOCKS port.
+
+#### Linux
+
+```
+$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
+```
+
+#### OS X
+
+```
+$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
+```
+
+#### Windows
+
+Create a shortcut with the `Target` set to:
+
+```
+C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
+```
+
+and `Start in` set to:
+
+```
+"C:\path\to\Tor Browser\Browser"
+```
+
+(You may need to adjust the actual path to wherever you have put your Tor
+Browser.)
+
+When you start Tor browser, it will give you a big red error page because
+Arti isn't offering it a control port interface.  But it will still work!
+Try [check.torproject.org](https://check.torproject.org/) to be sure.
+
+The resulting Tor Browser should be using arti.  Note that onion services
+won't work (Arti doesn't have them yet), and neither will any feature
+depending on Tor's control-port protocol.
+
 ## Compile-time features
 
 ### Additive features