Update documentation

2 files changed, 93 insertions, 49 deletions

@@ -1,74 +1,104 @@
-# licenser: plop a license in there
+# licensor: plop a license in there
 
 Are you tired of copying and pasting licenses into your new projects?
 Do you always forget what the dang github api thing is?
 Or I don't know, have some other reason why doing licenses is hard?
 
 Well now you don't have to worry!
-Just run `licenser` in your new repo and BLAMMO!
+Just run `licensor` in your new repo and BLAMMO!
 Done.
 
 ## Usage
 
-literally taken from `licenser -h`
+literally taken from `licensor -h`:
 
 ```
-licenser: plop a license in your project
-
-usage:  licenser [-h|-m|-M]
-        licenser [-f] [-q] [-y YEAR] [-a AUTHOR] [-e EMAIL] 
-              [-l LANG] [-o FILE] [LICENSE]
-flags:
-        -h      show this help and exit
-        -m      list available licenses and exit
-        -M      list licenses, disregarding cached manifest
-        -f      overwrite existing license
-        -q      quiet: don't log anything
-options:
-        -y YEAR         set copyright date(s) to YEAR.
-                        default: $(date +%Y).
-                        this option accepts arbitrary input.
-        -a AUTHOR       set copyright holder(s) to AUTHOR.
-                        default:
-                                - git config --get user.name
-                                - getent password $USER
-                                - $USER
-        -e EMAIL        set AUTHOR's email address to EMAIL.
-                        default:
-                                - git config --get user.email
-                                - [blank]
-        -l LANG         set license language to LANG.
-                        default: 'en' (subject to change)
-        -o FILE         set output file to FILE.
-                        default: LICENSE in $PWD
-parameters:
-        LICENSE         which license to use.
-                        default: $LICENSER_LICENSE, which
-                        defaults to MIT.
+licensor: easily provide a license for a project
+USAGE:  licensor [-h|-l|-L]
+licensor -s QUERY
+licensor [FLAGS] [OPTIONS] [LICENSE]
+
+FLAGS:
+-h      Display this help and exit.
+-l      List available licenses and exit.
+-L      List available licenses, disregarding cache.
+This flag will re-download the license repo.
+
+-f      Overwrite existing license.
+-q      Be quiet (don't log anything).
+-z      Fold output to 70 characters (see -w).
+-Z      Disable folding of output.
+-p      Include "optional" license content.
+-P      Don't include "optional" content.
+
+OPTIONS:
+-s QUERY        Search for a license matching QUERY.
+Only license titles are searched.
+
+-y YEARS        Set copyright date(s) to YEARS.
+Default: $(date +%Y).
+-a AUTHORS      Set copyright holder(s) to AUTHOR.
+Default: use the first of
+- git config --get user.name
+                        - getent password $USER
+                        - $USER
+ -e EMAILS      Set AUTHOR's EMAIL address.
+                Default: $(git config --get user.email),
+                or stay blank.
+ -c COPYRIGHT   Set the entire COPYRIGHT string to print.
+                By default, it's built from the above information:
+                "Copyright (C) <year> <author> <email>".
+ -w WIDTH       Fold the output to WIDTH characters.
+                Default: 70.
+ -o FILE        Output the fetched license to FILE.
+                Default: $PWD/COPYING.
+
+PARAMETERS:
+ LICENSE        The license to use.
+                Default: MIT.
 ```
 
-## License source
+You can use an output file of `-` (i.e., `licensor -o-`) to print the license to
+stdout.
 
-As of v0.2, `licenser` gets its licenses from
-[another repo](https://git.sr.ht/~acdw/licenser-licenses),
-to streamline additions to available licenses.
-If you have spotty internet connection or want to use your own license source,
-you can change the environment variable `$LICENSER_SOURCE`.
+### Available licenses
 
-For v0.3, I want to add a configuration file to take care of these kinds of
-configurations.
+Licenses are pulled from [SPDX][]'s [git repository of licenses][spdx-git].
+This includes all of the more common licenses, and honestly, if you're wanting
+to do something weird is `licensor` the right project for you?
 
-## Contributing
+*That being said, adding the ability for arbitrary license "repositories" is
+probably for the best.*
+
+[SPDX]: https://spdx.org/licenses/
+[spdx-git]: https://github.com/spdx/license-list-data/
+
+### Templating
+
+SPDX uses a [particular templating format][spdx-template-format] that `licensor`
+can read and use.  As of v1.0, only `beginOptional`/`endOptional` and
+`var;name="copyright"` fields are filled in; all others are stripped from output.
 
-Send me a request for another license or a pull-thingy
-through [the mailing list](~acdw/licenser@lists.sr.ht).
+## Configuring
+
+There are some environment variables you can set to change `licensor`'s default
+behavior:
+
+- `LICENSE_REPO_VERSION` : 3.17
+- `LICENSE_REPO_URL` : `https://github.com/spdx/license-list-data/archive/refs/tags/v$LICENSE_REPO_VERSION.tar.gz`
+- `LICENSE_REPO_PATH` : `license-list-data-$LICENSE_REPO_VERSION/template`
+- `LICENSOR_LICENSE` : MIT
+- `LICENSOR_OUTPUT_FILE` : COPYING
+
+## Contributing
 
-Or, look at the [roadmap](https://todo.sr.ht/~acdw/licenser).
+Send me an [email](mailto:acdw@acdw.net).
 
 ## License
 
 MIT, baby.
 
+See [COPYING](/licensor/COPYING) for details.
 
 ## Author
 
@@ -12,8 +12,9 @@ LICENSOR_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/licensor"
 
 usage() {
         cat <<EOF
-$PRGN: drop a lil ol license in yr project
-USAGE:  $PRGN [-h|-m|-M]
+$PRGN: easily provide a license for a project
+USAGE:  $PRGN [-h|-l|-L]
+        $PRGN -s QUERY
         $PRGN [FLAGS] [OPTIONS] [LICENSE]
 
 FLAGS:
@@ -21,10 +22,18 @@ FLAGS:
  -l     List available licenses and exit.
  -L     List available licenses, disregarding cache.
         This flag will re-download the license repo.
+
  -f     Overwrite existing license.
  -q     Be quiet (don't log anything).
+ -z     Fold output to $__width characters (see -w).
+ -Z     Disable folding of output.
+ -p     Include "optional" license content.
+ -P     Don't include "optional" content.
 
 OPTIONS:
+ -s QUERY       Search for a license matching QUERY.
+                Only license titles are searched.
+
  -y YEARS       Set copyright date(s) to YEARS.
                 Default: \$(date +%Y).
  -a AUTHORS     Set copyright holder(s) to AUTHOR.
@@ -35,6 +44,11 @@ OPTIONS:
  -e EMAILS      Set AUTHOR's EMAIL address.
                 Default: \$(git config --get user.email),
                 or stay blank.
+ -c COPYRIGHT   Set the entire COPYRIGHT string to print.
+                By default, it's built from the above information:
+                "Copyright (C) <year> <author> <email>".
+ -w WIDTH       Fold the output to WIDTH characters.
+                Default: $__width.
  -o FILE        Output the fetched license to FILE.
                 Default: \$PWD/$LICENSOR_OUTPUT_FILE.