Stream: rustdoc

Topic: warning sections in rustdoc: #79677


view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:38):

For me it's another debate. In the end, we still want to generate his HTML which needs to be present before we even add the syntax extension. I think it's two different issues.

@GuillaumeGomez this misses my point - if we add this CSS, people will immediately start using the HTML class

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:38):

if you want to add this you should add a feature gate for the rustdoc-warning CSS class, which sounds really painful to do, you'd need a full HTML parser

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:40):

Is that an issue? The problem they were talking about was about the syntax extension, not the CSS itself. But maybe I completely missed the point. It's friday evening after all XD

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:40):

now I'm mostly ok with landing another syntax (e.g. WARNING:) and having class="rustdoc-warning" work as a side effect, but the difference is that rustdoc-warning wouldn't be stable

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:40):

right now we've documented that the CSS class will never change and is part of the stability guarentees

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:41):

Ok, I'll write what I understood, you'll tell me how wrong/right I am :p

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:45):

So, this PR adds the possibility to have codeblocks added and the associated CSS class. We checked with docs-rs to prevent CSS class conflicts. On that part, it seems all good.

We then asked opinions from rustdoc users, they said that using HTML directly was not nice and suggested to extend doc comments syntax. So once this syntax extension is decided, we'll still need to generate the <div class="rustdoc-warning"> element.

But where I'm lost, it's that you seem to say that if we don't know about the doc comment syntax extension, we can't add the <div class="rustdoc-warning">. To be clear: this HTML doesn't require anything on our side. We declared the CSS class and made it work only on <div>. It doesn't exclude the syntax extension at all. Which is why I don't understand what's troubling you

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

what troubles me is that this stabilizes the CSS class

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

does any other part of rustdoc explicitly say it generates HTML like that?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:47):

Well, we need the CSS class in any case, no?

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

what does this mean for the JSON backend?

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

what does this mean if someone writes a PDF viewer based on the JSON backend?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:47):

the JSON backend doesn't (shouldn't?) care about that

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

the CSS should be an implemnetation detail, not documented

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:47):

GuillaumeGomez said:

the JSON backend doesn't (shouldn't?) care about that

why not? That seems like a great thing to show in the documentation, even in other formats

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:48):

yes and if we stick to markdown, the problem doesn't even exist

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:49):

I don't follow, sorry

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:50):

sorry, not good at explaining

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:50):

you can already use html directly with classes specific to rustdoc

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:51):

if you use JSON, maybe you want to only list your items or have another renderer, no idea

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:51):

GuillaumeGomez said:

you can already use html directly with classes specific to rustdoc

you can?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:51):

but it's not up to us to care about what others do with the JSON

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:51):

that really makes the JSON a second-class citizen :/

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:51):

we're not making all the information available to it

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:52):

of course you, you can put html in doc comments because markdown allows it, so as long as the class exists in the CSS, what prevents you to not use it?

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:52):

oh I see what you mean

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:52):

the difference is that isn't stabilized

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:52):

it's just an artifact of how rustdoc is implemented

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:52):

what do you mean?

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:52):

we could change the CSS classes without considering it a breaking change

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:52):

(or at least, I would be strongly opposed to considering that breaking change)

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:53):

basically my fear is that we're locking ourselves in to a specific implementation

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:54):

well, we have to in a way

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:55):

otherwise, we'd break docs.rs too

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:55):

UI changes can only be small and one at a time

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:55):

I don't see how this is related to docs.rs

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:55):

docs.rs isn't adding any documentation with class="rustdoc-warning"

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:55):

and I wouldn't consider it to need the same stability guarentees as library authors

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:56):

yep, but it's officially documented as an "add"

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:57):

I don't follow

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:57):

friday evening makes me bad with talks, sorry XD

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:57):

we can wait until next week if you like :smile:

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:57):

so, in any case, in your JSON you'll have the rustdoc-warning tag

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:58):

we can assume they'll have a markdown parser

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:58):

since the rustdoc-warning class is documented, they can handle it

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:58):

well now they need to have an HTML parser too :/

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:58):

the two are not the same, pulldown does not handle HTML

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:58):

so my question is: why would you want to change this class? The display is not related to the JSON

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:58):

pulldown handles HTML

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:58):

pulldown does not parse HTML

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:59):

it doesn't display it, which is totally different

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 21:59):

html is part of markdown spec

view this post on Zulip Joshua Nelson (Dec 04 2020 at 21:59):

https://github.com/raphlinus/pulldown-cmark/issues/484#issuecomment-698964416

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:00):

Ah no, it's different

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:00):

pulldown just say "I saw something which looks like an HTML tag and marked it as such"

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:00):

but that's it

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:01):

it's not parsing the HTML so to speak

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:01):

right, that's what I mean

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:02):

we can already add html in markdown, JSON output already has to deal with it

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:02):

well, I guess this is more of a principle of the thing, but right now the HTML is just an implementation detail

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:02):

we don't recommend that you use HTML

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:04):

Euuuuh... Well, we definitely recommend it XD

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:05):

well, no

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:05):

badly phrased it

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:05):

we don't say anything about it, except that it's supported and working

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:05):

right exactly

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:05):

it's an implementation detail

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:06):

not really, it's a whole part of markdown

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:06):

and in this case, we need to have this HTML element before we can add the syntax extension (because in the end, the extension will generate this HTML)

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:06):

but yes, in the end, the markdown will look better with an extension

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:07):

GuillaumeGomez said:

and in this case, we need to have this HTML element before we can add the syntax extension (because in the end, the extension will generate this HTML)

I understand that, you keep saying it, but it's not at all related to stabilizing the HTML element

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:07):

which is the bit I'm concerned about

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:07):

however, please keep in mind that using a rustdoc-specific extension will also have a cost for people using the JSON output

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:08):

right, yes, you have to parse the extension

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:08):

but it's possible rustdoc could expose it in the JSON at some point

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:08):

well, if the problem is that it's being put too much forward, I can remove the doc about it so that we'll only talk about it once we have the syntax extension. I'm fine with it too haha

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:08):

without having to add an HTML parser of its own

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:08):

ok great :)

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:09):

then we don't need the fcp anymore I guess?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:11):

Still remain the big unknown: what will the syntax extension look like?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:11):

on that point, I really have no suggestion...

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:16):

I liked the WARNING: suggestion

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:18):

I don't because it doesn't have a clear separation from the end of the text

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:19):

we could use a line break as the separation

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:19):

that's consistent with how it's normally used I think

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:20):

I don't have a strong opinion on this to be honest. Whatever people mostly prefer, I'll implement it. My only condition is: it has to be fully markdown compliant

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:20):

otherwise, the JSON output will be screwed

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:20):

'markdown compliant' doesn't mean a lot since all text is valid markdown :laughing:

view this post on Zulip Joshua Nelson (Dec 04 2020 at 22:20):

what do you mean by that?

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:21):

it means not adding esoteric stuff like §§ this is the warning §§

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:21):

it has to remains fully readable even without the rustdoc nice renderin

view this post on Zulip Nixon Enraght-Moony (Dec 04 2020 at 22:22):

Any sequence of characters is a valid CommonMark document.

source

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:23):

let's focus on "remains fully readable" please T_T

view this post on Zulip GuillaumeGomez (Dec 04 2020 at 22:25):

@Joshua Nelson On the meantime, I'm removing the second commit and the fcp since it doesn't have meaning anymore. Do you want to create the new issue or should I?

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:52):

Joshua Nelson said:

pulldown does not parse HTML

@Manish Goregaokar you and I are saying different things when we say parse

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:52):

ah

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:52):

I mean "tell the difference between classes and literal strings", you mean "put the literal string in the output"

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:53):

sure

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:53):

but it's part of the general point i'm making here: whatever the JSON backend is piped to will need to handle HTML regardless

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:53):

Markdown _is_ HTML

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:54):

I guess the difference in my mind is that until now we haven't recommended using raw HTML in markdown

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:54):

We have recommended markdown, raw html is allowed in markdown

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:54):

we also haven't recommended using links in markdown :)

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:54):

https://spec.commonmark.org/0.29/#html-blocks <-- part of the spec

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:54):

i've seen crates using it

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:55):

it gets used a _lot_ for images because markdown image syntax doesn't let you like ... resize them etc

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:55):

so my perspective is that the ship has already sailed

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:55):

yeah that's fair - you're saying consumers of the JSON backend would need something like pandoc no matter what

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:56):

at least to display things the same as rustdoc

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:56):

correct

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:57):

there is _one_ crucial new thing we're introducing: so far unless they're using an external stylesheet, rustdoc markdown can just be rendered faithfully with a standard markdown parser with no frills

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:57):

sure, the codeblocks will not look good, but they'll still exist

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:57):

but the warning block will require additional css

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:57):

i think this is a minor change

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:57):

Now, there is also the whole other concern that from a user's POV they may not want to write HTML

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:58):

but i'm iffy about that because introducing a one-liner syntax is fine until you want more than one line

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:58):

and then it gets super complicated

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:58):

Manish Goregaokar said:

there is _one_ crucial new thing we're introducing: so far unless they're using an external stylesheet, rustdoc markdown can just be rendered faithfully with a standard markdown parser with no frills

I think this is not actually different - the div will still show up without a stylesheet, it just won't look like a warning

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:58):

correct

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:59):

which doesn't seem much different in practice than intra-doc links not showing up if you use a bog-standard markdown parser

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:59):

it's different in that it's possible that the contents of the div may be written in a way that's unclear

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:59):

unless it says WARNING

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 17:59):

ah well i was hoping we would eventually fix that in the json backend

view this post on Zulip Joshua Nelson (Dec 05 2020 at 17:59):

Manish Goregaokar said:

ah well i was hoping we would eventually fix that in the json backend

it works today I think

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:00):

at least, with some assembly

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:00):

it gives you which item the link refers to

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:01):

Manish Goregaokar said:

Now, there is also the whole other concern that from a user's POV they may not want to write HTML

well right, from my perspective I don't think we're actually getting very much if it's just adding a stylesheet

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:02):

users still have to write HTML, you still have to worry about whether it renders properly with rustdoc's stylesheet, and you have this concern about other markdown parsers not rendering it correctly

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 18:03):

you don't have to worry about it rendering properly with rustdoc's stylesheet

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 18:03):

i do think the "users have to write HTML" is valid

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 18:03):

but like, if we are introducing _any_ scoped syntax, they will have to learn it

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 18:03):

anything other than WARNING: will be something with subtleties to learn

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 18:04):

so my take is like this:

- HTML is strictly better than any ad hoc scoped syntax we introduce
- I'm not happy with it being unscoped and restricted to a single line

which makes my position "HTML or not at all"

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:05):

I'm on board with that take, I think that's reasonable

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:05):

so I think we should ask on https://github.com/rust-lang/rust/pull/79677 if people will actually use it if it's HTML

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:05):

since otherwise there's not much point

view this post on Zulip Joshua Nelson (Dec 05 2020 at 18:07):

I can do that now if you like

view this post on Zulip Manish Goregaokar (Dec 05 2020 at 20:06):

I'll post something

view this post on Zulip GuillaumeGomez (Dec 06 2020 at 13:14):

I also think that HTML should enough (it's rare for me and @Manish Goregaokar to agree hehe) but users seem to want a syntax extension too. So maybe we shouldn't close the possibility entirely and wait for them to agree on something (in the boundaries of something acceptable of course) and in the meatime, add the initial HTML we agreed on.


Last updated: Oct 11 2021 at 22:34 UTC