Skip to content

Commit 4516d44

Browse files
ehussehuss
authored
Merge pull request #13 from ehuss/mdbook-spec
Add mdbook-spec.
2 parents 5da3ca9 + 0a0cb86 commit 4516d44

File tree

13 files changed

+1447
-2
lines changed

13 files changed

+1447
-2
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: CI
2+
on:
3+
pull_request:
4+
merge_group:
5+
6+
jobs:
7+
test:
8+
name: Test
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@master
12+
- name: Install mdbook
13+
run: |
14+
mkdir bin
15+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
16+
echo "$(pwd)/bin" >> $GITHUB_PATH
17+
- name: Verify the book builds
18+
env:
19+
SPEC_DENY_WARNINGS: 1
20+
run: mdbook build

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
book

‎README.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
1-
# spec
2-
The Rust specification
1+
# The Rust Specification
2+
3+
## Building
4+
5+
The specification uses [mdBook] to process the source into HTML. See [mdBook Installation] for more information on installing mdBook. To build the book, run:
6+
7+
```sh
8+
mdbook build
9+
```
10+
11+
This will output the HTML into a directory called `book`.
12+
13+
For authors, consider using the server functionality which supports automatic reload:
14+
15+
```sh
16+
mdbook serve --open
17+
```
18+
19+
This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
20+
21+
[mdBook]: https://rust-lang.github.io/mdBook/
22+
[mdBook Insallation]: https://rust-lang.github.io/mdBook/guide/installation.html
323

424
## License
525

‎book.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[book]
2+
language = "en"
3+
title = "The Rust Specification"
4+
src = "spec"
5+
6+
[output.html]
7+
additional-css = ["css/custom.css"]
8+
curly-quotes = true
9+
10+
[preprocessor.spec]
11+
command = "cargo run --locked --manifest-path=mdbook-spec/Cargo.toml"
12+
13+
[build]
14+
extra-watch-dirs = ["mdbook-spec/src", "css"]

‎css/custom.css‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
/* Custom CSS for the Rust Specification. */
2+
3+
/* <kbd> tags can be used to highlight specific character elements. */
4+
kbd {
5+
border: 1px solid #999;
6+
display: inline-block;
7+
border-radius: 3px;
8+
padding: 0 0.6ex;
9+
background: #eee;
10+
box-shadow: inset -1px -1px 0 #999;
11+
vertical-align: baseline;
12+
color: #000;
13+
height: 1.55em;
14+
font-style: normal;
15+
font-weight: bold;
16+
font-family: inherit;
17+
font-size: revert;
18+
line-height: revert;
19+
}
20+
kbd.optional {
21+
border-style: dashed;
22+
background: #fff;
23+
}
24+
var.optional {
25+
border-style: dashed;
26+
}
27+
/* <var> tags can be used for non-terminals. */
28+
var {
29+
border: 1px solid #9c9;
30+
box-shadow: inset -1px -1px 0 #9c9;
31+
font-style: normal;
32+
display: inline-block;
33+
vertical-align: baseline;
34+
border-radius: 7px;
35+
padding: 0 4px;
36+
background: #dfd;
37+
margin: 2px;
38+
}
39+
var.type {
40+
box-shadow: inset -1px -1px 0 #c99;
41+
border-color: #c99;
42+
background: #fdd;
43+
}
44+
/* <span class="repeat"> can be used for a grammar production that repeats zero or more times. */
45+
span.repeat {
46+
position: relative;
47+
border: 1px dashed #393;
48+
border-radius: 10px;
49+
display: inline-block;
50+
padding: 6px;
51+
margin-left: 0.5ex;
52+
margin-top: 1em;
53+
margin-bottom: 0.5ex;
54+
min-width: 3.8em;
55+
text-align: center;
56+
}
57+
span.repeat::before {
58+
content: "zero or more";
59+
white-space: nowrap;
60+
display: block;
61+
text-align: center;
62+
font-size: 0.75em;
63+
position: absolute;
64+
left: 0;
65+
right: 0;
66+
top: -1.4em;
67+
color: #393;
68+
}
69+
var > span {
70+
display: inline-block;
71+
border-right: 1px dotted green;
72+
padding-right: 0.5ex;
73+
margin-right: 0.5ex;
74+
font-style: italic;
75+
}
76+
77+
/* <span class="version"> can be used to highlight a specific version of Rust. */
78+
span.version {
79+
float: right;
80+
margin-left: 1em;
81+
margin-bottom: 1em;
82+
background: #f7c0eb;
83+
padding: 0.2ex 0.5ex;
84+
border-radius: 5px;
85+
display: block;
86+
box-shadow: inset -1px -1px 0 #a06894;
87+
font-size: 0.9em;
88+
}
89+
90+
/* <dfn> tags are used to indicate a specific word or phrase is being defined. */
91+
dfn {
92+
font-style: italic;
93+
text-decoration: underline;
94+
}
95+
96+
.content main {
97+
/* Provides space on the left for the rule call-outs. */
98+
padding-left: 4em;
99+
}
100+
101+
/* Rules are generated via r[foo.bar] syntax, processed by mdbook-spec. */
102+
.rule {
103+
/* Allows the rule to be positioned. */
104+
position: relative;
105+
/* Position slightly to the left. */
106+
left: -4em;
107+
color: #999;
108+
font-size: 0.8em;
109+
}
110+
/* mdbook will wrap the rule content in a <p> tag, with a margin. However, we
111+
don't need the extra space
112+
*/
113+
.rule ~ p {
114+
margin-top: 0px;
115+
}
116+
117+
/* Change the default styling of blockquotes. */
118+
blockquote {
119+
font-style: italic;
120+
font-size: 0.9em;
121+
color: #333;
122+
background: #fff2d3;
123+
padding: 1ex 1em;
124+
margin: 1ex;
125+
margin-left: 2em;
126+
display: table;
127+
/* vw units allow this to be adaptive to the screen size so it isn't too small on mobile. */
128+
margin-right: 12vw;
129+
}
130+
/* mdbook will wrap the blockquote content in a <p> tag, with a margin. However,
131+
that adds too much space, so remove it.
132+
*/
133+
blockquote > p {
134+
margin-top: 0px;
135+
margin-bottom: 0px;
136+
}
137+
138+
/* When the sidebar is visible, reduce the spacing of rules so that the
139+
content doesn't get shifted too far, and make the text too narrow.
140+
*/
141+
.sidebar-visible .rule {
142+
left: -1em;
143+
}
144+
.sidebar-visible .content main {
145+
padding-left: 1em;
146+
}
147+
148+
/* Remove the blue coloring of links on rules that mdbook normally sets. */
149+
.rule-link {
150+
color: #999 !important;
151+
}
152+
153+
/* When clicking a rule, it is added as a URL fragment and the browser will
154+
navigate to it. This adds an indicator that the linked rule is the one that
155+
is "current", just like normal headers are in mdbook.
156+
*/
157+
.rule:target::before {
158+
display: inline-block;
159+
content: "»";
160+
margin-inline-start: -20px;
161+
width: 20px;
162+
}
163+
164+
/* Sets the color for [!HISTORY] blockquote admonitions. */
165+
.history > blockquote {
166+
background: #f7c0eb;
167+
}

‎docs/authoring.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Authoring Guide
2+
3+
## Markdown formatting
4+
5+
* Use ATX-style heading with sentence case.
6+
7+
## Special markdown constructs
8+
9+
### Rules
10+
11+
Most clauses should be preceded with a rule.
12+
Rules can be specified in the markdown source with the following on a line by itself:
13+
14+
```
15+
r[foo.bar]
16+
```
17+
18+
The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`).
19+
20+
Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are automatic link references so that any rule can be referred to from any page in the book.
21+
22+
In the HTML, the rules are clickable just like headers.
23+
24+
### Admonitions
25+
26+
Admonitions use a style similar to GitHub-flavored markdown, where the style name is placed at the beginning of a blockquote, such as:
27+
28+
```
29+
> [!WARNING]
30+
> This is a warning.
31+
```
32+
33+
All this does is apply a CSS class to the blockquote. You should define the color or style of the rule in the `css/custom.css` file if it isn't already defined.

‎mdbook-spec/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/target

0 commit comments

Comments
 (0)