doc: add age(1) and age-keygen(1) man pages

Closes #131

Author: FiloSottile

.github/workflows/ronn.yml

@@ -0,0 +1,33 @@
+on:
+  push:
+    branches:
+      - '**'
+    paths:
+      - '**.ronn'
+name: Generate man pages
+jobs:
+  ronn:
+    runs-on: ubuntu-latest
+    name: Ronn
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Run ronn
+        uses: ./.github/workflows/ronn
+        id: ronn
+      - name: Undo email mangling
+        # rdiscount randomizes the output for no good reason, which causes
+        # changes to always get committed. Sigh.
+        # https://github.com/davidfstr/rdiscount/blob/6b1471ec3/ext/generate.c#L781-L795
+        run: |-
+          for f in doc/*.html; do
+            awk '/Filippo Valsorda/ { $0 = "<p>Filippo Valsorda <a href=\"mailto:[email protected]\" data-bare-link=\"true\">[email protected]</a></p>" } { print }' "$f" > "$f.tmp"
+            mv "$f.tmp" "$f"
+          done
+      - name: Commit and push if changed
+        run: |-
+          git config user.name "GitHub Actions"
+          git config user.email "[email protected]"
+          git add -A
+          git commit -m "doc: regenerate groff and html man pages" || exit 0
+          git push

.github/workflows/ronn/Dockerfile

@@ -0,0 +1,8 @@
+FROM ruby:3.0.1-buster
+
+RUN apt-get update && apt-get install -y groff
+RUN bundle config --global frozen 1
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+ENTRYPOINT ["bash", "-O", "globstar", "-c", \
+    "/usr/local/bundle/bin/ronn **/*.ronn"]

.github/workflows/ronn/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "ronn", "~> 0.7.3"

.github/workflows/ronn/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    hpricot (0.8.6)
+    mustache (1.1.1)
+    rdiscount (2.2.0.2)
+    ronn (0.7.3)
+      hpricot (>= 0.8.2)
+      mustache (>= 0.7.0)
+      rdiscount (>= 1.5.8)
+
+PLATFORMS
+  aarch64-linux
+  x86_64-linux
+
+DEPENDENCIES
+  ronn (~> 0.7.3)
+
+BUNDLED WITH
+   2.2.15

.github/workflows/ronn/action.yml

@@ -0,0 +1,4 @@
+name: Ronn
+runs:
+  using: docker
+  image: Dockerfile

HomebrewFormula/age.rb

@@ -16,5 +16,7 @@ def install
     mkdir bin
     system "go", "build", "-trimpath", "-o", bin, "-ldflags", "-X main.Version=v#{version}", "filippo.io/age/cmd/..."
     prefix.install_metafiles
+    man1.install "doc/age.1"
+    man1.install "doc/age-keygen.1"
   end
 end

age.go

@@ -35,6 +35,16 @@
 // encryption operations. If you need to tie into existing key management
 // infrastructure, you might want to consider implementing your own Recipient
 // and Identity.
+//
+// Backwards compatibility
+//
+// Files encrypted with a stable version (not alpha, beta, or release candidate)
+// of age, or with any v1.0.0 beta or release candidate, will decrypt with any
+// later versions of the v1 API. This might change in v2, in which case v1 will
+// be maintained with security fixes for compatibility with older files.
+//
+// If decrypting an older file poses a security risk, doing so might require an
+// explicit opt-in in the API.
 package age
 
 import (

cmd/age-keygen/keygen.go

@@ -27,7 +27,7 @@ Options:
     -o, --output OUTPUT       Write the result to the file at path OUTPUT.
     -y                        Convert an identity file to a recipients file.
 
-age-keygen generates a new standard X25519 key pair, and outputs it to
+age-keygen generates a new native X25519 key pair, and outputs it to
 standard output or to the OUTPUT file.
 
 If an OUTPUT file is specified, the public key is printed to standard error.

doc/age-keygen.1.ronn

@@ -0,0 +1,57 @@
+age-keygen(1) -- generate age(1) key pairs
+====================================================
+
+## SYNOPSIS
+
+`age-keygen` [`-o` <OUTPUT>]<br>
+`age-keygen` `-y` [`-o` <OUTPUT>] [<INPUT>]<br>
+
+## DESCRIPTION
+
+`age-keygen` generates a new native age(1) key pair, and outputs the identity to
+standard output or to the <OUTPUT> file. The output includes the public key and
+the current time as comments.
+
+If the output is not going to a terminal, `age-keygen` prints the public key to
+standard error.
+
+## OPTIONS
+
+* `-o`, `--output`=<OUTPUT>:
+    Write the identity to <OUTPUT> instead of standard output.
+    
+    If <OUTPUT> already exists, it is not overwritten.
+
+* `-y`:
+    Read an identity file from <INPUT> or from standard input and output the
+    corresponding recipient(s), one per line, with no comments.
+
+* `--version`:
+    Print the version and exit.
+
+## EXAMPLES
+
+Generate a new identity:
+
+    $ age-keygen
+    # created: 2021-01-02T15:30:45+01:00
+    # public key: age1lvyvwawkr0mcnnnncaghunadrqkmuf9e6507x9y920xxpp866cnql7dp2z
+    AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
+
+Write a new identity to `key.txt`:
+
+    $ age-keygen -o key.txt
+    Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+Convert an identity to a recipient:
+
+    $ age-keygen -y key.txt
+    age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+## SEE ALSO
+
+age(1)
+
+## AUTHORS
+
+Filippo Valsorda <[email protected]>