Create FAQ

Add an FAQ section to the book. Include information about how to use
imdl with `fzf --preview`.

type: documentation
fixes:
- https://github.com/casey/intermodal/issues/397

CHANGELOG.md

@@ -4,7 +4,8 @@ Changelog
 
 UNRELEASED - 2020-04-20
 -----------------------
-- :sparkles: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Add `--terminal` override terminal autodetection - Fixes [#398](https://github.com/casey/intermodal/issues/398) - _Casey Rodarmor <casey@rodarmor.com>_
+- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Create FAQ - Fixes [#397](https://github.com/casey/intermodal/issues/397) - _Casey Rodarmor <casey@rodarmor.com>_
+- :sparkles: [`65597c98510b`](https://github.com/casey/intermodal/commit/65597c98510b0536247c58a4cead559d3b3817be) Add `--terminal` override terminal autodetection - Fixes [#398](https://github.com/casey/intermodal/issues/398) - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`70dbe93c6ab0`](https://github.com/casey/intermodal/commit/70dbe93c6ab01408dfc42e1b75664de13de16a51) Note install script only works on Linux and MacOS - Fixes [#371](https://github.com/casey/intermodal/issues/371) - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`b67a2f1885c9`](https://github.com/casey/intermodal/commit/b67a2f1885c9445c08411457809f8893ebfa2045) Fix 404.css link - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`87687f4decbb`](https://github.com/casey/intermodal/commit/87687f4decbbd216b32ea3c9001122c56d5a93fc) Add custom 404 page to site - _Casey Rodarmor <casey@rodarmor.com>_

bin/gen/config.yaml

@@ -121,3 +121,17 @@ references:
 
     - url: https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md
       description: 'Grin Slate Serialization'
+
+faq:
+- title: Can intermodal be used to preview torrents with `fzf`?
+  anchor: fzf-preview
+  text: |-
+    Yes! [@mustaqimM](https://github.com/mustaqimM) came up with the following:
+
+        fzf --preview='imdl --color always --terminal torrent show --input {}
+
+    _Note the use of `--color always` and `--terminal` to force colored, human readable output._
+
+    This can be used to, for example, preview the torrents in a directory:
+
+        find . -name '*.torrent' | fzf --preview='imdl -c always -t torrent show -i {}'

bin/gen/src/common.rs

@@ -31,8 +31,9 @@ pub(crate) use crate::{
 
 // 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, reference::Reference, reference_section::ReferenceSection,
-  release::Release, subcommand::Subcommand, summary::Summary, table::Table,
+  bin::Bin, changelog::Changelog, config::Config, entry::Entry, example::Example, faq::Faq,
+  faq_entry::FaqEntry, introduction::Introduction, kind::Kind, metadata::Metadata, opt::Opt,
+  package::Package, project::Project, readme::Readme, reference::Reference,
+  reference_section::ReferenceSection, release::Release, subcommand::Subcommand, summary::Summary,
+  table::Table,
 };

bin/gen/src/config.rs

@@ -8,6 +8,7 @@ pub(crate) struct Config {
   pub(crate) examples: Vec<Example>,
   pub(crate) packages: Vec<Package>,
   pub(crate) references: Vec<ReferenceSection>,
+  pub(crate) faq: Vec<FaqEntry>,
 }
 
 impl Config {

bin/gen/src/faq.rs

@@ -0,0 +1,15 @@
+use crate::common::*;
+
+#[derive(Template)]
+#[template(path = "faq.md")]
+pub(crate) struct Faq {
+  pub(crate) entries: Vec<FaqEntry>,
+}
+
+impl Faq {
+  pub(crate) fn new(entries: &[FaqEntry]) -> Self {
+    Self {
+      entries: entries.to_vec(),
+    }
+  }
+}

bin/gen/src/faq_entry.rs

@@ -0,0 +1,8 @@
+use crate::common::*;
+
+#[derive(Clone, Debug, Deserialize)]
+pub(crate) struct FaqEntry {
+  pub(crate) title: String,
+  pub(crate) text: String,
+  pub(crate) anchor: String,
+}

bin/gen/src/main.rs

@@ -11,6 +11,8 @@ mod config;
 mod entry;
 mod example;
 mod exit_status_ext;
+mod faq;
+mod faq_entry;
 mod introduction;
 mod kind;
 mod metadata;

bin/gen/src/opt.rs

@@ -151,6 +151,10 @@ impl Opt {
       fs::write(path, text)?;
     }
 
+    let faq = Faq::new(&project.config.faq);
+
+    fs::write(project.root.join("book/src/faq.md"), faq.render_newline()?)?;
+
     let summary = Summary::new(project);
 
     let text = summary.render_newline()?;

bin/gen/templates/SUMMARY.md

@@ -3,6 +3,8 @@ Summary
 
 [Intermodal](./introduction.md)
 
+- [FAQ](./faq.md)
+
 {{commands}}
 
 - [Bittorrent](./bittorrent.md)

bin/gen/templates/faq.md

@@ -0,0 +1,14 @@
+FAQ
+===
+
+{% for entry in entries %}
+- [{{entry.title}}](#{{entry.anchor}})
+{% endfor %}
+
+{% for entry in entries %}
+<h2 name="{{entry.anchor}}">
+{{entry.title}}
+</h2>
+
+{{entry.text}}
+{% endfor %}

book/src/SUMMARY.md

@@ -3,6 +3,8 @@ Summary
 
 [Intermodal](./introduction.md)
 
+- [FAQ](./faq.md)
+
 - [Commands](./commands.md)
   - [`imdl`](./commands/imdl.md)
   - [`imdl completions`](./commands/imdl-completions.md)

book/src/faq.md

@@ -0,0 +1,21 @@
+FAQ
+===
+
+
+- [Can intermodal be used to preview torrents with `fzf`?](#fzf-preview)
+
+
+
+<h2 name="fzf-preview">
+Can intermodal be used to preview torrents with `fzf`?
+</h2>
+
+Yes! [@mustaqimM](https://github.com/mustaqimM) came up with the following:
+
+    fzf --preview='imdl --color always --terminal torrent show --input {}
+
+_Note the use of `--color always` and `--terminal` to force colored, human readable output._
+
+This can be used to, for example, preview the torrents in a directory:
+
+    find . -name '*.torrent' | fzf --preview='imdl -c always -t torrent show -i {}'