Skip to content

Commit 1585613

Browse files
committed
rustdoc: Enable the footnote markdown extension
This enables hoedown's footnote extension, and fixes all footnotes in the reference manual to use the new syntax.
1 parent 9306e84 commit 1585613

File tree

3 files changed

+59
-37
lines changed

3 files changed

+59
-37
lines changed

mk/tests.mk

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -220,8 +220,8 @@ ALL_CS := $(wildcard $(S)src/rt/*.cpp \
220220
$(S)src/rt/*/*/*.cpp \
221221
$(S)src/rustllvm/*.cpp)
222222
ALL_CS := $(filter-out $(S)src/rt/miniz.cpp \
223-
$(wildcard $(S)src/rt/sundown/src/*.c) \
224-
$(wildcard $(S)src/rt/sundown/html/*.c) \
223+
$(wildcard $(S)src/rt/hoedown/src/*.c) \
224+
$(wildcard $(S)src/rt/hoedown/bin/*.c) \
225225
,$(ALL_CS))
226226
ALL_HS := $(wildcard $(S)src/rt/*.h \
227227
$(S)src/rt/*/*.h \
@@ -232,8 +232,8 @@ ALL_HS := $(filter-out $(S)src/rt/vg/valgrind.h \
232232
$(S)src/rt/msvc/typeof.h \
233233
$(S)src/rt/msvc/stdint.h \
234234
$(S)src/rt/msvc/inttypes.h \
235-
$(wildcard $(S)src/rt/sundown/src/*.h) \
236-
$(wildcard $(S)src/rt/sundown/html/*.h) \
235+
$(wildcard $(S)src/rt/hoedown/src/*.h) \
236+
$(wildcard $(S)src/rt/hoedown/bin/*.h) \
237237
,$(ALL_HS))
238238

239239
# Run the tidy script in multiple parts to avoid huge 'echo' commands
@@ -266,6 +266,7 @@ tidy:
266266
-and -not -name '*.sh' \
267267
| grep '^$(S)src/llvm' -v \
268268
| grep '^$(S)src/libuv' -v \
269+
| grep '^$(S)src/rt/hoedown' -v \
269270
| grep '^$(S)src/gyp' -v \
270271
| grep '^$(S)src/etc' -v \
271272
| grep '^$(S)src/doc' -v \

src/doc/rust.md

Lines changed: 44 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,12 @@ production. See [tokens](#tokens) for more information.
116116
Rust input is interpreted as a sequence of Unicode codepoints encoded in UTF-8,
117117
normalized to Unicode normalization form NFKC.
118118
Most Rust grammar rules are defined in terms of printable ASCII-range codepoints,
119-
but a small number are defined in terms of Unicode properties or explicit codepoint lists.
120-
^[Substitute definitions for the special Unicode productions are provided to the grammar verifier, restricted to ASCII range, when verifying the grammar in this document.]
119+
but a small number are defined in terms of Unicode properties or explicit
120+
codepoint lists. [^inputformat]
121+
122+
[^inputformat]: Substitute definitions for the special Unicode productions are
123+
provided to the grammar verifier, restricted to ASCII range, when verifying
124+
the grammar in this document.
121125

122126
## Special Unicode Productions
123127

@@ -631,10 +635,13 @@ Semantic rules called "dynamic semantics" govern the behavior of programs at run
631635
A program that fails to compile due to violation of a compile-time rule has no defined dynamic semantics; the compiler should halt with an error report, and produce no executable artifact.
632636

633637
The compilation model centres on artifacts called _crates_.
634-
Each compilation processes a single crate in source form, and if successful, produces a single crate in binary form: either an executable or a library.^[A crate is somewhat
635-
analogous to an *assembly* in the ECMA-335 CLI model, a *library* in the
636-
SML/NJ Compilation Manager, a *unit* in the Owens and Flatt module system,
637-
or a *configuration* in Mesa.]
638+
Each compilation processes a single crate in source form, and if successful,
639+
produces a single crate in binary form: either an executable or a
640+
library.[^cratesourcefile]
641+
642+
[^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the
643+
ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit*
644+
in the Owens and Flatt module system, or a *configuration* in Mesa.
638645

639646
A _crate_ is a unit of compilation and linking, as well as versioning, distribution and runtime loading.
640647
A crate contains a _tree_ of nested [module](#modules) scopes.
@@ -3246,12 +3253,17 @@ types. User-defined types have limited capabilities.
32463253

32473254
The primitive types are the following:
32483255

3249-
* The "unit" type `()`, having the single "unit" value `()` (occasionally called "nil").
3250-
^[The "unit" value `()` is *not* a sentinel "null pointer" value for reference slots; the "unit" type is the implicit return type from functions otherwise lacking a return type, and can be used in other contexts (such as message-sending or type-parametric code) as a zero-size type.]
3256+
* The "unit" type `()`, having the single "unit" value `()` (occasionally called
3257+
"nil"). [^unittype]
32513258
* The boolean type `bool` with values `true` and `false`.
32523259
* The machine types.
32533260
* The machine-dependent integer and floating-point types.
32543261

3262+
[^unittype]: The "unit" value `()` is *not* a sentinel "null pointer" value for
3263+
reference slots; the "unit" type is the implicit return type from functions
3264+
otherwise lacking a return type, and can be used in other contexts (such as
3265+
message-sending or type-parametric code) as a zero-size type.]
3266+
32553267
#### Machine types
32563268

32573269
The machine types are the following:
@@ -3270,16 +3282,19 @@ The machine types are the following:
32703282

32713283
#### Machine-dependent integer types
32723284

3273-
The Rust type `uint`^[A Rust `uint` is analogous to a C99 `uintptr_t`.] is an
3285+
The Rust type `uint` [^rustuint] is an
32743286
unsigned integer type with target-machine-dependent size. Its size, in
32753287
bits, is equal to the number of bits required to hold any memory address on
32763288
the target machine.
32773289

3278-
The Rust type `int`^[A Rust `int` is analogous to a C99 `intptr_t`.] is a
3290+
The Rust type `int` [^rustint] is a
32793291
two's complement signed integer type with target-machine-dependent size. Its
32803292
size, in bits, is equal to the size of the rust type `uint` on the same target
32813293
machine.
32823294

3295+
[^rustuint]: A Rust `uint` is analogous to a C99 `uintptr_t`.
3296+
[^rustint]: A Rust `int` is analogous to a C99 `intptr_t`.
3297+
32833298
### Textual types
32843299

32853300
The types `char` and `str` hold textual data.
@@ -3352,10 +3367,12 @@ and access to a vector is always bounds-checked.
33523367

33533368
### Structure types
33543369

3355-
A `struct` *type* is a heterogeneous product of other types, called the *fields* of the type.
3356-
^[`struct` types are analogous `struct` types in C,
3357-
the *record* types of the ML family,
3358-
or the *structure* types of the Lisp family.]
3370+
A `struct` *type* is a heterogeneous product of other types, called the *fields*
3371+
of the type.[^structtype]
3372+
3373+
[^structtype]: `struct` types are analogous `struct` types in C,
3374+
the *record* types of the ML family,
3375+
or the *structure* types of the Lisp family.
33593376

33603377
New instances of a `struct` can be constructed with a [struct expression](#structure-expressions).
33613378

@@ -3375,9 +3392,10 @@ is the only value that inhabits such a type.
33753392
### Enumerated types
33763393

33773394
An *enumerated type* is a nominal, heterogeneous disjoint union type,
3378-
denoted by the name of an [`enum` item](#enumerations).
3379-
^[The `enum` type is analogous to a `data` constructor declaration in ML,
3380-
or a *pick ADT* in Limbo.]
3395+
denoted by the name of an [`enum` item](#enumerations). [^enumtype]
3396+
3397+
[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
3398+
ML, or a *pick ADT* in Limbo.
33813399

33823400
An [`enum` item](#enumerations) declares both the type and a number of *variant constructors*,
33833401
each of which is independently named and takes an optional tuple of arguments.
@@ -3804,14 +3822,15 @@ By default, the scheduler chooses the number of threads based on
38043822
the number of concurrent physical CPUs detected at startup.
38053823
It's also possible to override this choice at runtime.
38063824
When the number of tasks exceeds the number of threads — which is likely —
3807-
the scheduler multiplexes the tasks onto threads.^[
3808-
This is an M:N scheduler,
3809-
which is known to give suboptimal results for CPU-bound concurrency problems.
3810-
In such cases, running with the same number of threads and tasks can yield better results.
3811-
Rust has M:N scheduling in order to support very large numbers of tasks
3812-
in contexts where threads are too resource-intensive to use in large number.
3813-
The cost of threads varies substantially per operating system, and is sometimes quite low,
3814-
so this flexibility is not always worth exploiting.]
3825+
the scheduler multiplexes the tasks onto threads.[^mnscheduler]
3826+
3827+
[^mnscheduler]: This is an M:N scheduler, which is known to give suboptimal
3828+
results for CPU-bound concurrency problems. In such cases, running with the
3829+
same number of threads and tasks can yield better results. Rust has M:N
3830+
scheduling in order to support very large numbers of tasks in contexts where
3831+
threads are too resource-intensive to use in large number. The cost of
3832+
threads varies substantially per operating system, and is sometimes quite
3833+
low, so this flexibility is not always worth exploiting.
38153834

38163835
### Communication between tasks
38173836

src/librustdoc/html/markdown.rs

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@ static HOEDOWN_EXT_TABLES: libc::c_uint = 1 << 0;
5151
static HOEDOWN_EXT_FENCED_CODE: libc::c_uint = 1 << 1;
5252
static HOEDOWN_EXT_AUTOLINK: libc::c_uint = 1 << 3;
5353
static HOEDOWN_EXT_STRIKETHROUGH: libc::c_uint = 1 << 4;
54+
static HOEDOWN_EXT_SUPERSCRIPT: libc::c_uint = 1 << 8;
55+
static HOEDOWN_EXT_FOOTNOTES: libc::c_uint = 1 << 2;
56+
57+
static HOEDOWN_EXTENSIONS: libc::c_uint =
58+
HOEDOWN_EXT_NO_INTRA_EMPHASIS | HOEDOWN_EXT_TABLES |
59+
HOEDOWN_EXT_FENCED_CODE | HOEDOWN_EXT_AUTOLINK |
60+
HOEDOWN_EXT_STRIKETHROUGH | HOEDOWN_EXT_SUPERSCRIPT |
61+
HOEDOWN_EXT_FOOTNOTES;
5462

5563
type hoedown_document = libc::c_void; // this is opaque to us
5664

@@ -236,9 +244,6 @@ pub fn render(w: &mut io::Writer, s: &str, print_toc: bool) -> fmt::Result {
236244

237245
unsafe {
238246
let ob = hoedown_buffer_new(DEF_OUNIT);
239-
let extensions = HOEDOWN_EXT_NO_INTRA_EMPHASIS | HOEDOWN_EXT_TABLES |
240-
HOEDOWN_EXT_FENCED_CODE | HOEDOWN_EXT_AUTOLINK |
241-
HOEDOWN_EXT_STRIKETHROUGH;
242247
let renderer = hoedown_html_renderer_new(0, 0);
243248
let mut opaque = MyOpaque {
244249
dfltblk: (*renderer).blockcode.unwrap(),
@@ -248,7 +253,7 @@ pub fn render(w: &mut io::Writer, s: &str, print_toc: bool) -> fmt::Result {
248253
(*renderer).blockcode = Some(block);
249254
(*renderer).header = Some(header);
250255

251-
let document = hoedown_document_new(renderer, extensions, 16);
256+
let document = hoedown_document_new(renderer, HOEDOWN_EXTENSIONS, 16);
252257
hoedown_document_render(document, ob, s.as_ptr(),
253258
s.len() as libc::size_t);
254259
hoedown_document_free(document);
@@ -319,15 +324,12 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
319324

320325
unsafe {
321326
let ob = hoedown_buffer_new(DEF_OUNIT);
322-
let extensions = HOEDOWN_EXT_NO_INTRA_EMPHASIS | HOEDOWN_EXT_TABLES |
323-
HOEDOWN_EXT_FENCED_CODE | HOEDOWN_EXT_AUTOLINK |
324-
HOEDOWN_EXT_STRIKETHROUGH;
325327
let renderer = hoedown_html_renderer_new(0, 0);
326328
(*renderer).blockcode = Some(block);
327329
(*renderer).header = Some(header);
328330
(*(*renderer).opaque).opaque = tests as *mut _ as *mut libc::c_void;
329331

330-
let document = hoedown_document_new(renderer, extensions, 16);
332+
let document = hoedown_document_new(renderer, HOEDOWN_EXTENSIONS, 16);
331333
hoedown_document_render(document, ob, doc.as_ptr(),
332334
doc.len() as libc::size_t);
333335
hoedown_document_free(document);

0 commit comments

Comments
 (0)