chore(rfc-vibe) cp 0.1.0 -> 0.1.1
This commit is contained in:
7 files changed
+320
No files matched your search
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024 Stephen Waits <steve@waits.net>
|
||||
|
||||
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.
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
|
||||
for details.
|
||||
Binary file not shown.
@@ -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)
|
||||
@@ -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
|
||||
]
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 992 KiB |
@@ -0,0 +1,11 @@
|
||||
[package]
|
||||
name = "rfc-vibe"
|
||||
version = "0.1.1"
|
||||
entrypoint = "lib.typ"
|
||||
authors = ["Stephen Waits <steve@waits.net>"]
|
||||
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/*"]
|
||||
Reference in new issue
Block a user