Generate reference sections with bin/gen

type: documentation

CHANGELOG.md

@@ -2,9 +2,10 @@ Changelog
 =========
 
 
-UNRELEASED - 2020-04-18
+UNRELEASED - 2020-04-19
 -----------------------
-- :art: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Use `invariant` instead of `unwrap` and `expect` - Fixes [#167](https://github.com/casey/intermodal/issues/167) - _Casey Rodarmor <casey@rodarmor.com>_
+- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Generate reference sections with `bin/gen` - _Casey Rodarmor <casey@rodarmor.com>_
+- :art: [`a6bf75279181`](https://github.com/casey/intermodal/commit/a6bf7527918178821e080db10e65b057f427200d) Use `invariant` instead of `unwrap` and `expect` - Fixes [#167](https://github.com/casey/intermodal/issues/167) - _Casey Rodarmor <casey@rodarmor.com>_
 - :white_check_mark: [`faf46c0f0e6f`](https://github.com/casey/intermodal/commit/faf46c0f0e6fd4e4f8b504d414a3bf02d7d68e4a) Test that globs match torrent contents - Fixes [#377](https://github.com/casey/intermodal/issues/377) - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`0a754d0bcfcf`](https://github.com/casey/intermodal/commit/0a754d0bcfcfd65127d7b6e78d41852df78d3ea2) Add manual Arch install link - Fixes [#373](https://github.com/casey/intermodal/issues/373) - _Casey Rodarmor <casey@rodarmor.com>_
 - :art: [`0a870ed2ee2c`](https://github.com/casey/intermodal/commit/0a870ed2ee2cca79fddb9940fb879354468deb4d) Get current time early when creating torrents - Fixes [#207](https://github.com/casey/intermodal/issues/207) - _Casey Rodarmor <casey@rodarmor.com>_

bin/gen/config.yaml

@@ -60,3 +60,64 @@ packages:
   package-manager:  'Manual Installation'
   package:          '[intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup>'
   command:          '[wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages)'
+
+references:
+  - title: BitTorrent
+    entries:
+    - url: https://github.com/bittorrent/bittorrent.org
+      description: >-
+        GitHub repository hosting protocol development discussion and contents of
+        bittorrent.org.
+
+    - url: https://www.bittorrent.org
+      description: >-
+        Official web site site hosting BEPs and other information about the
+        protocol.
+
+    - url: https://wiki.theory.org/index.php/Main_Page
+      description: >-
+        Wiki with lots of information about all aspects of the BitTorrent
+        protocol and implementations.
+
+    - url: https://archive.org/details/2014_torrent_archive_organized)
+      description: >-
+        Massive 158 GiB archive containing 5.5 million torrents, assembled in
+        2014.
+
+    - url: https://github.com/internetarchive/dweb-transport
+      description: >-
+        Github repository hosting The Internet Archive's distributed web and
+        BitTorrent-related software.
+
+    - url: https://libtorrent.org/udp_tracker_protocol.html
+      description: UDP tracker protocol description.
+
+  - title: Metadata
+    entries:
+    - title: Media RSS Specification
+      url: http://www.rssboard.org/media-rss
+      description: >-
+        _Media RSS is a new RSS module that supplements the <enclosure>
+        capabilities of RSS 2.0. RSS enclosures are already being used to
+        syndicate audio files and images. Media RSS extends enclosures to handle
+        other media types, such as short films or TV, as well as provide
+        additional metadata with the media. Media RSS enables content publishers
+        and bloggers to syndicate multimedia content such as TV and video clips,
+        movies, images and audio._
+
+  - title: Cryptography
+    entries:
+    - url: https://ssbc.github.io/scuttlebutt-protocol-guide/
+      description: Secure Scuttlebutt Protocol guide
+
+    - url: https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md
+      description: 'Lightning Network Encrypted and Authenticated Transport'
+
+    - url: http://noiseprotocol.org/noise.html
+      description: 'Noise Protocol'
+
+    - url: https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js
+      description: 'Handshake P2P Encryption Protocol'
+
+    - url: https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md
+      description: 'Grin Slate Serialization'

bin/gen/src/common.rs

@@ -15,6 +15,7 @@ pub(crate) use cargo_toml::Manifest;
 pub(crate) use chrono::{DateTime, NaiveDateTime, Utc};
 pub(crate) use fehler::{throw, throws};
 pub(crate) use git2::{Commit, Repository};
+pub(crate) use log::info;
 pub(crate) use regex::Regex;
 pub(crate) use serde::{Deserialize, Serialize};
 pub(crate) use structopt::StructOpt;
@@ -23,12 +24,15 @@ pub(crate) use strum_macros::{EnumVariantNames, IntoStaticStr};
 pub(crate) use url::Url;
 
 // traits
-pub(crate) use crate::{command_ext::CommandExt, exit_status_ext::ExitStatusExt, row::Row};
+pub(crate) use crate::{
+  command_ext::CommandExt, exit_status_ext::ExitStatusExt, row::Row, slug::Slug,
+  template_ext::TemplateExt,
+};
 
 // structs and enums
 pub(crate) use crate::{
   bin::Bin, changelog::Changelog, config::Config, entry::Entry, example::Example,
   introduction::Introduction, kind::Kind, metadata::Metadata, opt::Opt, package::Package,
-  project::Project, readme::Readme, release::Release, subcommand::Subcommand, summary::Summary,
-  table::Table,
+  project::Project, readme::Readme, reference::Reference, reference_section::ReferenceSection,
+  release::Release, subcommand::Subcommand, summary::Summary, table::Table,
 };

bin/gen/src/config.rs

@@ -2,11 +2,12 @@ use crate::common::*;
 
 const PATH: &str = "bin/gen/config.yaml";
 
-#[derive(Deserialize)]
+#[derive(Debug, Deserialize)]
 pub(crate) struct Config {
   pub(crate) changelog: BTreeMap<String, Metadata>,
   pub(crate) examples: Vec<Example>,
   pub(crate) packages: Vec<Package>,
+  pub(crate) references: Vec<ReferenceSection>,
 }
 
 impl Config {

bin/gen/src/example.rs

@@ -1,6 +1,6 @@
 use crate::common::*;
 
-#[derive(Deserialize, Clone)]
+#[derive(Deserialize, Debug, Clone)]
 pub(crate) struct Example {
   pub(crate) command: String,
   #[serde(default)]

bin/gen/src/main.rs

@@ -18,11 +18,15 @@ mod opt;
 mod package;
 mod project;
 mod readme;
+mod reference;
+mod reference_section;
 mod release;
 mod row;
+mod slug;
 mod subcommand;
 mod summary;
 mod table;
+mod template_ext;
 
 #[throws]
 fn main() {

bin/gen/src/metadata.rs

@@ -1,6 +1,6 @@
 use crate::common::*;
 
-#[derive(Deserialize, Serialize, Clone)]
+#[derive(Deserialize, Debug, Serialize, Clone)]
 pub(crate) struct Metadata {
   #[serde(rename = "type")]
   pub(crate) kind: Kind,

bin/gen/src/opt.rs

@@ -20,11 +20,29 @@ pub(crate) enum Opt {
   Man,
 }
 
+#[throws]
+fn blank(path: impl AsRef<Path>, title: &str) {
+  let path = path.as_ref();
+
+  info!("Writing blank page to `{}`…", path.display());
+
+  let text = format!(
+    "
+  # {}
+
+  This page intentionally left blank.
+  ",
+    title
+  );
+
+  fs::write(path, text)?;
+}
+
 #[throws]
 fn clean_dir(dir: impl AsRef<Path>) {
   let dir = dir.as_ref();
 
-  eprintln!("Cleaning `{}`…", dir.display());
+  info!("Cleaning `{}`…", dir.display());
 
   if dir.is_dir() {
     fs::remove_dir_all(dir)?;
@@ -62,7 +80,7 @@ impl Opt {
 
   #[throws]
   pub(crate) fn changelog(project: &Project) {
-    eprintln!("Generating changelog…");
+    info!("Generating changelog…");
     let changelog = Changelog::new(&project)?;
 
     let dst = project.root.join("CHANGELOG.md");
@@ -72,7 +90,7 @@ impl Opt {
 
   #[throws]
   pub(crate) fn completion_scripts(project: &Project) {
-    eprintln!("Generating completion scripts…");
+    info!("Generating completion scripts…");
     let completions = project.root.join("completions");
 
     clean_dir(&completions)?;
@@ -92,20 +110,24 @@ impl Opt {
 
   #[throws]
   pub(crate) fn readme(project: &Project) {
-    eprintln!("Generating readme…");
+    info!("Generating readme…");
     let template = project.root.join("bin/gen/templates/README.md");
 
     let readme = Readme::load(&project.config, &template)?;
 
-    let mut text = readme.render()?;
-    text.push('\n');
+    let text = readme.render_newline()?;
 
     fs::write(project.root.join("README.md"), text)?;
   }
 
   #[throws]
   pub(crate) fn book(project: &Project) {
-    eprintln!("Generating book…");
+    info!("Generating book…");
+
+    blank(project.root.join("book/src/commands.md"), "Commands")?;
+    blank(project.root.join("book/src/bittorrent.md"), "BitTorrent")?;
+    blank(project.root.join("book/src/references.md"), "References")?;
+
     let commands = project.root.join("book/src/commands/");
 
     clean_dir(&commands)?;
@@ -118,24 +140,33 @@ impl Opt {
       fs::write(dst, page)?;
     }
 
-    let summary = Summary::new(&project.bin);
+    let references = project.root.join("book/src/references/");
+    clean_dir(&references)?;
 
-    let mut text = summary.render()?;
-    text.push('\n');
+    for section in &project.config.references {
+      let text = section.render_newline()?;
+
+      let path = project.root.join("book/src").join(section.path());
+
+      fs::write(path, text)?;
+    }
+
+    let summary = Summary::new(project);
+
+    let text = summary.render_newline()?;
 
     fs::write(project.root.join("book/src/SUMMARY.md"), text)?;
 
     let introduction = Introduction::new(&project.config);
 
-    let mut text = introduction.render()?;
-    text.push('\n');
+    let text = introduction.render_newline()?;
 
     fs::write(project.root.join("book/src/introduction.md"), text)?;
   }
 
   #[throws]
   pub(crate) fn man(project: &Project) {
-    eprintln!("Generating man pages…");
+    info!("Generating man pages…");
     let mans = project.root.join("man");
 
     clean_dir(&mans)?;
@@ -145,7 +176,7 @@ impl Opt {
 
       let dst = mans.join(format!("{}.1", subcommand.slug()));
 
-      eprintln!("Writing man page to `{}`", dst.display());
+      info!("Writing man page to `{}`", dst.display());
 
       fs::write(dst, man)?;
     }

bin/gen/src/package.rs

@@ -1,6 +1,6 @@
 use crate::common::*;
 
-#[derive(Deserialize, Clone)]
+#[derive(Deserialize, Debug, Clone)]
 #[serde(rename_all = "kebab-case")]
 pub(crate) struct Package {
   operating_system: String,

bin/gen/src/reference.rs

@@ -0,0 +1,8 @@
+use crate::common::*;
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct Reference {
+  pub(crate) url: Url,
+  pub(crate) title: Option<String>,
+  pub(crate) description: String,
+}

bin/gen/src/reference_section.rs

@@ -0,0 +1,14 @@
+use crate::common::*;
+
+#[derive(Debug, Deserialize, Template)]
+#[template(path = "references.md")]
+pub(crate) struct ReferenceSection {
+  pub(crate) title: String,
+  pub(crate) entries: Vec<Reference>,
+}
+
+impl ReferenceSection {
+  pub(crate) fn path(&self) -> String {
+    format!("./references/{}.md", self.title.slug())
+  }
+}

bin/gen/src/slug.rs

@@ -0,0 +1,9 @@
+pub(crate) trait Slug {
+  fn slug(&self) -> String;
+}
+
+impl Slug for str {
+  fn slug(&self) -> String {
+    self.replace(' ', "-").to_lowercase()
+  }
+}

bin/gen/src/subcommand.rs

@@ -38,7 +38,7 @@ impl Subcommand {
 
   #[throws]
   fn help(&self) -> String {
-    eprintln!("Getting help for `{}`", self.command_line());
+    info!("Getting help for `{}`", self.command_line());
 
     Command::new(&self.bin)
       .args(self.command.as_slice())
@@ -51,7 +51,7 @@ impl Subcommand {
   pub(crate) fn man(&self) -> String {
     let command_line = self.command_line();
 
-    eprintln!("Generating man page for `{}`", command_line);
+    info!("Generating man page for `{}`", command_line);
 
     let name = command_line.replace(" ", "\\ ");
 
@@ -85,7 +85,7 @@ impl Subcommand {
       .unwrap()
       .to_owned();
 
-    eprintln!("Running help2man for `{}`", command_line);
+    info!("Running help2man for `{}`", command_line);
 
     let mut command = self.bin.as_os_str().to_owned();
     for arg in &self.command {

bin/gen/src/summary.rs

@@ -4,26 +4,58 @@ use crate::common::*;
 #[template(path = "SUMMARY.md")]
 pub(crate) struct Summary {
   pub(crate) commands: String,
+  pub(crate) references: String,
 }
 
 impl Summary {
-  pub(crate) fn new(bin: &Bin) -> Summary {
-    let mut lines = Vec::new();
+  pub(crate) fn new(project: &Project) -> Summary {
+    let mut commands = Index::new("Commands", "./commands.md");
 
-    lines.push("- [Commands](./commands.md)".to_string());
+    for subcommand in &project.bin.subcommands {
+      commands.entry(
+        &format!("`{}`", subcommand.command_line()),
+        &format!("./commands/{}.md", subcommand.slug()),
+      );
+    }
 
-    for subcommand in &bin.subcommands {
-      let slug = subcommand.slug();
+    let mut references = Index::new("References", "./references.md");
 
-      lines.push(format!(
-        "  - [`{}`](./commands/{}.md)",
-        subcommand.command_line(),
-        slug
-      ))
+    for section in &project.config.references {
+      references.entry(&section.title, &section.path());
     }
 
     Summary {
-      commands: lines.join("\n"),
+      commands: commands.text(),
+      references: references.text(),
     }
   }
 }
+
+struct Index {
+  title: String,
+  entries: Vec<String>,
+}
+
+impl Index {
+  fn new(title: &str, path: &str) -> Self {
+    Self {
+      title: format!("- [{}]({})", title, path),
+      entries: Vec::new(),
+    }
+  }
+
+  fn entry(&mut self, title: &str, path: &str) {
+    self.entries.push(format!("  - [{}]({})", title, path));
+  }
+
+  fn text(self) -> String {
+    let mut text = self.title;
+
+    for entry in self.entries {
+      text.push('\n');
+      text.push_str(&entry);
+    }
+
+    text
+  }
+}

bin/gen/src/template_ext.rs

@@ -0,0 +1,15 @@
+use crate::common::*;
+
+pub(crate) trait TemplateExt {
+  #[throws]
+  fn render_newline(&self) -> String;
+}
+
+impl<T: Template> TemplateExt for T {
+  #[throws]
+  fn render_newline(&self) -> String {
+    let mut text = self.render()?.trim().to_owned();
+    text.push('\n');
+    text
+  }
+}

bin/gen/templates/SUMMARY.md

@@ -8,9 +8,7 @@ Summary
 - [Bittorrent](./bittorrent.md)
   - [Distributing Large Data Sets](./bittorrent/distributing-large-data-sets.md)
   - [BEP Support](./bittorrent/bep-support.md)
-  - [Alternatives & Prior Art](./bittorrent/prior-art.md)
+  - [Metainfo Utilities](./bittorrent/metainfo-utilities.md)
   - [UDP Tracker Protocol](./bittorrent/udp-tracker-protocol.md)
-  - [References](./bittorrent/references.md)
 
-- [Metadata](./metadata.md)
-  - [Prior Art](./metadata/prior-art.md)
+{{references}}

bin/gen/templates/references.md

@@ -0,0 +1,6 @@
+# {{title}}
+
+{% for entry in entries -%}
+- [{{entry.title.clone().unwrap_or(entry.url.to_string())}}]({{entry.url}}) — {{entry.description}}
+
+{% endfor -%}

book/src/SUMMARY.md

@@ -17,9 +17,10 @@ Summary
 - [Bittorrent](./bittorrent.md)
   - [Distributing Large Data Sets](./bittorrent/distributing-large-data-sets.md)
   - [BEP Support](./bittorrent/bep-support.md)
-  - [Alternatives & Prior Art](./bittorrent/prior-art.md)
+  - [Metainfo Utilities](./bittorrent/metainfo-utilities.md)
   - [UDP Tracker Protocol](./bittorrent/udp-tracker-protocol.md)
-  - [References](./bittorrent/references.md)
 
-- [Metadata](./metadata.md)
-  - [Prior Art](./metadata/prior-art.md)
+- [References](./references.md)
+  - [BitTorrent](./references/bittorrent.md)
+  - [Metadata](./references/metadata.md)
+  - [Cryptography](./references/cryptography.md)

book/src/bittorrent.md

@@ -1,4 +1,5 @@
-Bittorrent
-==========
 
-This page intentionally left blank.
+  # BitTorrent
+
+  This page intentionally left blank.
+  

book/src/bittorrent/metainfo-utilities.md

@@ -0,0 +1,21 @@
+Metainfo Utilities
+==================
+
+| 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.                                                                          |
+| [buildtorrent](http://manpages.ubuntu.com/manpages/bionic/man1/buildtorrent.1.html) | CLI                     | C          | Torrent file creator packaged for Ubuntu and Debian                                                                                       |
+| [maketorrent](https://github.com/fuchsi/maketorrent)                                | CLI                     | Rust       | Torrent file creator.                                                                                                                     |

book/src/bittorrent/prior-art.md

@@ -1,21 +1 @@
-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.                                                                          |
-| [buildtorrent](http://manpages.ubuntu.com/manpages/bionic/man1/buildtorrent.1.html) | CLI                     | C          | Torrent file creator packaged for Ubuntu and Debian                                                                                       |
-| [maketorrent](https://github.com/fuchsi/maketorrent)                                | CLI                     | Rust       | Torrent file creator.                                                                                                                     |
+# Alternatives & Prior Art

book/src/commands.md

@@ -1,4 +1,5 @@
-Commands
-========
 
-This page intentionally left blank.
+  # Commands
+
+  This page intentionally left blank.
+  

book/src/metadata.md

@@ -1,4 +1 @@
-Metadata
-==========
-
-This page intentionally left blank.
+# Metadata

book/src/metadata/prior-art.md

@@ -1,4 +1 @@
-Prior Art
-=========
-
-- [Media RSS Specification](http://www.rssboard.org/media-rss): _Media RSS is a new RSS module that supplements the <enclosure> capabilities of RSS 2.0. RSS enclosures are already being used to syndicate audio files and images. Media RSS extends enclosures to handle other media types, such as short films or TV, as well as provide additional metadata with the media. Media RSS enables content publishers and bloggers to syndicate multimedia content such as TV and video clips, movies, images and audio._
+# Prior Art

book/src/references.md

@@ -0,0 +1,5 @@
+
+  # References
+
+  This page intentionally left blank.
+  

book/src/references/bittorrent.md

@@ -0,0 +1,13 @@
+# BitTorrent
+
+- [https://github.com/bittorrent/bittorrent.org](https://github.com/bittorrent/bittorrent.org) — GitHub repository hosting protocol development discussion and contents of bittorrent.org.
+
+- [https://www.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](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)](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](https://github.com/internetarchive/dweb-transport) — Github repository hosting The Internet Archive's distributed web and BitTorrent-related software.
+
+- [https://libtorrent.org/udp_tracker_protocol.html](https://libtorrent.org/udp_tracker_protocol.html) — UDP tracker protocol description.

book/src/references/cryptography.md

@@ -0,0 +1,11 @@
+# Cryptography
+
+- [https://ssbc.github.io/scuttlebutt-protocol-guide/](https://ssbc.github.io/scuttlebutt-protocol-guide/) — Secure Scuttlebutt Protocol guide
+
+- [https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md) — Lightning Network Encrypted and Authenticated Transport
+
+- [http://noiseprotocol.org/noise.html](http://noiseprotocol.org/noise.html) — Noise Protocol
+
+- [https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js](https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js) — Handshake P2P Encryption Protocol
+
+- [https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md](https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md) — Grin Slate Serialization

book/src/references/metadata.md

@@ -0,0 +1,3 @@
+# Metadata
+
+- [Media RSS Specification](http://www.rssboard.org/media-rss) — _Media RSS is a new RSS module that supplements the <enclosure> capabilities of RSS 2.0. RSS enclosures are already being used to syndicate audio files and images. Media RSS extends enclosures to handle other media types, such as short films or TV, as well as provide additional metadata with the media. Media RSS enables content publishers and bloggers to syndicate multimedia content such as TV and video clips, movies, images and audio._