-
Notifications
You must be signed in to change notification settings - Fork 7
/
srfi-faq.html
383 lines (316 loc) · 16.3 KB
/
srfi-faq.html
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
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Scheme Request for Implementation - FAQ</title>
<link href="/favicon.png" rel="icon" sizes="192x192" type="image/png">
<link href="admin.css" rel="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1"></head>
<body>
<h1><a href="/"><img class="srfi-logo" src="srfi-logo.svg" alt="SRFI surfboard logo" /></a>Scheme
Request For Implementation - FAQ</h1>
<p>The <em>Scheme Request for Implementation</em> process is
<a href= "srfi-process.html">documented elsewhere</a>. This
document is intended to provide some of the rationale about SRFIs
rather than cluttering up that document.</p>
<p>The SRFI process grew out of the Scheme Workshop held in
Baltimore, MD, on September 26, 1998, where the attendees
considered a number of proposals for standardized feature sets
for inclusion in Scheme implementations. Many of the proposals
received overwhelming support in a series of straw votes. Along
with this there was concern that the next Revised Report would
not be produced for several years and this would prevent the
timely implementation of standardized approaches to several
important problems and needs in the Scheme community.</p>
<p>The SRFI process is a service provided to the Scheme community by
the editors, currently Arthur A. Gleckler. See <a
href="srfi-history.html">SRFI History</a> for information on the
previous editors. As of July, 2015, SRFI is hosted on <a
href="http://srfi-email.schemers.org/srfi-announce/msg/2736115">new
mail and web hosts</a>. (See the new <a
href="hosting-plan.html">Hosting Plan</a>.)</p>
<dl>
<dt>Are SRFIs standards?
<dd>
<p>Yes and no. SRFIs are <strong>not</strong> official
standards. There exist organizations such as ISO, IEEE, ANSI,
etc. who are set up to develop official standards. The SRFI
process is designed as an attempt to maximize the quality of
SRFIs within the constraint of not assigning authority to
anyone.</p>
<p>There are official Scheme standards, ANSI Scheme and
IEEE-1178-1990. SRFIs are in addition to these standards.</p>
<p>On the other hand, the process for creating SRFIs
<strong>is</strong> standardized, and each final SRFI remains
frozen and publicly available, hence they have many of the
properties of standards. So you might choose to think of them
as unofficial standards.</p>
<dt>Are SRFIs replacements for R<sup>n</sup>RS?
<dd>
<p>No. Each Revised Report has been written by a different body,
which determines what eventually is and is not included in
that report. The SRFI process is orthogonal to all of these
reports. Authors of SRFIs must not expect that their SRFIs
will be included, or even be considered, by the authors of
reports.</p>
<p>Of course anyone, including authors of future Revised
Reports, is welcome to employ the definition and rationale of
a SRFI, the discussion surrounding its adoption, and its
widespread implementation to argue that the authors of a
standard or report should consider adding the contents of the
SRFI to that standard.</p>
<p>If SRFIs had existed before R<sup>4</sup>RS, the macro
appendix to that report might have made more sense to have
been released as a SRFI. But it didn't. So it wasn't.</p>
<p>There is <strong>considerable</strong> value in reading
the <a href="https://groups.csail.mit.edu/mac/projects/scheme/rrrs-archive.html">discussions of the R<sup>n</sup>RS authors</a>, as they have often
considered issues that are candidates for SRFIs.</p>
<dt><a id="preliminary">Are SRFIs a discussion forum for
preliminary ideas?</a>
<dd>
<p>No. SRFIs stands for <em>Scheme Request for
Implementation</em>. Note the last word. If someone has
amorphous ideas for something that would be cool, but has no
idea how it might be done, they should discuss it in journals,
workshops, seminars, or public forums
like <a href="https://www.reddit.com/r/scheme/">r/scheme</a>
on Reddit. When the discussions have coalesced to the point
where an implementation strategy is apparent, then it is time
to write up a SRFI proposal.</p>
<dt>I really think that there should be a place to archive
non-implementation documents.
<dd>
<p>You're not alone! There seem to be lots of people who
disagree with the editors on this point. If you have ideas on how
this should be done, please send mail to
<a href="mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org"><srfi
minus editors at srfi dot schemers dot org></a></p>
<dt>Are SRFIs "RFCs for the Scheme community?"
<dd>
<p>Not quite. As RFC1796 (<a href=
"https://datatracker.ietf.org/doc/html/rfc1796">Not All RFCs are
Standards</a>) says, RFCs serve a variety of purposes. The SRFI
editors feel that there are sufficient other venues for
discussion of ideas. The point of SRFIs is that a programmer
can dependably test to see what features a Scheme
implementation provides, and can therefore program in a
portable way beyond the bounds of standardized Scheme.</p>
<dt>What's with all the time periods? Why so little
time?
<dd>
<p>The time periods are an attempt to drive the SRFI process as
quickly as possible while maintaining sufficient time for
sober second thought. To maximize the quality of SRFIs, we
want all of the relevant people to be involved in the
discussion of any particular SRFI proposal. Many of those
people are very busy, and this mechanism constrains the time
commitment they must make to stay on top of a proposal. It
also prevents discussion on a proposal from dragging on in an
endless repetition of the same points, long after anyone's
opinion is likely to be changed.</p>
<p>The other issue in the timing is to prevent editors from
stone-walling a proposal. It is not their job to make
qualitative judgments about proposals, but rather to maintain
the quality while expediting the creation of important
unofficial standards.</p>
<p>If a proposal is still under discussion after 90 days, it
means that it has been extended several times. The editors
will normally extend the discussion period to maintain a
minimum of 15 days after any significant change. Any proposal
still under active discussion and revision after 90 days is
not ready for codification. It will then be withdrawn for a
(normal) minimum of 30 days, after which it may be
resubmitted. If it is now in good shape, it will likely
become final after the 60-day discussion period. Thus, it
will have been delayed a maximum of 90 days. This is likely
to happen only in very exceptional cases, and is the only
cost of the fixed time periods.</p>
<dt><a id="teeth">What kind of standards are these,
anyway? There aren't any teeth in the rules!</a>
<dd>
<p>To have enforcement, there must be authority. There is no
absolute authority in the Scheme community, so there can be no
absolute enforcement. The final authority is the implementors.
If they believe that a particular SRFI documents a useful or
important feature, they will add it to their implementations;
if not, they won't. The discussion relating to any SRFI will be
retained indefinitely, and implementors can refer to that when
making their decision. Hence poorly worded, poorly reasoned, or
poorly defended SRFIs will be nothing more than a waste of
some time — regrettable, but necessary to retain an open
process.</p>
<dt>Why do I have to include a sample implementation?
<dd>
<p>See the discussion above about <a href=
"#preliminary">preliminary ideas</a>. SRFIs are about
implementation. If you haven't either: (a) built one, or (b)
have a very clear outline of how to build one, then you aren't
documenting anything useful about implementation. As the
<a href="srfi-process.html">process document</a> says, if you
think the editors are wrong to withdraw your proposal because
it doesn't have a sufficient outline of implementation, then
prove us wrong by going and implementing it on some system. Then
your SRFI will return to draft, and eventually active
status.</p>
<dt>What standard should my sample implementation use?
<dd>
<p>We encourage contributors to use R<sup>7</sup>RS combined with other
SRFIs as a basis. However, some SRFIs will require features not
present in R<sup>7</sup>RS and other SRFIs, and that's okay.
Furthermore, using other R<sup>n</sup>RS standards, as well as
IEEE Scheme, is acceptable.</p>
<dt>What should my sample implementation include?
<dd>
<p>It should implement all the features described in the SRFI
document.</p>
<p>It should also include automated tests. Having them will
help implementors, and that will increase the likelihood that
your SRFI will be incorporated in Scheme implementations. It
will also help users understand how your SRFI is to be used.
<p>However, if the sample implementation is trivial or not
really meant to be used, i.e. it is just a proof of concept,
it's okay to omit tests. That should be a rare case.
<p>No specific test framework is required, but both SRFI 64 and
SRFI 78 are available.
<dt>Do SRFIs exist to describe the features of a particular
Scheme implementation?
<dd>
<p>No. Every SRFI should describe a cohesive feature set that is
portable across a variety of Scheme implementations. (Here we
mean portable in the sense of being possible to implement,
not in the sense of a portable implementation.) Rather than
testing to see if the implementation is, e.g. Guile-4.3c, a
program should test for the particular features that it
requires.</p>
<p>This is a lesson learned from the Emacs world where it
used to be that code would check to see what version of Emacs
it was running on and make assumptions about the features
that that particular version provided. Unfortunately, that
made the code un-portable to alternative Emacs
implementations that had the required features but different
version numbers. The same lesson can be observed in
old C code that assumed that such-and-such a system had
particular features. More commonly today, C programs use a
configuration program that determines what libraries and
functions are available, regardless of the system or
compiler. The mechanism documented in <a href="srfi-7/">SRFI
7</a> essentially provides a similar capability, while
staying within Scheme code.</p>
<p>The biggest advantage of checking for features rather than
implementations is that code becomes portable to systems of
which the author was unaware, assuming that they provide the features
that the program requires.</p>
<dt>
<p>The process document mentions that different SRFIs may
conflict with each other. Won't that make it impossible for an
implementation to support conflicting SRFIs?</p>
<dd>Not necessarily. See <a href="/srfi-7/">SRFI 7</a>.
<a id="copyright"></a>
<dt>Does the SRFI copyright permit using a SRFI sample
implementation (or a derivative of one) in my Scheme
implementation?
<dd><p>Yes.</p>
<dt>Does the SRFI copyright permit using parts of a SRFI in
the documentation of my Scheme implementation?
<dd><p>Yes.</p>
<dt>Where did the acronym come from? It's a mouthful.
<dd>
<p>Alan Bawden suggested RFI at the Scheme workshop as a
humorous reference to RFCs. The S was added because the initial
editors (and others) felt that "Scheme" should be in there
somewhere. If you pronounce it <em>ess-are-eff-eye</em> it certainly
is a mouthful, but if you pronounce it <em>surfie</em>, as we do,
it's fine. Scheme Implementation Request (SIR) was also
proposed.</p>
<dt>Are there any special considerations if I use Github to
propose or comment on a SRFI?
<dd>
<p>Please keep the discussion of each SRFI on its mailing
list. For example, if you create a pull request, send all your
comments to the mailing list. While Github's tools can be
convenient, we don't want to lose any of our history to Github.
While their APIs make it straightforward to download almost
everything (e.g. comments, issues, and pull requests), we don't
have code in place to do that automatically.</p>
<dt>What if I don't want to use Github?
<dd>
<p>If you'd rather not use Github to propose SRFIs or
revisions to them, feel free to point the editors at alternate
Git repos or to send us patch files. (Patch files can be
created using <code>git format-patch -M origin/master</code> or
<code>git send-email</code>.) If you're a SRFI author and
would rather not use Git, either, just send updated files, or
links to them, or diffs, and we'll check in the changes.</p>
<dt>May I use Markdown or another format?
<dd>
<p>You may include a Markdown version, but you must still submit
the SRFI document as HTML.</p>
<p>Below is a snippet from the <code>Makefile</code> of SRFI 123.
It generates HTML from Markdown using the Pandoc tool (GPL
licensed).
<pre>
srfi-123.html: srfi-123.md
pandoc \
--css=http://srfi.schemers.org/srfi.css \
--from=markdown_github-hard_line_breaks \
--include-in-header=header.html \
--standalone \
--to=html \
srfi-123.md \
>srfi-123.html
</pre>
<p>Remember that the editors need to make slight changes to the
document, e.g. to add to its history of drafts, and won't edit
the document in a format other than HTML.</p>
<dt id="conventions">What linguistic conventions do SRFIs use?
<dd>
<p>Starting in about 2019, new SRFIs use some of the conventions
of the R7RS Small report
(<a href="https://small.r7rs.org/attachment/r7rs.pdf">PDF</a>),
section 1.3.2, a shortened form of which appears here. Note
that SRFIs before about 2019 may not follow these conventions.</p>
<p>When speaking of an error situation, we use the phrase “an
error is signaled” to indicate that implementations must
detect and report the error by raising a non-continuable
exception, as if by the procedure <code>raise</code>. The
phrase “an error that satisfies <i>predicate</i> is signaled”
means that an error is signaled as above. Furthermore, if the
object that is signaled is passed to the specified predicate,
the predicate returns <code>#t</code>.</p>
<p>The phrase "is an error," however, means that implementations
are not required to detect or report the error. In fact, the
implementation may take any action whatsoever, such as
signaling an error, extending a procedure’s behavior, or
failing catastrophically. If the value of an expression is
said to be “unspecified,” then the expression must evaluate to
some object without signaling an error, but the value depends
on the implementation.</p>
<p>Finally, the words and phrases “must,” “must not,” “shall,”
“shall not,” “should,” “should not,” “may,” “required,”
“recommended,” and “optional" are to be interpreted as
described in <a href="https://www.ietf.org/rfc/rfc2119.html">RFC
2119</a> unless otherwise specified. They are used only with
reference to implementer or implementation behavior, not with
reference to programmer or program behavior.</p></dd>
<dt>May I contribute code to a final SRFI, e.g. an implementation
of the SRFI for a specific Scheme implementation?
<dd>
<p>We are happy to accept contributions. We'll publish your code in
the SRFI's Git repository. Please
include a <code>README</code> file, and use the copyright notice
from the <a href="srfi-process.html">SRFI process</a>.</p>
<dt>Whom should I contact if I find a problem with the web site, etc?
<dd>
<p>Please send email to <a href="mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org">srfi-editors@<span class="antispam">nospam</span>srfi.schemers.org</a>.</p>
<dt><a id="errata"></a>How are errata handled?
<dd>
<p>See <a href="srfi-process.html#errata">Errata</a> in the
Process document.</p></dd>
</dl>
<hr>
<address>
<a href=
"mailto:srfi-editors%20at%20srfi%20dot%20schemers%20dot%20org">The
SRFI Editors</a>
</address>
<p>The history of this document is <a href="https://github.com/scheme-requests-for-implementation/srfi-common/commits/master/srfi-faq.html">here</a>.</body></html>