DOC: Readme and website improvements

kernc · kernc · commit 8a4dcfe461af · 2024-10-29T00:02:23.000+01:00
diff --git a/.github/scripts/aspell-ignorewords.txt b/.github/scripts/aspell-ignorewords.txt
@@ -80,3 +80,7 @@ vqwg
 worktree
 zsh
 vL
+FAQPage
+acceptedAnswer
+mainEntity
+typeof
diff --git a/.github/scripts/build-website.sh b/.github/scripts/build-website.sh
@@ -4,19 +4,20 @@ mkdir -p output
 cp icon.svg output
 
 preamble='<!doctype html>
-<html lang=en itemscope itemtype="https://schema.org/SoftwareApplication">
+<html lang=en vocab="https://schema.org/" typeof="SoftwareApplication">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Myba - git-based file backup with encryption</title>
 <link rel="logo icon" href="icon.svg">
 <meta name="theme-color" content="#333">
-<meta itemprop="applicationCategory" content="BusinessApplication"><meta itemprop="applicationCategory" content="DeveloperApplication"><meta itemprop="applicationCategory" content="SecurityApplication"><meta itemprop="applicationCategory" content="UtilitiesApplication">
-<meta itemprop="operatingSystem" content="Linux"><meta itemprop="operatingSystem" content="macOS"><meta itemprop="operatingSystem" content="Windows">
-<meta itemprop="isAccessibleForFree" content="true">
-<meta itemprop="license" content="https://www.gnu.org/licenses/agpl-3.0.txt">
-<meta itemprop="sameAs" content="https://github.com/kernc/myba/">
-<meta itemprop="url" content="/">
+<meta property="name" content="myba">
+<meta property="applicationCategory" content="BusinessApplication"><meta property="applicationCategory" content="DeveloperApplication"><meta property="applicationCategory" content="SecurityApplication"><meta property="applicationCategory" content="UtilitiesApplication">
+<meta property="operatingSystem" content="Linux"><meta property="operatingSystem" content="macOS"><meta property="operatingSystem" content="Windows">
+<meta property="isAccessibleForFree" content="true">
+<link property="license" href="https://www.gnu.org/licenses/agpl-3.0.txt">
+<link property="sameAs" href="https://github.com/kernc/myba/">
+<meta property="url" content="./">
 <script async src="https://www.googletagmanager.com/gtag/js?id=G-JT9W3RXCJD"></script>
 <script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag("js",new Date());gtag("config","G-JT9W3RXCJD");</script>
 <style>
@@ -30,26 +31,27 @@ h1 img {vertical-align: middle; margin: 0 1em 1em 0;}
 h1 {line-height: 1.3em;}
 a:link {color:navy}
 a:hover {color:blue !important}
-a:visited {color:darkmagenta}
+a:visited {color:#230}
 summary {width:fit-content; border:2px solid silver; cursor:pointer; padding:.2em .6em; margin:.3em 0; font-weight:bold}
 details[open] summary {border:2px solid black;}
 </style>
 <meta property="og:title" content="Myba - git-based file backup with encryption">
 <meta property="og:type" content="website">
 <meta property="og:url" content="https://kernc.github.io/myba/">
 <meta property="og:image" content="https://kernc.github.io/myba/icon.svg">
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.10.0/highlight.min.js" integrity="sha512-6yoqbrcLAHDWAdQmiRlHG4+m0g/CT/V9AGyxabG8j7Jk8j3r3K6due7oqpiRMZqcYe9WM2gPcaNNxnl2ux+3tA==" crossorigin></script>
+<script async src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.10.0/highlight.min.js" integrity="sha512-6yoqbrcLAHDWAdQmiRlHG4+m0g/CT/V9AGyxabG8j7Jk8j3r3K6due7oqpiRMZqcYe9WM2gPcaNNxnl2ux+3tA==" crossorigin></script>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.10.0/styles/github-dark.min.css" integrity="sha512-rO+olRTkcf304DQBxSWxln8JXCzTHlKnIdnMUwYvQa9/Jd4cQaNkItIUj6Z4nvW1dqK0SKXLbn9h4KwZTNtAyw==" crossorigin>
 </head>
 <body><main><article>
 '
 postamble='</article></main>
-<script>hljs.highlightAll();</script>
+<div property="aggregateRating" typeof="AggregateRating"><meta property="reviewCount" content="1"><meta property="ratingValue" content="5"></div>
+<div property="offers" typeof="Offer"><meta property="price" content="0"><meta property="priceCurrency" content="BTC"></div>
+<script>window.addEventListener("load", () => hljs.highlightAll());</script>
 <script>[...document.links].forEach(a => { if (a.hostname !== location.hostname) a.target = "_blank"; })</script>
 </body></html>'
 
 ext_config_file="$(dirname "$0")/markdown-ext-config.json"
-
 {
     echo "$preamble"
     python -m markdown -v -o html -x extra -x toc -c "$ext_config_file" README.full.md
diff --git a/README.full.md b/README.full.md
@@ -1,15 +1,16 @@
 <img src="icon.svg" width="64" alt/>  Myba — git-based backup utility with encryption
 =====
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/kernc/myba/ci.yml?branch=master&style=for-the-badge)](https://github.com/kernc/myba/actions)
-[![Source lines of code](https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/kernc/myba/badge?filter=myba.sh$&style=for-the-badge&logo=github&color=skyblue&label=SLOC)](https://github.com/kernc/myba)
-[![Script size](https://img.shields.io/github/size/kernc/myba/myba.sh?style=for-the-badge&logo=github&color=skyblue)](https://github.com/kernc/myba)
+[![Build status](https://img.shields.io/github/actions/workflow/status/kernc/myba/ci.yml?branch=master&style=for-the-badge)](https://github.com/kernc/myba/actions)
+[![Language: shell / Bash](https://img.shields.io/badge/lang-Shell-skyblue?style=for-the-badge)](https://github.com/kernc/myba)
+[![Source lines of code](https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/kernc/myba/badge?filter=myba.sh$&style=for-the-badge&color=skyblue&label=SLOC)](https://github.com/kernc/myba)
+[![Script size](https://img.shields.io/github/size/kernc/myba/myba.sh?style=for-the-badge&color=skyblue)](https://github.com/kernc/myba)
 [![Issues](https://img.shields.io/github/issues/kernc/myba?style=for-the-badge)](#)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink&style=for-the-badge)](https://github.com/sponsors/kernc)
+[![Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink&style=for-the-badge)](https://github.com/sponsors/kernc)
 
 [TOC]
 
-**Myba** (pronounced: mỹba) **is an
+**_Myba_** (pronounced: [_mỹba_](https://www.google.com/search?q=myba)) **is an
 open-source, secure, distributed, version-controlled, encrypted
 file backup software based on `git`**,
 for **Linux, MacOS, BSDs**, and possibly even **Windows/WSL**.
@@ -78,7 +79,7 @@ that **large binaries don't change too often**.
 fully **encrypted backups** that are really **easily replicated and synced to the cloud**.
 
 <script src="https://ssl.gstatic.com/trends_nrtr/3826_RC01/embed_loader.js"></script>
-<script>var now=(new Date()).toISOString().split('T')[0]; window.trends.embed.renderExploreWidget("TIMESERIES", {"comparisonItem":[{"keyword":"/m/02mhh1","geo":"","time":"2004-01-01 "+now},{"keyword":"/m/05vqwg","geo":"","time":"2004-01-01 "+now},{"keyword":"/m/0ryppmg","geo":"","time":"2004-01-01 "+now}],"category":0,"property":""}, {"exploreQuery":"q=%2Fm%2F02mhh1,%2Fm%2F05vqwg,%2Fm%2F0ryppmg&date=all#TIMESERIES","guestPath":"https://trends.google.com:443/trends/embed/"})</script>
+<script>var now=(new Date()).toISOString().split('T')[0];window.trends.embed.renderExploreWidget("TIMESERIES", {"comparisonItem":[{"keyword":"/m/02mhh1","geo":"","time":"all"},{"keyword":"/m/05vqwg","geo":"","time":"all"},{"keyword":"/m/0ryppmg","geo":"","time":"all"},{"keyword":"myba","geo":"","time":"all"}],"category":0,"property":""}, {"exploreQuery":"date=all&q=%2Fm%2F02mhh1,%2Fm%2F05vqwg,%2Fm%2F0ryppmg,myba#TIMESERIES","guestPath":"https://trends.google.com:443/trends/embed/"});</script>
 
 
 ### Use-cases
@@ -99,7 +100,7 @@ To install everything on a Debian/Ubuntu-based system, run:
 # Install dependencies
 sudo apt install  gzip git git-lfs openssl gpg
 
-# Download and make available somewhere in path
+# Download and put somewhere on PATH
 curl -vL 'https://bit.ly/myba-backup' > ~/.local/bin/myba
 export PATH="$HOME/.local/bin:$PATH"
 
@@ -110,14 +111,14 @@ Note, only one of `openssl` _or_ `gpg` is needed, not both!
 It should be similar, if not nearly equivalent, to install on other platforms.
 Hopefully you will find most dependencies already satisfied.
 
-Please report back if you find / manage to get this working under anything but the above configuration and especially Windows/WSL!
+Please report back if you find / manage to get this working under everything but the above configuration and especially Windows/WSL!
 
 
 Usage
 -----
 You run the script with arguments according to the usage printout below.
 Myba heavily relies on `git` and thus **its command-line usage largely follows that of git convention**.
-Most subcommands pass obtained arguments and options (`"@"`) straight to matching `git` subcommands! 
+Most subcommands pass obtained arguments and options (`"$@"`) straight to matching `git` subcommands!
 ```text
 Usage: myba <subcommand> [options]
 Subcommands:
@@ -173,7 +174,7 @@ myba add Documents Photos Etc .dotfile
 PASSWORD='secret'  myba commit -m "my precious"
 myba remote add origin "/media/usb/backup"
 myba remote add github "git@github.com:user/my-backup.git"
-myba push  # Push to all configured remotes & free disk space
+VERBOSE=1 myba push  # Push to all configured remotes & free up disk space
 
 # Somewhere else, much, much later, avoiding catastrophe ...
 
@@ -186,21 +187,23 @@ See [_smoke-test.sh_](https://github.com/kernc/myba/blob/master/smoke-test.sh) f
 
 Contributing
 ------------
-The project is [hosted on github](https://github.com/kernc/myba/).
+The project is [hosted on GitHub](https://github.com/kernc/myba/).
 
 The script is considered _mostly_ feature-complete, but there remain
 bugs and design flaws to be discovered and ironed out, as well as any
 [TODOs and FIXMEs](https://github.com/search?q=repo%3Akernc%2Fmyba+%28todo+OR+fixme+OR+xxx%29&type=code)
 marked in the source.
 **All source code lines are open to discussion.**
-Especially appreciated are clear pointers to targets for simplification.
+Especially appreciated are targets for simplification.
 
 
 FAQ
 ---
+<div property="about" typeof="FAQPage">
 
-<details markdown="1">
-<summary>Is git a good tool for backups?</summary>
+<details markdown="1" property="mainEntity" typeof="Question">
+<summary property="name">Is git a good tool for backups?</summary>
+<div property="acceptedAnswer" typeof="Answer"><div property="text">
 
 Git/myba's inherently core features allow you to:
 
@@ -217,11 +220,12 @@ Git/myba's inherently core features allow you to:
 of people and organizations worldwide,
 with long and rigorous release / support cycles.
 
-</details>
-<details markdown="1">
-<summary>Git doesn't track file owner and access control / permissions ...</summary>
+</div></div></details>
+<details markdown="1" property="mainEntity" typeof="Question">
+<summary property="name">Git doesn't track file owner and access control / permissions ...?</summary>
+<div property="acceptedAnswer" typeof="Answer"><div property="text">
 
-True. Files commited by any user are restorable by any user with the right password.
+Correct. Files commited by any user are restorable by any user with the right password.
 In order to restore files with specific file permission bits set, **defer to
 [umask](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/umask.html)**,
 e.g.:
@@ -236,23 +240,27 @@ simply **write a small shell wrapper** that takes care of it.
 **Welcome to contrib** anything short to the respect
 you find widely-applicable and useful.
 
-</details>
-<details markdown="1">
-<summary>Git isn't optimized for continuously-changing databases and binary files ...</summary>
+</div></div></details>
+<details markdown="1" property="mainEntity" typeof="Question">
+<summary property="name">Is git optimized for continuously-changing databases and binary files?</summary>
+<div property="acceptedAnswer" typeof="Answer"><div property="text">
 
-That is correct. Git saves whole file snapshots and doesn't do any in-file or within-file
+It's not. Git saves whole file snapshots and doesn't do any in-file or within-file
 or across-file deduplication, so it's not well suited to automatic continuous backing up
 of databases that change often.
 
 However, while git repositories bloat when commiting large binary and media files,
 **_myba_ only ever uses sparse-checkout**, keeping overhead disk space use to a minimum.
 
-</details>
-<details markdown="1">
-<summary>How to influence what files / filetypes to ignore from backup?</summary>
+</div></div></details>
+<details markdown="1" property="mainEntity" typeof="Question">
+<summary property="name">How to configure what files / filetypes to ignore from backup?</summary>
+<div property="acceptedAnswer" typeof="Answer"><div property="text">
 
-You can edit `$PLAIN_REPO/info/exclude`, which is prepopulated with default common ignore patterns.
+You can edit `$PLAIN_REPO/info/exclude`, which is prepopulated with
+[default common ignore patterns](https://github.com/search?q=repo%3Akernc%2Fmyba+%22default_gitignore%3D%22&type=code).
 You can tweak various other git settings (like config, filters, hooks)
-by modifying files in `$PLAIN_REPO` and `$PLAIN_REPO/_encrypted/.git`.
+by modifying respective files in `$PLAIN_REPO` and (encrypted repo) `$PLAIN_REPO/_encrypted/.git`.
 
-</details>
+</div></div></details>
+</div>
diff --git a/README.md b/README.md
@@ -1,13 +1,14 @@
 <img src="icon.svg" width="64" alt/> Myba — git-based backup utility w/ encryption
 =====
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/kernc/myba/ci.yml?branch=master&style=for-the-badge)](https://github.com/kernc/myba/actions)
-[![Source lines of code](https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/kernc/myba/badge?filter=myba.sh$&style=for-the-badge&logo=github&color=skyblue&label=SLOC)](https://github.com/kernc/myba)
-[![Script size](https://img.shields.io/github/size/kernc/myba/myba.sh?style=for-the-badge&logo=github&color=skyblue)](https://github.com/kernc/myba)
+[![Build status](https://img.shields.io/github/actions/workflow/status/kernc/myba/ci.yml?branch=master&style=for-the-badge)](https://github.com/kernc/myba/actions)
+[![Language: shell / Bash](https://img.shields.io/badge/lang-Shell-skyblue?style=for-the-badge)](https://github.com/kernc/myba)
+[![Source lines of code](https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/kernc/myba/badge?filter=myba.sh$&style=for-the-badge&color=skyblue&label=SLOC)](https://github.com/kernc/myba)
+[![Script size](https://img.shields.io/github/size/kernc/myba/myba.sh?style=for-the-badge&color=skyblue)](https://github.com/kernc/myba)
 [![Issues](https://img.shields.io/github/issues/kernc/myba?style=for-the-badge)](#)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink&style=for-the-badge)](https://github.com/sponsors/kernc)
+[![Sponsors](https://img.shields.io/github/sponsors/kernc?color=pink&style=for-the-badge)](https://github.com/sponsors/kernc)
 
-**Myba** (pronounced: mỹba) **is an
+**_Myba_** (pronounced: _mỹba_) **is an
 open-source, secure, distributed, version-controlled, encrypted
 file backup software based on `git`**,
 for **Linux, MacOS, BSDs**, and possibly even **Windows/WSL**.
@@ -29,7 +30,9 @@ See [_smoke-test.sh_](https://github.com/kernc/myba/blob/master/smoke-test.sh) f
 
 Contributing
 ------------
-The script is considered _mostly_ feature-complete, but there remain bugs and design flaws to be discovered and ironed out,
-as well as any TODOs and FIXMEs marked in the source.
+The script is considered _mostly_ feature-complete, but there remain
+bugs and design flaws to be discovered and ironed out, as well as any
+[TODOs and FIXMEs](https://github.com/search?q=repo%3Akernc%2Fmyba+%28todo+OR+fixme+OR+xxx%29&type=code)
+marked in the source.
 **All source code lines are open to discussion.**
-Especially appreciated are clear pointers to targets for simplification.
+Especially appreciated are targets for simplification.
