Improve book

- Write introduction - Move large readme sections into book - Rename docs to www type: documentation
casey · Apr 8, 2020 · e91b419 · e91b419
1 parent 1e5c19d
commit e91b419
Show file tree

Hide file tree

Showing 18 changed files with 151 additions and 119 deletions.
diff --git a/.github/workflows/main.yaml → .github/workflows/build.yaml b/.github/workflows/main.yaml → .github/workflows/build.yaml
diff --git a/.github/workflows/site.yaml → .github/workflows/www.yaml b/.github/workflows/site.yaml → .github/workflows/www.yaml
@@ -1,4 +1,4 @@
-name: Site
+name: WWW
 
 on:
   push:
@@ -18,11 +18,11 @@ jobs:
         uses: peaceiris/actions-mdbook@v1
         with:
           mdbook-version: latest
-      - run: mdbook build book --dest-dir ../docs/book
+      - run: mdbook build book --dest-dir ../www/book
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         if:   github.ref == 'refs/heads/master'
         with:
           github_token:   ${{secrets.GITHUB_TOKEN}}
           publish_branch: gh-pages
-          publish_dir:    ./docs
+          publish_dir:    ./www
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,3 @@
 /target
 **/*.rs.bk
-/book/book
+/www/book
diff --git a/README.md b/README.md
diff --git a/bin/lint b/bin/lint
@@ -2,4 +2,4 @@
 
 set -euxo pipefail
 
-! grep --color -REni 'FIXME|TODO|XXX|todo!|#\[ignore]' src
+! grep --color -REni 'FIXME|TODO|XXX|todo!|#\[ignore]' src book/src
diff --git a/book/book.toml b/book/book.toml
@@ -3,4 +3,4 @@ authors      = ["Casey Rodarmor"]
 language     = "en"
 multilingual = false
 src          = "src"
-title        = "imdl"
+title        = "Intermodal"
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -1,3 +1,8 @@
-# Summary
+Summary
+=======
 
-- [Notes](./notes.md)
+[Intermodal](./introduction.md)
+
+- [BitTorrent BEP Support](./bep-support.md)
+- [Alternatives & Prior Art](./prior-art.md)
+- [BitTorrent References](./bittorrent-references.md)
diff --git a/book/src/bep-support.md b/book/src/bep-support.md
@@ -0,0 +1,66 @@
+BEP Support
+===========
+
+| Symbol   | Meaning                     |
+|:--------:|-----------------------------|
+| &#x2705; | Supported                   |
+| &#x274C; | Unsupported (link to issue) |
+| &#x2796; | Not Applicable              |
+
+| BEP                                            | Status                                                     | Title                                                            |
+|:----------------------------------------------:|:----------------------------------------------------------:|:-----------------------------------------------------------------|
+| [00](http://bittorrent.org/beps/bep_0000.html) | &#x2796;                                                   | Index of BitTorrent Enhancement Proposals                        |
+| [01](http://bittorrent.org/beps/bep_0001.html) | &#x2796;                                                   | The BitTorrent Enhancement Proposal Process                      |
+| [02](http://bittorrent.org/beps/bep_0002.html) | &#x2796;                                                   | Sample reStructured Text BEP Template                            |
+| [03](http://bittorrent.org/beps/bep_0003.html) | &#x2705;                                                   | The BitTorrent Protocol Specification                            |
+| [04](http://bittorrent.org/beps/bep_0004.html) | &#x2796;                                                   | Assigned Numbers                                                 |
+| [05](http://bittorrent.org/beps/bep_0005.html) | &#x2705;                                                   | DHT Protocol                                                     |
+| [06](http://bittorrent.org/beps/bep_0006.html) | &#x2796;                                                   | Fast Extension                                                   |
+| [07](http://bittorrent.org/beps/bep_0007.html) | &#x2796;                                                   | IPv6 Tracker Extension                                           |
+| [08](http://bittorrent.org/beps/bep_0008.html) | &#x2796;                                                   | Tracker Peer Obfuscation                                         |
+| [09](http://bittorrent.org/beps/bep_0009.html) | &#x2705;                                                   | Extension for Peers to Send Metadata Files                       |
+| [10](http://bittorrent.org/beps/bep_0010.html) | &#x2796;                                                   | Extension Protocol                                               |
+| [11](http://bittorrent.org/beps/bep_0011.html) | &#x2796;                                                   | Peer Exchange (PEX)                                              |
+| [12](http://bittorrent.org/beps/bep_0012.html) | &#x2705;                                                   | Multitracker Metadata Extension                                  |
+| [14](http://bittorrent.org/beps/bep_0014.html) | &#x2796;                                                   | Local Service Discovery                                          |
+| [15](http://bittorrent.org/beps/bep_0015.html) | &#x2796;                                                   | UDP Tracker Protocol for BitTorrent                              |
+| [16](http://bittorrent.org/beps/bep_0016.html) | &#x2796;                                                   | Superseeding                                                     |
+| [17](http://bittorrent.org/beps/bep_0017.html) | [&#x274C;](https://github.com/casey/intermodal/issues/92)  | HTTP Seeding                                                     |
+| [18](http://bittorrent.org/beps/bep_0018.html) | &#x2796;                                                   | Search Engine Specificiation                                     |
+| [19](http://bittorrent.org/beps/bep_0019.html) | [&#x274C;](https://github.com/casey/intermodal/issues/93)  | WebSeed - HTTP/FTP Seeding (GetRight style)                      |
+| [20](http://bittorrent.org/beps/bep_0020.html) | &#x2796;                                                   | Peer ID Conventions                                              |
+| [21](http://bittorrent.org/beps/bep_0021.html) | &#x2796;                                                   | Extension for partial seeds                                      |
+| [22](http://bittorrent.org/beps/bep_0022.html) | &#x2796;                                                   | BitTorrent Local Tracker Discovery Protocol                      |
+| [23](http://bittorrent.org/beps/bep_0023.html) | &#x2796;                                                   | Tracker Returns Compact Peer Lists                               |
+| [24](http://bittorrent.org/beps/bep_0024.html) | &#x2796;                                                   | Tracker Returns External IP                                      |
+| [25](http://bittorrent.org/beps/bep_0025.html) | &#x2796;                                                   | An Alternate BitTorrent Cache Discovery Protocol                 |
+| [26](http://bittorrent.org/beps/bep_0026.html) | &#x2796;                                                   | Zeroconf Peer Advertising and Discovery                          |
+| [27](http://bittorrent.org/beps/bep_0027.html) | &#x2705;                                                   | Private Torrents                                                 |
+| [28](http://bittorrent.org/beps/bep_0028.html) | &#x2796;                                                   | Tracker exchange extension                                       |
+| [29](http://bittorrent.org/beps/bep_0029.html) | &#x2796;                                                   | uTorrent transport protocol                                      |
+| [30](http://bittorrent.org/beps/bep_0030.html) | [&#x274C;](https://github.com/casey/intermodal/issues/94)  | Merkle hash torrent extension                                    |
+| [31](http://bittorrent.org/beps/bep_0031.html) | &#x2796;                                                   | Failure Retry Extension                                          |
+| [32](http://bittorrent.org/beps/bep_0032.html) | &#x2796;                                                   | BitTorrent DHT Extensions for IPv6                               |
+| [33](http://bittorrent.org/beps/bep_0033.html) | &#x2796;                                                   | DHT Scrapes                                                      |
+| [34](http://bittorrent.org/beps/bep_0034.html) | &#x2796;                                                   | DNS Tracker Preferences                                          |
+| [35](http://bittorrent.org/beps/bep_0035.html) | [&#x274C;](https://github.com/casey/intermodal/issues/96)  | Torrent Signing                                                  |
+| [36](http://bittorrent.org/beps/bep_0036.html) | &#x2796;                                                   | Torrent RSS feeds                                                |
+| [37](http://bittorrent.org/beps/bep_0037.html) | &#x2796;                                                   | Anonymous BitTorrent over proxies                                |
+| [38](http://bittorrent.org/beps/bep_0038.html) | &#x2796;                                                   | Finding Local Data Via Torrent File Hints                        |
+| [39](http://bittorrent.org/beps/bep_0039.html) | [&#x274C;](https://github.com/casey/intermodal/issues/98)  | Updating Torrents Via Feed URL                                   |
+| [40](http://bittorrent.org/beps/bep_0040.html) | &#x2796;                                                   | Canonical Peer Priority                                          |
+| [41](http://bittorrent.org/beps/bep_0041.html) | &#x2796;                                                   | UDP Tracker Protocol Extensions                                  |
+| [42](http://bittorrent.org/beps/bep_0042.html) | &#x2796;                                                   | DHT Security extension                                           |
+| [43](http://bittorrent.org/beps/bep_0043.html) | &#x2796;                                                   | Read-only DHT Nodes                                              |
+| [44](http://bittorrent.org/beps/bep_0044.html) | &#x2796;                                                   | Storing arbitrary data in the DHT                                |
+| [45](http://bittorrent.org/beps/bep_0045.html) | &#x2796;                                                   | Multiple-address operation for the BitTorrent DHT                |
+| [46](http://bittorrent.org/beps/bep_0046.html) | [&#x274C;](https://github.com/casey/intermodal/issues/244) | Updating Torrents Via DHT Mutable Items                          |
+| [47](http://bittorrent.org/beps/bep_0047.html) | [&#x274C;](https://github.com/casey/intermodal/issues/99)  | Padding files and extended file attributes                       |
+| [48](http://bittorrent.org/beps/bep_0048.html) | &#x2796;                                                   | Tracker Protocol Extension: Scrape                               |
+| [49](http://bittorrent.org/beps/bep_0049.html) | [&#x274C;](https://github.com/casey/intermodal/issues/100) | Distributed Torrent Feeds                                        |
+| [50](http://bittorrent.org/beps/bep_0050.html) | &#x2796;                                                   | Publish/Subscribe Protocol                                       |
+| [51](http://bittorrent.org/beps/bep_0051.html) | &#x2796;                                                   | DHT Infohash Indexing                                            |
+| [52](http://bittorrent.org/beps/bep_0052.html) | [&#x274C;](https://github.com/casey/intermodal/issues/101) | The BitTorrent Protocol Specification v2                         |
+| [53](http://bittorrent.org/beps/bep_0053.html) | [&#x274C;](https://github.com/casey/intermodal/issues/245) | Magnet URI extension - Select specific file indices for download |
+| [54](http://bittorrent.org/beps/bep_0054.html) | &#x2796;                                                   | The lt_donthave extension                                        |
+| [55](http://bittorrent.org/beps/bep_0055.html) | &#x2796;                                                   | Holepunch extension                                              |
diff --git a/book/src/bittorrent-references.md b/book/src/bittorrent-references.md
@@ -0,0 +1,10 @@
+BitTorrent References
+---------------------
+
+| URL                                                         | Description                                                                                       |
+|:------------------------------------------------------------|:--------------------------------------------------------------------------------------------------|
+| https://github.com/bittorrent/bittorrent.org                | GitHub repository hosting protocol development discussion and contents of bittorrent.org.         |
+| https://www.bittorrent.org                                  | Official web site site hosting BEPs and other information about the protocol.                     |
+| https://wiki.theory.org/index.php/Main_Page                 | Wiki with lots of information about all aspects of the BitTorrent protocol and implementations.   |
+| https://archive.org/details/2014_torrent_archive_organized) | Massive 158 GiB archive containing 5.5 million torrents, assembled in 2014.                       |
+| https://github.com/internetarchive/dweb-transport           | Github repository hosting The Internet Archive's distributed web and BitTorrent-related software. |
diff --git a/book/src/introduction.md b/book/src/introduction.md
@@ -0,0 +1,39 @@
+# Intermodal
+
+Intermodal is, as the moment, a BitTorrent metainfo utility. The binary is called `imdl`.
+
+Project development is hosted on GitHub at [github.com/casey/intermodal](https://github.com/casey/intermodal).
+
+Intermodal can be used to create `.torrent` files:
+
+```
+$ imdl torrent create --input foo
+```
+
+Print information about existing torrent files:
+
+```
+$ imdl torrent show --input foo.torrent
+```
+
+Verify downloaded torrents:
+
+```
+$ imdl torrent verify --input foo.torrent --content foo
+```
+
+Generate magnet links from torrent files:
+
+```
+$ imdl torrent link --input foo.torrent
+```
+
+Functionality that is not yet finalized, but still available for preview, can be accessed with the `--unstable` flag:
+
+Print information about a collection of torrents:
+
+```
+$ imdl --unstable torrent stats --input dir
+```
+
+Happy sharing!
diff --git a/book/src/prior-art.md b/book/src/prior-art.md
@@ -0,0 +1,19 @@
+Alternatives & Prior Art
+------------------------
+
+| Name                                                                              | UI                      | Language   | Notes                                                                                                                                     |
+|-----------------------------------------------------------------------------------|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| [torf-cli](https://github.com/rndusr/torf-cli)                                    | CLI                     | Python     | Highly recommended utility for creating torrents and magnet links, as well as displaying information about and editing existing torrents. |
+| [mktorrent](https://github.com/Rudde/mktorrent)                                   | CLI                     | C          | Popular but unmaintained torrent file creator.                                                                                            |
+| [pmktorrent](https://github.com/xxkfqz/pmktorrent)                                | CLI                     | C          | Maintained fork of mktorrent.                                                                                                             |
+| [mktorrent](https://github.com/mukaibot/mktorrent)                                | Library                 | Ruby       | Library for creating torrent files.                                                                                                       |
+| [py3createtorrent](https://github.com/rsnitsch/py3createtorrent/)                 | CLI                     | Python     | Torrent file creator.                                                                                                                     |
+| [create-torrent](https://github.com/webtorrent/create-torrent)                    | Library&nbsp;&&nbsp;CLI | JavaScript | Javascript library and CLI for creating torrents.                                                                                         |
+| [whatmp3](https://github.com/RecursiveForest/whatmp3)                             | CLI                     | Python     | Torrent file creator that automatically transcodes FLAC files.                                                                            |
+| [torrent-file-editor](https://github.com/torrent-file-editor/torrent-file-editor) | GUI                     | C++        | Graphical torrent file editor.                                                                                                            |
+| [torrent2magnet](https://github.com/repolho/torrent2magnet)                       | CLI                     | Python     | Creates magnet links from torrent files.                                                                                                  |
+| [h2torrent](https://github.com/elektito/ih2torrent)                               | CLI                     | Python     | Creates .torrent files from an infohash or magnet URI.                                                                                    |
+| [dottorrent](https://github.com/kz26/dottorrent)                                  | Library                 | Python     | Library for creating torrent files                                                                                                        |
+| [dottorrent-cli](https://github.com/kz26/dottorrent-cli)                          | CLI                     | Python     | Torrent file creator.                                                                                                                     |
+| [torrent-creator](https://github.com/kimbatt/torrent-creator/)                    | Web page                | Typescript | Single-page web app torrent file creator.                                                                                                 |
+| [pyrocore](https://github.com/pyroscope/pyrocore)                                 | CLI                     | PYthon     | Utilities for creating, modifying, and displaying torrent files.                                                                          |
diff --git a/justfile b/justfile
@@ -48,7 +48,7 @@ preview-readme:
 
 # build and serve the book
 book:
-	mdbook serve book --open
+	mdbook serve book --open --dest-dir ../www/book
 
 # add git log messages to changelog
 changes:
@@ -62,10 +62,6 @@ dev-deps:
 update-toc:
 	cargo run --package update-readme toc
 
-# update readme table of supported BEPs
-update-supported-beps:
-	cargo run --package update-readme supported-beps
-
 check-minimal-versions:
 	./bin/check-minimal-versions
 
@@ -88,9 +84,9 @@ publish: publish-check
 	git tag -a {{version}} -m 'Release {{version}}'
 	git push github {{version}}
 
-# open github pages index
-open-pages:
-	open docs/index.html
+# open site index
+www:
+	open www/index.html
 
 # retrieve large collection of torrents from the Internet Archive
 get-torrents:

diff --git a/src.torrent b/src.torrent
diff --git a/docs/CNAME → www/CNAME b/docs/CNAME → www/CNAME
diff --git a/docs/favicon.ico → www/favicon.ico b/docs/favicon.ico → www/favicon.ico
diff --git a/docs/index.css → www/index.css b/docs/index.css → www/index.css
diff --git a/docs/index.html → www/index.html b/docs/index.html → www/index.html
diff --git a/docs/install.sh → www/install.sh b/docs/install.sh → www/install.sh
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		set -euxo pipefail

		! grep --color -REni 'FIXME\|TODO\|XXX\|todo!\|#\[ignore]' src
		! grep --color -REni 'FIXME\|TODO\|XXX\|todo!\|#\[ignore]' src book/src