Merge pull request #1710 from WaffleLapkin/pretty-rule-refs

move r[rules] to the left of the main body, using a grid

Author: ehuss

mdbook-spec/src/rules.rs

@@ -105,9 +105,10 @@ impl Spec {
                 }
                 format!(
                     "<div class=\"rule\" id=\"r-{rule_id}\">\
-                     <a class=\"rule-link\" href=\"#r-{rule_id}\">[{rule_id}]</a>\
+                     <a class=\"rule-link\" href=\"#r-{rule_id}\" title=\"{rule_id}\"><span>[{rule_id_broken}]<span/></a>\
                      {test_html}\
-                     </div>\n"
+                     </div>\n",
+                     rule_id_broken = rule_id.replace(".", "<wbr>."),
                 )
             })
             .to_string()

src/attributes.md

@@ -105,9 +105,8 @@ fn some_unused_variables() {
 }
 ```
 
-## Meta Item Attribute Syntax
-
 r[attributes.meta]
+## Meta Item Attribute Syntax
 
 r[attributes.meta.intro]
 A "meta item" is the syntax used for the _Attr_ rule by most [built-in
@@ -188,9 +187,8 @@ _MetaListPaths_ | `allow(unused, clippy::inline_always)`
 _MetaListIdents_ | `macro_use(foo, bar)`
 _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")`
 
-## Active and inert attributes
-
 r[attributes.activity]
+## Active and inert attributes
 
 r[attributes.activity.intro]
 An attribute is either active or inert. During attribute processing, *active
@@ -201,9 +199,8 @@ The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is
 inert when compiling for tests and active otherwise. [Attribute macros] are
 active. All other attributes are inert.
 
-## Tool attributes
-
 r[attributes.tool]
+## Tool attributes
 
 r[attributes.tool.intro]
 The compiler may allow attributes for external tools where each tool resides
@@ -234,9 +231,8 @@ pub fn f() {}
 > Note: `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic",
 > "miri" and "rust_analyzer".
 
-## Built-in attributes index
-
 r[attributes.builtin]
+## Built-in attributes index
 
 The following is an index of all built-in attributes.
 

src/attributes/codegen.md

@@ -1,12 +1,11 @@
+r[attributes.codegen]
 # Code generation attributes
 
-r[attributes.codegen]
 
 The following [attributes] are used for controlling code generation.
 
-## Optimization hints
-
 r[attributes.codegen.hint]
+## Optimization hints
 
 r[attributes.codegen.hint.cold-inline]
 The `cold` and `inline` [attributes] give suggestions to generate code in a
@@ -19,9 +18,8 @@ Both attributes can be used on [functions]. When applied to a function in a
 a trait implementation and not to all trait implementations. The attributes
 have no effect on a trait function without a body.
 
-### The `inline` attribute
-
 r[attributes.codegen.inline]
+### The `inline` attribute
 
 r[attributes.codegen.inline.intro]
 The *`inline` [attribute]* suggests that a copy of the attributed function
@@ -44,24 +42,23 @@ There are three ways to use the inline attribute:
 > ***Note***: `#[inline]` in every form is a hint, with no *requirements*
 > on the language to place a copy of the attributed function in the caller.
 
+r[attributes.codegen.cold]
 ### The `cold` attribute
 
-r[attributes.codegen.cold]
 
 The *`cold` [attribute]* suggests that the attributed function is unlikely to
 be called.
 
+r[attributes.codegen.no_builtins]
 ## The `no_builtins` attribute
 
-r[attributes.codegen.no_builtins]
 
 The *`no_builtins` [attribute]* may be applied at the crate level to disable
 optimizing certain code patterns to invocations of library functions that are
 assumed to exist.
 
-## The `target_feature` attribute
-
 r[attributes.codegen.target_feature]
+## The `target_feature` attribute
 
 r[attributes.codegen.target_feature.intro]
 The *`target_feature` [attribute]* may be applied to a function to
@@ -90,15 +87,15 @@ Functions marked with `target_feature` are not inlined into a context that
 does not support the given features. The `#[inline(always)]` attribute may not
 be used with a `target_feature` attribute.
 
+r[attributes.codegen.target_feature.availability]
 ### Available features
 
-r[attributes.codegen.target_feature.availability]
 
 The following is a list of the available feature names.
 
+r[attributes.codegen.target_feature.x86]
 #### `x86` or `x86_64`
 
-r[attributes.codegen.target_feature.x86]
 
 Executing code with unsupported features is undefined behavior on this platform.
 Hence this platform requires that `#[target_feature]` is only applied to [`unsafe`
@@ -165,9 +162,9 @@ Feature     | Implicitly Enables | Description
 [`xsaveopt`]: https://www.felixcloutier.com/x86/xsaveopt
 [`xsaves`]: https://www.felixcloutier.com/x86/xsaves
 
+r[attributes.codegen.target_feature.aarch64]
 #### `aarch64`
 
-r[attributes.codegen.target_feature.aarch64]
 
 This platform requires that `#[target_feature]` is only applied to [`unsafe`
 functions][unsafe function].
@@ -230,9 +227,9 @@ Feature        | Implicitly Enables | Feature Name
 `tme`          |                | FEAT_TME --- Transactional Memory Extension
 `vh`           |                | FEAT_VHE --- Virtualization Host Extensions
 
+r[attributes.codegen.target_feature.riscv]
 #### `riscv32` or `riscv64`
 
-r[attributes.codegen.target_feature.riscv]
 
 This platform requires that `#[target_feature]` is only applied to [`unsafe`
 functions][unsafe function].
@@ -292,9 +289,9 @@ Feature     | Implicitly Enables  | Description
 [rv-zksh]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zksh.adoc
 [rv-zkt]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zkt.adoc
 
+r[attributes.codegen.target_feature.wasm]
 #### `wasm32` or `wasm64`
 
-r[attributes.codegen.target_feature.wasm]
 
 `#[target_feature]` may be used with both safe and
 [`unsafe` functions][unsafe function] on Wasm platforms. It is impossible to
@@ -327,9 +324,8 @@ Feature               | Implicitly Enables  | Description
 [tail-call]: https://github.com/webassembly/tail-call
 [multivalue]: https://github.com/webassembly/multi-value
 
-### Additional information
-
 r[attributes.codegen.target_feature.info]
+### Additional information
 
 r[attributes.codegen.target_feature.remark-cfg]
 See the [`target_feature` conditional compilation option] for selectively
@@ -346,9 +342,8 @@ in the standard library for runtime feature detection on these platforms.
 > may be enabled or disabled for an entire crate with the
 > [`-C target-feature`] flag.
 
-## The `track_caller` attribute
-
 r[attributes.codegen.track_caller]
+## The `track_caller` attribute
 
 r[attributes.codegen.track_caller.allowed-positions]
 The `track_caller` attribute may be applied to any function with [`"Rust"` ABI][rust-abi]
@@ -364,9 +359,9 @@ implementations, otherwise undefined behavior results. When applied to a functio
 available to an `extern` block, the declaration in the `extern` block must also have the attribute,
 otherwise undefined behavior results.
 
+r[attributes.codegen.track_caller.behavior]
 ### Behavior
 
-r[attributes.codegen.track_caller.behavior]
 Applying the attribute to a function `f` allows code within `f` to get a hint of the [`Location`] of
 the "topmost" tracked call that led to `f`'s invocation. At the point of observation, an
 implementation behaves as if it walks up the stack from `f`'s frame to find the nearest frame of an
@@ -444,9 +439,8 @@ fn calls_h() {
 
 And so on.
 
-### Limitations
-
 r[attributes.codegen.track_caller.limits]
+### Limitations
 
 r[attributes.codegen.track_caller.hint]
 This information is a hint and implementations are not required to preserve it.
@@ -480,9 +474,8 @@ trait object whose methods are attributed.
 [rust-abi]: ../items/external-blocks.md#abi
 [`Location`]: core::panic::Location
 
-## The `instruction_set` attribute
-
 r[attributes.codegen.instruction_set]
+## The `instruction_set` attribute
 
 r[attributes.codegen.instruction_set.allowed-positions]
 The *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for.
@@ -498,9 +491,9 @@ It uses the [_MetaListPath_] syntax, and a path comprised of the architecture fa
 r[attributes.codegen.instruction_set.target-limits]
 It is a compilation error to use the `instruction_set` attribute on a target that does not support it.
 
+r[attributes.codegen.instruction_set.arm]
 ### On ARM
 
-r[attributes.codegen.instruction_set.arm]
 
 For the `ARMv4T` and `ARMv5te` architectures, the following are supported:
 * `arm::a32` --- Generate the function as A32 "ARM" code.

src/attributes/debugger.md

@@ -1,12 +1,11 @@
+r[attributes.debugger]
 # Debugger attributes
 
-r[attributes.debugger]
 
 The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or WinDbg.
 
-## The `debugger_visualizer` attribute
-
 r[attributes.debugger.debugger_visualizer]
+## The `debugger_visualizer` attribute
 
 r[attributes.debugger.debugger_visualizer.intro]
 The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information.
@@ -15,9 +14,8 @@ This enables an improved debugger experience for displaying values in the debugg
 r[attributes.debugger.debugger_visualizer.syntax]
 It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute.
 
-### Using `debugger_visualizer` with Natvis
-
 r[attributes.debugger.debugger_visualizer.natvis]
+### Using `debugger_visualizer` with Natvis
 
 r[attributes.debugger.debugger_visualizer.natvis.intro]
 Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types.
@@ -82,9 +80,8 @@ When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
     > LowerRight: (15.0, 10.0)
 ```
 
-### Using `debugger_visualizer` with GDB
-
 r[attributes.debugger.debugger_visualizer.gdb]
+### Using `debugger_visualizer` with GDB
 
 r[attributes.debugger.debugger_visualizer.gdb.pretty]
 GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view.
@@ -156,9 +153,8 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil
 [pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 
-## The `collapse_debuginfo` attribute
-
 r[attributes.debugger.collapse_debuginfo]
+## The `collapse_debuginfo` attribute
 
 r[attributes.debugger.collapse_debuginfo.intro]
 The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site,

src/attributes/derive.md

@@ -1,6 +1,5 @@
-# Derive
-
 r[attributes.derive]
+# Derive
 
 r[attributes.derive.intro]
 The *`derive` attribute* allows new [items] to be automatically generated for
@@ -36,9 +35,9 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 r[attributes.derive.proc-macro]
 You can implement `derive` for your own traits through [procedural macros].
 
+r[attributes.derive.automatically_derived]
 ## The `automatically_derived` attribute
 
-r[attributes.derive.automatically_derived]
 The *`automatically_derived` attribute* is automatically added to
 [implementations] created by the `derive` attribute for built-in traits. It
 has no direct effect, but it may be used by tools and diagnostic lints to

src/attributes/diagnostics.md

@@ -1,13 +1,11 @@
-# Diagnostic attributes
-
 r[attributes.diagnostics]
+# Diagnostic attributes
 
 The following [attributes] are used for controlling or generating diagnostic
 messages during compilation.
 
-## Lint check attributes
-
 r[attributes.diagnostics.lint]
+## Lint check attributes
 
 A lint check names a potentially undesirable coding pattern, such as
 unreachable code or omitted documentation.
@@ -104,9 +102,9 @@ pub mod m3 {
 > [command-line][rustc-lint-cli], and also supports [setting
 > caps][rustc-lint-caps] on the lints that are reported.
 
+r[attributes.diagnostics.lint.reason]
 ### Lint Reasons
 
-r[attributes.diagnostics.lint.reason]
 All lint attributes support an additional `reason` parameter, to give context why
 a certain attribute was added. This reason will be displayed as part of the lint
 message if the lint is emitted at the defined level.
@@ -141,9 +139,8 @@ pub fn get_path() -> PathBuf {
 }
 ```
 
-### The `#[expect]` attribute
-
 r[attributes.diagnostics.expect]
+### The `#[expect]` attribute
 
 r[attributes.diagnostics.expect.intro]
 The `#[expect(C)]` attribute creates a lint expectation for lint `C`. The
@@ -228,9 +225,9 @@ pub fn another_example() {
 > Note: The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently
 > defined to always generate the `unfulfilled_lint_expectations` lint.
 
+r[attributes.diagnostics.lint.group]
 ### Lint groups
 
-r[attributes.diagnostics.lint.group]
 Lints may be organized into named groups so that the level of related lints
 can be adjusted together. Using a named group is equivalent to listing out the
 lints within that group.
@@ -269,9 +266,8 @@ fn example_err() {
 }
 ```
 
-### Tool lint attributes
-
 r[attributes.diagnostics.lint.tool]
+### Tool lint attributes
 
 r[attributes.diagnostics.lint.tool.intro]
 Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid`
@@ -303,9 +299,8 @@ fn foo() {
 
 > Note: `rustc` currently recognizes the tool lints for "[clippy]" and "[rustdoc]".
 
-## The `deprecated` attribute
-
 r[attributes.diagnostics.deprecated]
+## The `deprecated` attribute
 
 r[attributes.diagnostics.deprecated.intro]
 The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue
@@ -350,9 +345,8 @@ The [RFC][1270-deprecation.md] contains motivations and more details.
 
 [1270-deprecation.md]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md
 
-## The `must_use` attribute
-
 r[attributes.diagnostics.must_use]
+## The `must_use` attribute
 
 r[attributes.diagnostics.must_use.intro]
 The *`must_use` attribute* is used to issue a diagnostic warning when a value
@@ -469,9 +463,8 @@ When used on a function in a trait implementation, the attribute does nothing.
 > let _ = five();
 > ```
 
-## The `diagnostic` tool attribute namespace
-
 r[attributes.diagnostic.namespace]
+## The `diagnostic` tool attribute namespace
 
 r[attributes.diagnostic.namespace.intro]
 The `#[diagnostic]` attribute namespace is a home for attributes to influence compile-time error messages.
@@ -482,9 +475,8 @@ Unknown attributes in this namespace are accepted, though they may emit warnings
 Additionally, invalid inputs to known attributes will typically be a warning (see the attribute definitions for details).
 This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working.
 
-### The `diagnostic::on_unimplemented` attribute
-
 r[attributes.diagnostic.on_unimplemented]
+### The `diagnostic::on_unimplemented` attribute
 
 r[attributes.diagnostic.on_unimplemented.intro]
 The `#[diagnostic::on_unimplemented]` attribute is a hint to the compiler to supplement the error message that would normally be generated in scenarios where a trait is required but not implemented on a type.