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