about summary refs log tree commit diff stats
path: root/README.md
diff options
context:
space:
mode:
authorCase Duckworth2022-07-06 21:32:12 -0500
committerCase Duckworth2022-07-06 21:32:12 -0500
commit21ef0fd46020c3ae2ba610f8241d899209e240e1 (patch)
treeea035fe3c5efa3b420780785d5cd8eab7fa99c02 /README.md
parentUpdate COPYING (diff)
downloadlicensor-21ef0fd46020c3ae2ba610f8241d899209e240e1.tar.gz
licensor-21ef0fd46020c3ae2ba610f8241d899209e240e1.zip
Update documentation
Diffstat (limited to 'README.md')
-rw-r--r--README.md124
1 files changed, 77 insertions, 47 deletions
diff --git a/README.md b/README.md index e48d546..0e71ae5 100644 --- a/README.md +++ b/README.md
@@ -1,74 +1,104 @@
1# licenser: plop a license in there 1# licensor: plop a license in there
2 2
3Are you tired of copying and pasting licenses into your new projects? 3Are you tired of copying and pasting licenses into your new projects?
4Do you always forget what the dang github api thing is? 4Do you always forget what the dang github api thing is?
5Or I don't know, have some other reason why doing licenses is hard? 5Or I don't know, have some other reason why doing licenses is hard?
6 6
7Well now you don't have to worry! 7Well now you don't have to worry!
8Just run `licenser` in your new repo and BLAMMO! 8Just run `licensor` in your new repo and BLAMMO!
9Done. 9Done.
10 10
11## Usage 11## Usage
12 12
13literally taken from `licenser -h` 13literally taken from `licensor -h`:
14 14
15``` 15```
16licenser: plop a license in your project 16licensor: easily provide a license for a project
17 17USAGE: licensor [-h|-l|-L]
18usage: licenser [-h|-m|-M] 18licensor -s QUERY
19 licenser [-f] [-q] [-y YEAR] [-a AUTHOR] [-e EMAIL] 19licensor [FLAGS] [OPTIONS] [LICENSE]
20 [-l LANG] [-o FILE] [LICENSE] 20
21flags: 21FLAGS:
22 -h show this help and exit 22-h Display this help and exit.
23 -m list available licenses and exit 23-l List available licenses and exit.
24 -M list licenses, disregarding cached manifest 24-L List available licenses, disregarding cache.
25 -f overwrite existing license 25This flag will re-download the license repo.
26 -q quiet: don't log anything 26
27options: 27-f Overwrite existing license.
28 -y YEAR set copyright date(s) to YEAR. 28-q Be quiet (don't log anything).
29 default: $(date +%Y). 29-z Fold output to 70 characters (see -w).
30 this option accepts arbitrary input. 30-Z Disable folding of output.
31 -a AUTHOR set copyright holder(s) to AUTHOR. 31-p Include "optional" license content.
32 default: 32-P Don't include "optional" content.
33 - git config --get user.name 33
34 - getent password $USER 34OPTIONS:
35 - $USER 35-s QUERY Search for a license matching QUERY.
36 -e EMAIL set AUTHOR's email address to EMAIL. 36Only license titles are searched.
37 default: 37
38 - git config --get user.email 38-y YEARS Set copyright date(s) to YEARS.
39 - [blank] 39Default: $(date +%Y).
40 -l LANG set license language to LANG. 40-a AUTHORS Set copyright holder(s) to AUTHOR.
41 default: 'en' (subject to change) 41Default: use the first of
42 -o FILE set output file to FILE. 42- git config --get user.name
43 default: LICENSE in $PWD 43 - getent password $USER
44parameters: 44 - $USER
45 LICENSE which license to use. 45 -e EMAILS Set AUTHOR's EMAIL address.
46 default: $LICENSER_LICENSE, which 46 Default: $(git config --get user.email),
47 defaults to MIT. 47 or stay blank.
48 -c COPYRIGHT Set the entire COPYRIGHT string to print.
49 By default, it's built from the above information:
50 "Copyright (C) <year> <author> <email>".
51 -w WIDTH Fold the output to WIDTH characters.
52 Default: 70.
53 -o FILE Output the fetched license to FILE.
54 Default: $PWD/COPYING.
55
56PARAMETERS:
57 LICENSE The license to use.
58 Default: MIT.
48``` 59```
49 60
50## License source 61You can use an output file of `-` (i.e., `licensor -o-`) to print the license to
62stdout.
51 63
52As of v0.2, `licenser` gets its licenses from 64### Available licenses
53[another repo](https://git.sr.ht/~acdw/licenser-licenses),
54to streamline additions to available licenses.
55If you have spotty internet connection or want to use your own license source,
56you can change the environment variable `$LICENSER_SOURCE`.
57 65
58For v0.3, I want to add a configuration file to take care of these kinds of 66Licenses are pulled from [SPDX][]'s [git repository of licenses][spdx-git].
59configurations. 67This includes all of the more common licenses, and honestly, if you're wanting
68to do something weird is `licensor` the right project for you?
60 69
61## Contributing 70*That being said, adding the ability for arbitrary license "repositories" is
71probably for the best.*
72
73[SPDX]: https://spdx.org/licenses/
74[spdx-git]: https://github.com/spdx/license-list-data/
75
76### Templating
77
78SPDX uses a [particular templating format][spdx-template-format] that `licensor`
79can read and use. As of v1.0, only `beginOptional`/`endOptional` and
80`var;name="copyright"` fields are filled in; all others are stripped from output.
62 81
63Send me a request for another license or a pull-thingy 82## Configuring
64through [the mailing list](~acdw/licenser@lists.sr.ht). 83
84There are some environment variables you can set to change `licensor`'s default
85behavior:
86
87- `LICENSE_REPO_VERSION` : 3.17
88- `LICENSE_REPO_URL` : `https://github.com/spdx/license-list-data/archive/refs/tags/v$LICENSE_REPO_VERSION.tar.gz`
89- `LICENSE_REPO_PATH` : `license-list-data-$LICENSE_REPO_VERSION/template`
90- `LICENSOR_LICENSE` : MIT
91- `LICENSOR_OUTPUT_FILE` : COPYING
92
93## Contributing
65 94
66Or, look at the [roadmap](https://todo.sr.ht/~acdw/licenser). 95Send me an [email](mailto:acdw@acdw.net).
67 96
68## License 97## License
69 98
70MIT, baby. 99MIT, baby.
71 100
101See [COPYING](/licensor/COPYING) for details.
72 102
73## Author 103## Author
74 104