Improve book

- Write introduction
- Move large readme sections into book
- Rename docs to www

type: documentation
This commit is contained in:
Casey Rodarmor 2020-03-19 19:06:05 -07:00
parent 1e5c19d02b
commit e91b419af5
No known key found for this signature in database
GPG Key ID: 556186B153EC6FE0
18 changed files with 151 additions and 119 deletions

View File

@ -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

2
.gitignore vendored
View File

@ -1,3 +1,3 @@
/target
**/*.rs.bk
/book/book
/www/book

103
README.md
View File

@ -17,11 +17,6 @@ binary is called `imdl`.
- [Cargo](#cargo)
- [Semantic Versioning](#semantic-versioning)
- [Unstable Features](#unstable-features)
- [Bittorrent](#bittorrent)
- [BEP Support](#bep-support)
- [References](#references)
- [Alternatives & Prior Art](#alternatives--prior-art)
- [BitTorrent](#bittorrent)
- [Acknowledgments](#acknowledgments)
## General
@ -72,104 +67,6 @@ are unavailable unless the `--unstable` / `-u` flag is passed, for example
`imdl --unstable torrent create .`. Unstable features may be changed or removed
at any time.
## Bittorrent
### BEP Support
| Symbol | Meaning |
|:------------------:|---------------------------------------|
| :white_check_mark: | Supported |
| :x: | Unsupported (links to tracking issue) |
| :heavy_minus_sign: | Not Applicable |
| BEP | Status | Title |
|:----------------------------------------------:|:-----------------------------------------------------:|:-----------------------------------------------------------------|
| [00](http://bittorrent.org/beps/bep_0000.html) | :heavy_minus_sign: | Index of BitTorrent Enhancement Proposals |
| [01](http://bittorrent.org/beps/bep_0001.html) | :heavy_minus_sign: | The BitTorrent Enhancement Proposal Process |
| [02](http://bittorrent.org/beps/bep_0002.html) | :heavy_minus_sign: | Sample reStructured Text BEP Template |
| [03](http://bittorrent.org/beps/bep_0003.html) | :white_check_mark: | The BitTorrent Protocol Specification |
| [04](http://bittorrent.org/beps/bep_0004.html) | :heavy_minus_sign: | Assigned Numbers |
| [05](http://bittorrent.org/beps/bep_0005.html) | :white_check_mark: | DHT Protocol |
| [06](http://bittorrent.org/beps/bep_0006.html) | :heavy_minus_sign: | Fast Extension |
| [07](http://bittorrent.org/beps/bep_0007.html) | :heavy_minus_sign: | IPv6 Tracker Extension |
| [08](http://bittorrent.org/beps/bep_0008.html) | :heavy_minus_sign: | Tracker Peer Obfuscation |
| [09](http://bittorrent.org/beps/bep_0009.html) | :white_check_mark: | Extension for Peers to Send Metadata Files |
| [10](http://bittorrent.org/beps/bep_0010.html) | :heavy_minus_sign: | Extension Protocol |
| [11](http://bittorrent.org/beps/bep_0011.html) | :heavy_minus_sign: | Peer Exchange (PEX) |
| [12](http://bittorrent.org/beps/bep_0012.html) | :white_check_mark: | Multitracker Metadata Extension |
| [14](http://bittorrent.org/beps/bep_0014.html) | :heavy_minus_sign: | Local Service Discovery |
| [15](http://bittorrent.org/beps/bep_0015.html) | :heavy_minus_sign: | UDP Tracker Protocol for BitTorrent |
| [16](http://bittorrent.org/beps/bep_0016.html) | :heavy_minus_sign: | Superseeding |
| [17](http://bittorrent.org/beps/bep_0017.html) | [:x:](https://github.com/casey/intermodal/issues/92) | HTTP Seeding |
| [18](http://bittorrent.org/beps/bep_0018.html) | :heavy_minus_sign: | Search Engine Specificiation |
| [19](http://bittorrent.org/beps/bep_0019.html) | [:x:](https://github.com/casey/intermodal/issues/93) | WebSeed - HTTP/FTP Seeding (GetRight style) |
| [20](http://bittorrent.org/beps/bep_0020.html) | :heavy_minus_sign: | Peer ID Conventions |
| [21](http://bittorrent.org/beps/bep_0021.html) | :heavy_minus_sign: | Extension for partial seeds |
| [22](http://bittorrent.org/beps/bep_0022.html) | :heavy_minus_sign: | BitTorrent Local Tracker Discovery Protocol |
| [23](http://bittorrent.org/beps/bep_0023.html) | :heavy_minus_sign: | Tracker Returns Compact Peer Lists |
| [24](http://bittorrent.org/beps/bep_0024.html) | :heavy_minus_sign: | Tracker Returns External IP |
| [25](http://bittorrent.org/beps/bep_0025.html) | :heavy_minus_sign: | An Alternate BitTorrent Cache Discovery Protocol |
| [26](http://bittorrent.org/beps/bep_0026.html) | :heavy_minus_sign: | Zeroconf Peer Advertising and Discovery |
| [27](http://bittorrent.org/beps/bep_0027.html) | :white_check_mark: | Private Torrents |
| [28](http://bittorrent.org/beps/bep_0028.html) | :heavy_minus_sign: | Tracker exchange extension |
| [29](http://bittorrent.org/beps/bep_0029.html) | :heavy_minus_sign: | uTorrent transport protocol |
| [30](http://bittorrent.org/beps/bep_0030.html) | [:x:](https://github.com/casey/intermodal/issues/94) | Merkle hash torrent extension |
| [31](http://bittorrent.org/beps/bep_0031.html) | :heavy_minus_sign: | Failure Retry Extension |
| [32](http://bittorrent.org/beps/bep_0032.html) | :heavy_minus_sign: | BitTorrent DHT Extensions for IPv6 |
| [33](http://bittorrent.org/beps/bep_0033.html) | :heavy_minus_sign: | DHT Scrapes |
| [34](http://bittorrent.org/beps/bep_0034.html) | :heavy_minus_sign: | DNS Tracker Preferences |
| [35](http://bittorrent.org/beps/bep_0035.html) | [:x:](https://github.com/casey/intermodal/issues/96) | Torrent Signing |
| [36](http://bittorrent.org/beps/bep_0036.html) | :heavy_minus_sign: | Torrent RSS feeds |
| [37](http://bittorrent.org/beps/bep_0037.html) | :heavy_minus_sign: | Anonymous BitTorrent over proxies |
| [38](http://bittorrent.org/beps/bep_0038.html) | :heavy_minus_sign: | Finding Local Data Via Torrent File Hints |
| [39](http://bittorrent.org/beps/bep_0039.html) | [:x:](https://github.com/casey/intermodal/issues/98) | Updating Torrents Via Feed URL |
| [40](http://bittorrent.org/beps/bep_0040.html) | :heavy_minus_sign: | Canonical Peer Priority |
| [41](http://bittorrent.org/beps/bep_0041.html) | :heavy_minus_sign: | UDP Tracker Protocol Extensions |
| [42](http://bittorrent.org/beps/bep_0042.html) | :heavy_minus_sign: | DHT Security extension |
| [43](http://bittorrent.org/beps/bep_0043.html) | :heavy_minus_sign: | Read-only DHT Nodes |
| [44](http://bittorrent.org/beps/bep_0044.html) | :heavy_minus_sign: | Storing arbitrary data in the DHT |
| [45](http://bittorrent.org/beps/bep_0045.html) | :heavy_minus_sign: | Multiple-address operation for the BitTorrent DHT |
| [46](http://bittorrent.org/beps/bep_0046.html) | [:x:](https://github.com/casey/intermodal/issues/244) | Updating Torrents Via DHT Mutable Items |
| [47](http://bittorrent.org/beps/bep_0047.html) | [:x:](https://github.com/casey/intermodal/issues/99) | Padding files and extended file attributes |
| [48](http://bittorrent.org/beps/bep_0048.html) | :heavy_minus_sign: | Tracker Protocol Extension: Scrape |
| [49](http://bittorrent.org/beps/bep_0049.html) | [:x:](https://github.com/casey/intermodal/issues/100) | Distributed Torrent Feeds |
| [50](http://bittorrent.org/beps/bep_0050.html) | :heavy_minus_sign: | Publish/Subscribe Protocol |
| [51](http://bittorrent.org/beps/bep_0051.html) | :heavy_minus_sign: | DHT Infohash Indexing |
| [52](http://bittorrent.org/beps/bep_0052.html) | [:x:](https://github.com/casey/intermodal/issues/101) | The BitTorrent Protocol Specification v2 |
| [53](http://bittorrent.org/beps/bep_0053.html) | [:x:](https://github.com/casey/intermodal/issues/245) | Magnet URI extension - Select specific file indices for download |
| [54](http://bittorrent.org/beps/bep_0054.html) | :heavy_minus_sign: | The lt_donthave extension |
| [55](http://bittorrent.org/beps/bep_0055.html) | :heavy_minus_sign: | Holepunch extension |
## References
### 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 & 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. |
### BitTorrent
| 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. |
## Acknowledgments
The formatting of `imdl torrent show` is entirely copied from

View File

@ -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

View File

@ -3,4 +3,4 @@ authors = ["Casey Rodarmor"]
language = "en"
multilingual = false
src = "src"
title = "imdl"
title = "Intermodal"

View File

@ -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)

66
book/src/bep-support.md Normal file
View File

@ -0,0 +1,66 @@
BEP Support
===========
| Symbol | Meaning |
|:--------:|-----------------------------|
| ✅ | Supported |
| ❌ | Unsupported (link to issue) |
| ➖ | Not Applicable |
| BEP | Status | Title |
|:----------------------------------------------:|:----------------------------------------------------------:|:-----------------------------------------------------------------|
| [00](http://bittorrent.org/beps/bep_0000.html) | ➖ | Index of BitTorrent Enhancement Proposals |
| [01](http://bittorrent.org/beps/bep_0001.html) | ➖ | The BitTorrent Enhancement Proposal Process |
| [02](http://bittorrent.org/beps/bep_0002.html) | ➖ | Sample reStructured Text BEP Template |
| [03](http://bittorrent.org/beps/bep_0003.html) | ✅ | The BitTorrent Protocol Specification |
| [04](http://bittorrent.org/beps/bep_0004.html) | ➖ | Assigned Numbers |
| [05](http://bittorrent.org/beps/bep_0005.html) | ✅ | DHT Protocol |
| [06](http://bittorrent.org/beps/bep_0006.html) | ➖ | Fast Extension |
| [07](http://bittorrent.org/beps/bep_0007.html) | ➖ | IPv6 Tracker Extension |
| [08](http://bittorrent.org/beps/bep_0008.html) | ➖ | Tracker Peer Obfuscation |
| [09](http://bittorrent.org/beps/bep_0009.html) | ✅ | Extension for Peers to Send Metadata Files |
| [10](http://bittorrent.org/beps/bep_0010.html) | ➖ | Extension Protocol |
| [11](http://bittorrent.org/beps/bep_0011.html) | ➖ | Peer Exchange (PEX) |
| [12](http://bittorrent.org/beps/bep_0012.html) | ✅ | Multitracker Metadata Extension |
| [14](http://bittorrent.org/beps/bep_0014.html) | ➖ | Local Service Discovery |
| [15](http://bittorrent.org/beps/bep_0015.html) | ➖ | UDP Tracker Protocol for BitTorrent |
| [16](http://bittorrent.org/beps/bep_0016.html) | ➖ | Superseeding |
| [17](http://bittorrent.org/beps/bep_0017.html) | [❌](https://github.com/casey/intermodal/issues/92) | HTTP Seeding |
| [18](http://bittorrent.org/beps/bep_0018.html) | ➖ | Search Engine Specificiation |
| [19](http://bittorrent.org/beps/bep_0019.html) | [❌](https://github.com/casey/intermodal/issues/93) | WebSeed - HTTP/FTP Seeding (GetRight style) |
| [20](http://bittorrent.org/beps/bep_0020.html) | ➖ | Peer ID Conventions |
| [21](http://bittorrent.org/beps/bep_0021.html) | ➖ | Extension for partial seeds |
| [22](http://bittorrent.org/beps/bep_0022.html) | ➖ | BitTorrent Local Tracker Discovery Protocol |
| [23](http://bittorrent.org/beps/bep_0023.html) | ➖ | Tracker Returns Compact Peer Lists |
| [24](http://bittorrent.org/beps/bep_0024.html) | ➖ | Tracker Returns External IP |
| [25](http://bittorrent.org/beps/bep_0025.html) | ➖ | An Alternate BitTorrent Cache Discovery Protocol |
| [26](http://bittorrent.org/beps/bep_0026.html) | ➖ | Zeroconf Peer Advertising and Discovery |
| [27](http://bittorrent.org/beps/bep_0027.html) | ✅ | Private Torrents |
| [28](http://bittorrent.org/beps/bep_0028.html) | ➖ | Tracker exchange extension |
| [29](http://bittorrent.org/beps/bep_0029.html) | ➖ | uTorrent transport protocol |
| [30](http://bittorrent.org/beps/bep_0030.html) | [❌](https://github.com/casey/intermodal/issues/94) | Merkle hash torrent extension |
| [31](http://bittorrent.org/beps/bep_0031.html) | ➖ | Failure Retry Extension |
| [32](http://bittorrent.org/beps/bep_0032.html) | ➖ | BitTorrent DHT Extensions for IPv6 |
| [33](http://bittorrent.org/beps/bep_0033.html) | ➖ | DHT Scrapes |
| [34](http://bittorrent.org/beps/bep_0034.html) | ➖ | DNS Tracker Preferences |
| [35](http://bittorrent.org/beps/bep_0035.html) | [❌](https://github.com/casey/intermodal/issues/96) | Torrent Signing |
| [36](http://bittorrent.org/beps/bep_0036.html) | ➖ | Torrent RSS feeds |
| [37](http://bittorrent.org/beps/bep_0037.html) | ➖ | Anonymous BitTorrent over proxies |
| [38](http://bittorrent.org/beps/bep_0038.html) | ➖ | Finding Local Data Via Torrent File Hints |
| [39](http://bittorrent.org/beps/bep_0039.html) | [❌](https://github.com/casey/intermodal/issues/98) | Updating Torrents Via Feed URL |
| [40](http://bittorrent.org/beps/bep_0040.html) | ➖ | Canonical Peer Priority |
| [41](http://bittorrent.org/beps/bep_0041.html) | ➖ | UDP Tracker Protocol Extensions |
| [42](http://bittorrent.org/beps/bep_0042.html) | ➖ | DHT Security extension |
| [43](http://bittorrent.org/beps/bep_0043.html) | ➖ | Read-only DHT Nodes |
| [44](http://bittorrent.org/beps/bep_0044.html) | ➖ | Storing arbitrary data in the DHT |
| [45](http://bittorrent.org/beps/bep_0045.html) | ➖ | Multiple-address operation for the BitTorrent DHT |
| [46](http://bittorrent.org/beps/bep_0046.html) | [❌](https://github.com/casey/intermodal/issues/244) | Updating Torrents Via DHT Mutable Items |
| [47](http://bittorrent.org/beps/bep_0047.html) | [❌](https://github.com/casey/intermodal/issues/99) | Padding files and extended file attributes |
| [48](http://bittorrent.org/beps/bep_0048.html) | ➖ | Tracker Protocol Extension: Scrape |
| [49](http://bittorrent.org/beps/bep_0049.html) | [❌](https://github.com/casey/intermodal/issues/100) | Distributed Torrent Feeds |
| [50](http://bittorrent.org/beps/bep_0050.html) | ➖ | Publish/Subscribe Protocol |
| [51](http://bittorrent.org/beps/bep_0051.html) | ➖ | DHT Infohash Indexing |
| [52](http://bittorrent.org/beps/bep_0052.html) | [❌](https://github.com/casey/intermodal/issues/101) | The BitTorrent Protocol Specification v2 |
| [53](http://bittorrent.org/beps/bep_0053.html) | [❌](https://github.com/casey/intermodal/issues/245) | Magnet URI extension - Select specific file indices for download |
| [54](http://bittorrent.org/beps/bep_0054.html) | ➖ | The lt_donthave extension |
| [55](http://bittorrent.org/beps/bep_0055.html) | ➖ | Holepunch extension |

View File

@ -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. |

39
book/src/introduction.md Normal file
View File

@ -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!

19
book/src/prior-art.md Normal file
View File

@ -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 & 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. |

View File

@ -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:

BIN
src.torrent Normal file

Binary file not shown.

View File

Before

Width:  |  Height:  |  Size: 1.4 KiB

After

Width:  |  Height:  |  Size: 1.4 KiB