Long markdown links are brought inline, forcing extra space and becoming less readable

[detly]

OS: Ubuntu 22.10
Toolchain: stable-x86_64-unknown-linux-gnu
Cargo: 1.65.0
Rustc: 1.65.0
genemichaels: v0.1.9

Start with this code (just cribbed from one of my projects):

//! If that's what you have and it works, you don't need this crate at all — you
//! can just use [`CARGO_BIN_EXE_<name>`][cargo-env].
//!
//!   [cargo-env]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates

pub struct Foo;

impl Foo {
    pub fn do_stuff() {
        fn get_cargo_env_or_panic(key: &str) -> std::ffi::OsString {
            std::env::var_os(key).unwrap_or_else(||
                panic!("The environment variable '{key}' is not set, is this running under a 'cargo test' command?")
            )
        }

        get_cargo_env_or_panic("");
    }
}

After running genemichaels -w -l 100 src/lib.rs, I get:

//! If that's what you have and it works, you don't need this crate at all — you can
//! just use [`CARGO_BIN_EXE_<name>`
//! ](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
//! .
pub struct Foo;

impl Foo {
    pub fn do_stuff() {
        fn get_cargo_env_or_panic(key: &str) -> std::ffi::OsString {
            std::env::var_os(
                key,
            ).unwrap_or_else(
                || panic!(
                    "The environment variable '{key}' is not set, is this running under a 'cargo test' command?"
                ),
            )
        }

        get_cargo_env_or_panic("");
    }
}

I'm impressed that it at least made an effort to pull the panic! line in a bit (now 113 chars instead of 121). But in my entirely subjective opinion the markdown formatting is worse - I took the super long link out of the text so that the sentence was more readable, and now it's back in, breaking the text flow for a line and a half. More objectively, I think this will result in whitespace between the last word of the sentence and the full-stop, where there was none before, changing the rendered text as well.

I have seen comments that claim that Markdown can support breaking long URLs, but I have no idea how.

Related: Rustfmt #5477.

(Saw this project via Reddit so I thought I'd try it out and file issues for you! Great work!)

[andrewbaxter]

Thanks, yeah, that's a good point. So right now a lot of the markdown changes are done implicitly by pulldown_cmark - I'll see if I can figure out how to keep the footnote links separate since joining it wasn't actually my intention.

[andrewbaxter]

Erk, looks like we lose the reference id in pulldown_cmark: pulldown-cmark/pulldown-cmark#434

Options are make up new reference ids (how important are they? I could generate like ref1 ref2 etc) or switch markdown libraries at this point, since that issue is a couple years old now.

[andrewbaxter]

I switched to https://github.com/wooorm/markdown-rs which seems to be doing a decent job. I'll release this with a couple other small fixes I noticed in a bit (0.1.11).

FWIW I've noticed it kind of normalizing "collapsed" references like

[`ICU4X`]
...
[`ICU4X`]: https://...

to

[`ICU4X`][`icu4x`]
...
[`icu4x`]: https://...

I'm assuming there's a reason for that, but it may need to be revisited. At least it's not a regression...

Feel free to reopen if this doesn't work as expected!