Repository: rust
Issue: Alternative highlighting for Rust code block in rustdoc
Labels: T-rustdoc,C-feature-request,A-markdown-parsing

Context https://twitter.com/imperioworld_/status/1325916530257833984 cc @GuillaumeGomez 

# Description

I'm the author of https://github.com/Hywan/inline-c-rs/. It allows to write C code inside Rust. It's a super basic `proc_macro` that transforms the code into a string (with some extra manipulations), which is saved inside a temp file that is compiled by a C/C++ compiler, and finally run. That's useful for testing C API of a Rust program inside Rust with the Rust tooling (like `cargo test`). It is super useful for us at https://github.com/wasmerio/wasmer.

Recently, we pushed the concept further: Using `inline-c-rs` inside documentation, like this:

```rust
/// Blah blah blah.
///
/// # Examples
///
/// ```rust
/// # use inline_c::assert_c;
/// # fn main() {
/// #    (assert_c! {
/// # #include "tests/wasmer_wasm.h"
/// #
/// int main() {
///     wasm_engine_t* engine = wasm_engine_new();
///     wasm_store_t* store = wasm_store_new(engine);
///
///     // etc.
///    
///     return 0;
/// }
/// #    })
/// #    .success();
/// # }
/// ```
#[no_mangle]
pub unsafe extern "C" fn wasm_module_new(/* skipped */) -> /* skipped */ {
    // skipped
}
```

This documentation is:

* ✅ written in Rust, and contains C,
* ✅ is **tested** by `cargo test --doc` because the code block is tagged with <code>```rust</code> … so we can test C with `cargo test` 🤪!
* ✅ is **compiled to HTML** by `rustdoc`.

The result of `cargo doc` looks like this:

![Screenshot 2020-11-06 at 11 40 44](https://user-images.githubusercontent.com/946104/98651071-0b530e80-233a-11eb-85e9-82730674a6f7.png)

That's excellent! All the “Rust decoration” is “removed” (thanks to `# …`), and only the C code stays. That's insane I know, but it works and that's super fun.

One problem though:

* ❌ The highlighting is incorrect.

Because it's a <code>```rust</code> code block, there is a special handler for that I assume. I tried to write `rust,language-c` but the `language-c` part is ignored and is not present in the generated HTML code, as it can be seen here:

```html
<pre class="rust rust-example-rendered">
```

# Expectation

I would expect <code>```rust</code> to be a special keyword that unfolds to `rust` + `language-rust`:

* The former describes that it's a Rust code block, and consequently is a candidate for a test,
* The second describes the syntax highlighting ruleset to apply for the HTML documentation.

This keyword could have a different meaning in the presence of `language-<lang_id>` which “cancels” `language-rust`.

In other words, writing `rust,language-c` would keep the actual behavior of `rust` but it will disable the default highlighting to allow the user to define another one.

How does it sound?

# Motivation

The technique used by `inline-c-rs` can be ported to other languages. It's just super fun to see C code inside Rust documentation that is also tested by `cargo doc`. I'm sure this technique can be used by other languages in the future.

<!-- TRIAGEBOT_START -->

<!-- TRIAGEBOT_ASSIGN_START -->

<!-- TRIAGEBOT_ASSIGN_DATA_START$${"user":"poliorcetics"}$$TRIAGEBOT_ASSIGN_DATA_END -->

<!-- TRIAGEBOT_ASSIGN_END -->
<!-- TRIAGEBOT_END -->