1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
---
title: riki static site generator
subtitle: Subset of ikiwiki rewritten in Rust
bindings:
- subplot/riki.yaml
- lib/files.yaml
- lib/runcmd.yaml
impls:
rust:
- subplot/riki.rs
...
[ikiwiki]: http://ikiwiki.info/
[Subplot]: https://subplot.tech/
# Introduction
`riki` is a small subset of [ikiwiki][] rewritten in Rust, for
speed. This document describes the requirements and acceptance
criteria for the software, and how to verify that riki meets them in
an automated way. This is done using the [Subplot][] software.
# Verification scenarios
The approach used for verifying acceptance criteria is to run `riki`
against known inputs, and check that the output is as expected.
Specifically this is done by comparing the Pandoc abstract syntax
trees of the input and output. Pandoc is a well-known, well-respected
tool that we rely on as an "oracle".
## Markdown features
### Empty Markdown file
_Requirement: Given an empty input Markdown file, the output must
be an empty HTML file._
~~~scenario
given an installed riki
given file site/empty.mdwn from empty
when I run riki site output
then AST of site/empty.mdwn matches that of output/empty.html
~~~
~~~{#empty .file}
~~~
### Plain text
_Requirement: Given a Markdown file with plain text, the output must
be an HTML file with the same text, without extra elements._
~~~scenario
given an installed riki
given file site/page.mdwn from para
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#para .file}
Hello, world.
There are two paragraphs.
~~~
### Indented code block
_Requirement: Given a Markdown file with an indented code block, the
output must have a pre element.
~~~scenario
given an installed riki
given file site/page.mdwn from indented-code
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#indented-code .file}
This is indented by four spaces.
~~~
### Fenced code block
_Requirement: Given a Markdown file with a fenced code block, the
output must have a pre element.
~~~scenario
given an installed riki
given file site/page.mdwn from fenced-code
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#fenced-code .file}
```
This is a fenced code block.
```
~~~
### Image link
_Requirement: Given a Markdown file linking to an image, the output
must have an img element.
~~~scenario
given an installed riki
given file site/page.mdwn from image-link
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#image-link .file}
~~~
### Emphasised text
_Requirement: Inline markup for emphasis must result in an em element
in HTML output._
~~~scenario
given an installed riki
given file site/page.mdwn from emph
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#emph .file}
There is *emphasized*, and so is _this_.
~~~
### Strongly emphasised text
_Requirement: Inline markup for strong emphasis must result in a
strong element in HTML output._
~~~scenario
given an installed riki
given file site/page.mdwn from strong
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#strong .file}
There is **emphasized**, and so is __this__.
~~~
### Strike through in text
_Requirement: Inline markup for strike through must result in a del
element in HTML output._
~~~scenario
given an installed riki
given file site/page.mdwn from strike
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#strike .file}
There is ~~struck through~~.
~~~
### Top level heading
_Requirement: Given a Markdown file with top level heading, the output must
be an HTML file with one h1 element, without extra elements._
~~~scenario
given an installed riki
given file site/page.mdwn from h1
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#h1 .file}
# Heading
~~~
### Inline code
_Requirement: Inline code markup with backticks must result in a code
element in HTML output._
~~~scenario
given an installed riki
given file site/page.mdwn from backticks
when I run riki site output
then AST of site/page.mdwn matches that of output/page.html
~~~
~~~{#backticks .file}
There is `code` lurking here.
~~~
## Input files other than Markdown
_Requirement: Input files that aren't Markdown files must be copied
into the destination directory as-is._
~~~scenario
given an installed riki
given file site/image.jpg from image
when I run riki site output
then files site/image.jpg and output/image.jpg match
~~~
~~~{#image .file}
# Dummy
Pretend this is an image.
~~~
## Input files in sub=directories
_Requirement: If an source page or file is in a sub-directory, it
should be put in the corresponding sub-directory in the target
directory._
~~~scenario
given an installed riki
given file site/foo/page.mdwn from image
given file site/bar/image.jpg from para
when I run riki site output
then AST of site/foo/page.mdwn matches that of output/foo/page.html
then files site/bar//image.jpg and output/bar/image.jpg match
~~~
|
