Skip to content

Commit 4263a9d

Browse files
jyasskinjyasskin
authored
Convert the specification into RFC format (#466)
Fixes: #461 * Initial conversion to Internet-Draft. * Setup repository for draft-marchan-kdl2 using https://github.com/martinthomson/i-d-template * Remove unnecessary changes. * Tweak source to make the I-D build. * Fix zkat's name. Guess at their preferred initials. * Separate links where linking text equals the anchor. This works around cabo/kramdown-rfc#249. * Replace horizontal rules with subsections. RFCXML v3 doesn't include horizontal rules. * Use ~~~kdl instead of `` for strings with significant whitespace. That compiles to <sourcecode> which preserves sequences of spaces. * Give breadcrumbs to the RFC format definitions. * Point contributors to https://author-tools.ietf.org/. For if installing the dependencies is inconvenient. * Separate a code block from adjacent text. * Remove a workflow that overwrites customized files. * Remove the 'archive' workflow. * Use "Term ({{term}})" uniformly instead of just when the term matches the anchor. * Fix the instructions for preserving the RFCXML. * Remove the default copyright notice until the spec is relicensed. * Take the IETF licensing details out of CONTRIBUTING.md.
1 parent 0c2dde6 commit 4263a9d

File tree

11 files changed

+466
-193
lines changed

11 files changed

+466
-193
lines changed

‎.editorconfig‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# See http://editorconfig.org
2+
3+
root = true
4+
5+
[*.{md,xml,org}]
6+
charset = utf-8
7+
insert_final_newline = true
8+
trim_trailing_whitespace = true

‎.github/workflows/ghpages.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: "Update Editor's Copy"
2+
3+
on:
4+
push:
5+
paths-ignore:
6+
- README.md
7+
- CONTRIBUTING.md
8+
- LICENSE.md
9+
- .gitignore
10+
pull_request:
11+
paths-ignore:
12+
- README.md
13+
- CONTRIBUTING.md
14+
- LICENSE.md
15+
- .gitignore
16+
17+
jobs:
18+
build:
19+
name: "Update Editor's Copy"
20+
runs-on: ubuntu-latest
21+
permissions:
22+
contents: write
23+
steps:
24+
- name: "Checkout"
25+
uses: actions/checkout@v4
26+
27+
- name: "Setup"
28+
id: setup
29+
run: date -u "+date=%FT%T" >>"$GITHUB_OUTPUT"
30+
31+
- name: "Caching"
32+
uses: actions/cache@v4
33+
with:
34+
path: |
35+
.refcache
36+
.venv
37+
.gems
38+
node_modules
39+
.targets.mk
40+
key: i-d-${{ steps.setup.outputs.date }}
41+
restore-keys: i-d-
42+
43+
- name: "Build Drafts"
44+
uses: martinthomson/i-d-template@v1
45+
with:
46+
token: ${{ github.token }}
47+
48+
- name: "Update GitHub Pages"
49+
uses: martinthomson/i-d-template@v1
50+
if: ${{ github.event_name == 'push' }}
51+
with:
52+
make: gh-pages
53+
token: ${{ github.token }}
54+
55+
- name: "Archive Built Drafts"
56+
uses: actions/upload-artifact@v4
57+
with:
58+
path: |
59+
draft-*.html
60+
draft-*.txt

‎.github/workflows/publish.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: "Publish New Draft Version"
2+
3+
on:
4+
push:
5+
tags:
6+
- "draft-*"
7+
workflow_dispatch:
8+
inputs:
9+
email:
10+
description: "Submitter email"
11+
default: ""
12+
type: string
13+
14+
jobs:
15+
build:
16+
name: "Publish New Draft Version"
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: "Checkout"
20+
uses: actions/checkout@v4
21+
22+
# See https://github.com/actions/checkout/issues/290
23+
- name: "Get Tag Annotations"
24+
run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}
25+
26+
- name: "Setup"
27+
id: setup
28+
run: date -u "+date=%FT%T" >>"$GITHUB_OUTPUT"
29+
30+
- name: "Caching"
31+
uses: actions/cache@v4
32+
with:
33+
path: |
34+
.refcache
35+
.venv
36+
.gems
37+
node_modules
38+
.targets.mk
39+
key: i-d-${{ steps.setup.outputs.date }}
40+
restore-keys: i-d-
41+
42+
- name: "Build Drafts"
43+
uses: martinthomson/i-d-template@v1
44+
with:
45+
token: ${{ github.token }}
46+
47+
- name: "Upload to Datatracker"
48+
uses: martinthomson/i-d-template@v1
49+
with:
50+
make: upload
51+
env:
52+
UPLOAD_EMAIL: ${{ inputs.email }}
53+
54+
- name: "Archive Submitted Drafts"
55+
uses: actions/upload-artifact@v4
56+
with:
57+
path: "versioned/draft-*-[0-9][0-9].*"

‎.gitignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,25 @@
11
/target
22
Cargo.lock
3+
*.html
4+
*.pdf
5+
*.redxml
6+
*.swp
7+
*.txt
8+
*.upload
9+
*~
10+
.tags
11+
/*-[0-9][0-9].xml
12+
/.*.mk
13+
/.gems/
14+
/.refcache
15+
/.venv/
16+
/.vscode/
17+
/lib
18+
/node_modules/
19+
/versioned/
20+
Gemfile.lock
21+
archive.json
22+
draft-marchan-kdl2.xml
23+
package-lock.json
24+
report.xml
25+
!requirements.txt

‎.note.xml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<note title="Discussion Venues" removeInRFC="true">
2+
<t>Source for this draft and an issue tracker can be found at
3+
<eref target="https://github.com/kdl-org/kdl"/>.</t>
4+
</note>

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing
2+
3+
## Mechanics
4+
5+
Contributions can be made by creating pull requests.
6+
The GitHub interface supports creating pull requests using the Edit (✏) button.
7+
8+
9+
## Building the Specification
10+
11+
The specification is written in
12+
[kramdown-rfc](https://github.com/cabo/kramdown-rfc/wiki/Syntax2), which
13+
compiles via [RFCXML](https://authors.ietf.org/rfcxml-vocabulary) to text and
14+
HTML.
15+
16+
You can build the formatted versions or the intermediate RFCXML file using
17+
https://author-tools.ietf.org/ or locally by running `make`. To preserve the
18+
intermediate RFCXML form in a local build, run `make draft-marchan-kdl2.xml`
19+
once.
20+
21+
Command line usage requires that you have the necessary software installed. See
22+
[the instructions](https://github.com/martinthomson/i-d-template/blob/main/doc/SETUP.md).

‎Makefile‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
LIBDIR := lib
2+
include $(LIBDIR)/main.mk
3+
4+
$(LIBDIR)/main.mk:
5+
ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null))
6+
git submodule sync
7+
git submodule update --init
8+
else
9+
ifneq (,$(wildcard $(ID_TEMPLATE_HOME)))
10+
ln -s "$(ID_TEMPLATE_HOME)" $(LIBDIR)
11+
else
12+
git clone -q --depth 10 -b main \
13+
https://github.com/martinthomson/i-d-template $(LIBDIR)
14+
endif
15+
endif

‎QUERY-SPEC.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Then the following queries are valid:
110110
## Full Grammar
111111

112112
Rules that are not defined in this grammar are prefixed with `$`, see [the KDL
113-
grammar](https://github.com/kdl-org/kdl/blob/main/SPEC.md#full-grammar) for
113+
grammar](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html#full-grammar) for
114114
what they expand to.
115115

116116
```

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,16 @@ package {
4646

4747
For more details, see the [overview below](#overview).
4848

49-
There's a living [specification](SPEC.md), as well as various
49+
There's a living [specification](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html), as well as various
5050
[implementations](#implementations). You can also check out the [FAQ](#faq) to
5151
answer all your burning questions!
5252

5353
The current version of the KDL spec is
54-
[KDL 2.0.0](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md). For legacy KDL,
54+
[KDL 2.0.0](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html). For legacy KDL,
5555
please refer to the [KDL 1.0.0
5656
spec](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC_v1.md). All users are
5757
encouraged to migrate. [Migration is forward-and-backward-compatible and
58-
safe](https://github.com/kdl-org/kdl/blob/2.0.0/SPEC.md#compatibility), and can
58+
safe](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html#compatibility), and can
5959
be automated.
6060

6161
In addition to a spec for KDL itself, there are specifications for [a KDL Query
@@ -400,7 +400,7 @@ SDLang is an excellent base, but I wanted some details ironed out, and some
400400
things removed that only really made sense for SDLang's current use-cases, including
401401
some restrictions about data representation. KDL is very similar in many ways, except:
402402

403-
* The grammar and expected semantics are [well-defined and specified](SPEC.md).
403+
* The grammar and expected semantics are [well-defined and specified](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html).
404404
This was the original impetus for working on KDL, followed by details that
405405
seemed like they could be improved.
406406
* There is only one "number" type. KDL does not prescribe representations, but

‎SPEC_v1.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@ simultaneously. For example, `node "foo"` is a valid node in both versions, and
2222
should be represented identically by parsers.
2323

2424
KDL v2 is designed such that for any given KDL document written as KDL
25-
1.0 or [KDL 2.0](./SPEC.md), the parse will either fail completely, or, if the
25+
1.0 or [KDL 2.0](https://kdl-org.github.io/kdl/#go.draft-marchan-kdl2.html),
26+
the parse will either fail completely, or, if the
2627
parse succeeds, the data represented by a v1 or v2 parser will be identical.
2728
This means that it's safe to use a fallback parsing strategy in order to support
2829
both v1 and v2 simultaneously. For example, `node "foo"` is a valid node in both
@@ -540,4 +541,4 @@ unicode-space := See Table (All White_Space unicode characters which are not `ne
540541
single-line-comment := '//' ^newline+ (newline | eof)
541542
multi-line-comment := '/*' commented-block
542543
commented-block := '*/' | (multi-line-comment | '*' | '/' | [^*/]+) commented-block
543-
```
544+
```

0 commit comments

Comments
 (0)