diff --git a/preview/rfc-vibe/0.1.1/LICENSE b/preview/rfc-vibe/0.1.1/LICENSE new file mode 100644 index 0000000..35d39a7 --- /dev/null +++ b/preview/rfc-vibe/0.1.1/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Stephen Waits + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/preview/rfc-vibe/0.1.1/README.md b/preview/rfc-vibe/0.1.1/README.md new file mode 100644 index 0000000..1555b06 --- /dev/null +++ b/preview/rfc-vibe/0.1.1/README.md @@ -0,0 +1,100 @@ +# `rfc-vibe` package + +Bring that RFC lingo to your everyday documents. + +A [Typst](https://typst.app/) package that makes it easy to use the exact +keywords, boilerplate, and definitions provided by BCP 14, RFC2119, and RFC8174. +See the end of this README for an example of the output. + +In the future, this package may include other RFC-related patterns which are +applicable to a wide variety of everyday documents. + +## Usage + +Import the package in your Typst document: + +```typst +#import "@preview/rfc-vibe:0.1.1": * +``` + +### Keywords + +Use the keywords according to these examples: + +```typst +#must // renders as: MUST +#must-not // renders as: MUST NOT +#required // renders as: REQUIRED +#shall // renders as: SHALL +#shall-not // renders as: SHALL NOT +#should // renders as: SHOULD +#should-not // renders as: SHOULD NOT +#recommended // renders as: RECOMMENDED +#not-recommended // renders as: NOT RECOMMENDED +#may // renders as: MAY +#optional // renders as: OPTIONAL +``` + +For the rare situation when you want the keywords included in quotation marks, +use the `-quoted` versions: + +```typst +#must-quoted // renders as: "MUST" +#must-not-quoted // renders as: "MUST NOT" +#required-quoted // renders as: "REQUIRED" +#shall-quoted // renders as: "SHALL" +#shall-not-quoted // renders as: "SHALL NOT" +#should-quoted // renders as: "SHOULD" +#should-not-quoted // renders as: "SHOULD NOT" +#recommended-quoted // renders as: "RECOMMENDED" +#not-recommended-quoted // renders as: "NOT RECOMMENDED" +#may-quoted // renders as: "MAY" +#optional-quoted // renders as: "OPTIONAL" +``` + +### Boilerplate + +According to RFC8174, _authors who follow these guidelines should incorporate a +specific phrase near the beginning of their document_. Include this boilerplate +text with: + +```typst +#rfc-keyword-boilerplate +``` + +This will render as: + +```text +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, +and only when, they appear in all capitals, as shown here. +``` + +### Definitions + +Although not required (and maybe discouraged), you can include definitions of +individual keywords in your document: + +```typst +#rfc-keyword-must-definition +#rfc-keyword-must-not-definition +#rfc-keyword-should-definition +#rfc-keyword-should-not-definition +#rfc-keyword-may-definition +``` + +Or include all keyword definitions at once with: + +```typst +#rfc-keyword-definitions +``` + +## Example Output + +![Example output](thumbnail.png) + +## License + +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file +for details. diff --git a/preview/rfc-vibe/0.1.1/examples/example.pdf b/preview/rfc-vibe/0.1.1/examples/example.pdf new file mode 100644 index 0000000..eade690 Binary files /dev/null and b/preview/rfc-vibe/0.1.1/examples/example.pdf differ diff --git a/preview/rfc-vibe/0.1.1/examples/example.typ b/preview/rfc-vibe/0.1.1/examples/example.typ new file mode 100644 index 0000000..bd39d01 --- /dev/null +++ b/preview/rfc-vibe/0.1.1/examples/example.typ @@ -0,0 +1,69 @@ +#import "@preview/rfc-vibe:0.1.1": * + +#set page(paper: "us-letter", margin: 0.75in) +#set par(justify: true) +#set text(size: 10pt) + += `rfc-vibe` package + +This package makes it easy to use the exact keywords, boilerplate, and +definitions provided by #bcp14, #rfc2119, and #rfc8174. + +== Keywords + +Use the keywords according to these examples. Note that the *`-quoted`* versions +are only for the unique situation when you want the keywords included in +quotation marks. This is not necessary in normal usage. + +#grid( + columns: (auto, 1fr, auto), + + table( + columns: 2, + [*`#must` *], [#must], + [*`#must-not` *], [#must-not], + [*`#required` *], [#required], + [*`#shall` *], [#shall], + [*`#shall-not` *], [#shall-not], + [*`#should` *], [#should], + [*`#should-not` *], [#should-not], + [*`#recommended` *], [#recommended], + [*`#not-recommended` *], [#not-recommended], + [*`#may` *], [#may], + [*`#optional` *], [#optional], + ), + [], + table( + columns: 2, + [*`#must-quoted` *], [#must-quoted], + [*`#must-not-quoted` *], [#must-not-quoted], + [*`#required-quoted` *], [#required-quoted], + [*`#shall-quoted` *], [#shall-quoted], + [*`#shall-not-quoted` *], [#shall-not-quoted], + [*`#should-quoted` *], [#should-quoted], + [*`#should-not-quoted` *], [#should-not-quoted], + [*`#recommended-quoted` *], [#recommended-quoted], + [*`#not-recommended-quoted` *], [#not-recommended-quoted], + [*`#may-quoted` *], [#may-quoted], + [*`#optional-quoted` *], [#optional-quoted], + ), +) + +== Boilerplate + +According to #rfc8174, "authors who follow these guidelines should incorporate +this phrase near the beginning of their document." Do that with *`#rfc-keyword-boilerplate`*: + +#pad(left: 1em, rfc-keyword-boilerplate) + +== Definitions + +Although not required (and maybe discouraged), you can include the definitions of the individual keywords in your document individually with +*`#rfc-keyword-must-definition`*, +*`#rfc-keyword-must-not-definition`*, +*`#rfc-keyword-should-definition`*, +*`#rfc-keyword-should-not-definition`*, or +*`#rfc-keyword-may-definition`*. + +Or, you can include dfinitions of all keywords with *`#rfc-keyword-definitions`*: +#pad(left: 1em, rfc-keyword-definitions) diff --git a/preview/rfc-vibe/0.1.1/lib.typ b/preview/rfc-vibe/0.1.1/lib.typ new file mode 100644 index 0000000..28f29d1 --- /dev/null +++ b/preview/rfc-vibe/0.1.1/lib.typ @@ -0,0 +1,119 @@ +// one function to set the display of an RFC word +#let __rfc-keyword(body) = emph(upper(body)) +#let __rfc-keyword-quoted(body) = emph(upper(["#body"])) + +// a function (macro-like) for each of the possible RFC words +#let must = __rfc-keyword("must") +#let must-quoted = __rfc-keyword-quoted("must") +#let must-not = __rfc-keyword("must not") +#let required = __rfc-keyword("required") +#let shall = __rfc-keyword("shall") +#let shall-not = __rfc-keyword("shall not") +#let should = __rfc-keyword("should") +#let should-not = __rfc-keyword("should not") +#let recommended = __rfc-keyword("recommended") +#let not-recommended = __rfc-keyword("not recommended") +#let may = __rfc-keyword("may") +#let optional = __rfc-keyword("optional") + +// quoted versions, so quotation marks get included in the emph() +#let must-quoted = __rfc-keyword-quoted("must") +#let must-not-quoted = __rfc-keyword-quoted("must not") +#let required-quoted = __rfc-keyword-quoted("required") +#let shall-quoted = __rfc-keyword-quoted("shall") +#let shall-not-quoted = __rfc-keyword-quoted("shall not") +#let should-quoted = __rfc-keyword-quoted("should") +#let should-not-quoted = __rfc-keyword-quoted("should not") +#let recommended-quoted = __rfc-keyword-quoted("recommended") +#let not-recommended-quoted = __rfc-keyword-quoted("not recommended") +#let may-quoted = __rfc-keyword-quoted("may") +#let optional-quoted = __rfc-keyword-quoted("optional") + +// links to the relevant BCP and RFCs +#let bcp14-name = "BCP 14" +#let bcp14-url = "https://www.rfc-editor.org/bcp/bcp14" +#let bcp14 = link(bcp14-url, bcp14-name) + +#let rfc2119-name = "RFC2119" +#let rfc2119-url = "https://www.rfc-editor.org/rfc/rfc2119" +#let rfc2119 = link(rfc2119-url, rfc2119-name) + +#let rfc8174-name = "RFC8174" +#let rfc8174-url = "https://www.rfc-editor.org/rfc/rfc8174" +#let rfc8174 = link(rfc8174-url, rfc8174-name) + +// the boilerplate you should include when using RFC words: +// +// Authors who follow these guidelines should incorporate this phrase near +// the beginning of their document: +#let rfc-keyword-boilerplate = [ + The key words #must-quoted, #must-not-quoted, #required-quoted, #shall-quoted, + #shall-not-quoted, #should-quoted, #should-not-quoted, #recommended-quoted, + #not-recommended-quoted, #may-quoted, and #optional-quoted in this document + are to be interpreted as described in #bcp14 [#rfc2119] [#rfc8174] when, and + only when, they appear in all capitals, as shown here. +] + +// definitions for each of the words + +#let rfc-keyword-must-definition = terms.item( + must, + [ + This word, or the terms #required-quoted or #shall-quoted, mean that the definition + is an absolute requirement of the specification. + ] +) + +#let rfc-keyword-must-not-definition = terms.item( + must-not, + [ + This phrase, or the phrase #shall-not-quoted, mean that the definition is an + absolute prohibition of the specification. + ] +) + +#let rfc-keyword-should-definition = terms.item( + should, + [ + This word, or the adjective #recommended-quoted, mean that there may exist valid + reasons in particular circumstances to ignore a particular item, but the full + implications must be understood and carefully weighed before choosing a + different course. + ] +) + +#let rfc-keyword-should-not-definition = terms.item( + should-not, + [ + This phrase, or the phrase #not-recommended-quoted mean that there may exist + valid reasons in particular circumstances when the particular behavior is + acceptable or even useful, but the full implications should be understood and + the case carefully weighed before implementing any behavior described with + this label. + ] +) + +#let rfc-keyword-may-definition = terms.item( + may, + [ + This word, or the adjective "#optional", mean that an item is truly + optional. One vendor may choose to include the item because a particular + marketplace requires it or because the vendor feels that it enhances the + product while another vendor may omit the same item. An implementation which + does not include a particular option #must be prepared to interoperate with + another implementation which does include the option, though perhaps with + reduced functionality. In the same vein an implementation which does include a + particular option #must be prepared to interoperate with another + implementation which does not include the option (except, of course, for the + feature the option provides.) + ] +) + +// and all definitions in a single term list +#let rfc-keyword-definitions = [ + #rfc-keyword-must-definition + #rfc-keyword-must-not-definition + #rfc-keyword-should-definition + #rfc-keyword-should-not-definition + #rfc-keyword-may-definition +] diff --git a/preview/rfc-vibe/0.1.1/thumbnail.png b/preview/rfc-vibe/0.1.1/thumbnail.png new file mode 100644 index 0000000..877121c Binary files /dev/null and b/preview/rfc-vibe/0.1.1/thumbnail.png differ diff --git a/preview/rfc-vibe/0.1.1/typst.toml b/preview/rfc-vibe/0.1.1/typst.toml new file mode 100644 index 0000000..e76cbff --- /dev/null +++ b/preview/rfc-vibe/0.1.1/typst.toml @@ -0,0 +1,11 @@ +[package] +name = "rfc-vibe" +version = "0.1.1" +entrypoint = "lib.typ" +authors = ["Stephen Waits "] +license = "MIT" +description = "Bring RFC language into everyday docs" +categories = ["utility"] +keywords = ["rfc", "keywords", "rfc2119", "rfc8174", "bcp14"] +repository = "https://github.com/swaits/typst-collection" +exclude = ["thumbnail.png", "examples/*"]