From 21ef0fd46020c3ae2ba610f8241d899209e240e1 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 6 Jul 2022 21:32:12 -0500 Subject: Update documentation --- README.md | 124 ++++++++++++++++++++++++++++++++++++++------------------------ licensor | 18 ++++++++- 2 files changed, 93 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index e48d546..0e71ae5 100644 --- a/README.md +++ b/README.md @@ -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) ". + -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 diff --git a/licensor b/licensor index 3458e7d..88fcee4 100755 --- a/licensor +++ b/licensor @@ -12,8 +12,9 @@ LICENSOR_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/licensor" usage() { cat < ". + -w WIDTH Fold the output to WIDTH characters. + Default: $__width. -o FILE Output the fetched license to FILE. Default: \$PWD/$LICENSOR_OUTPUT_FILE. -- cgit 1.4.1-21-gabe81