Whole-document visible deprecation #2719
Comments
|
To generalize that, what about adding some kind of emoji to each line in the PEP 0 index? It should describe a different dimension/status than the first column, and we'd have to come up with a taxonomy that makes sense, but it could help gather more information about the PEPs from glancing at the index. (Of course, that emoji could also be carried over into the individual PEPs, and would likely be represented by some metadata tag in the PEP text itself.) |
|
The indicator I thought of is when you have a PDF or something that has big, red, translucent "DRAFT" wording on a slant in the background. |
CAM-Gerlach
added
infra
|
Instead of a new bespoke mechanism, at least for now I suggest just adding new variant(s) of the warning banner implemented in #2702 with appropriate content for each case, and implementing the followup proposal to make it "stick" to the top of the page would make it always visible and very hard to miss, unlike a regular admonition. That approach has the advantage of being flexible and extensible enough to cover the full variety of potential cases here while being prominent, informative and not too disruptive.
Instead of inventing a new dimension, since PEP 1 already displays status codes and groups PEPs by it, we could just introduce an |
|
It could either be hacked around with JS and applying a custom directive or adding the class to some specific body element, or something could be done at build time when reading the appropriate header, but a banner is still very visible while being less disruptive to legitimate readers (since the PEPs still have historical value), we'd have to decide which PEPs qualify and authors might not be too happy about their PEPs being defaced—the banner also provides useful information and a recommended alternative to readers rather than just a blaring warning. |
|
FWIW, it's "fairly" straightforward to have a banner that stays on top of the page. If we pick #2702's banners, it'd be a matter of:
|
|
Oh nice, I didn't expect it to be that simple, since I've had to deal with some fairly complex sticky top bars, but then again it's probably because I'm not an expert like you :). Better yet, we should add a The following JS snippit executed on stickyBanner = document.getElementsByClassName("sticky-banner")[0]
if (stickyBanner) {
style = document.createElement("style")
style.innerHTML = "[id] { scroll-margin-top: " + stickyBanner.offsetHeight + "px; }"
document.head.appendChild(style)
}Only issue is the scroll offset won't adapt to the banner being taller if the viewport is resized to be much narrower after
Oh, somehow I never knew that existed and just hacked together a bunch of JS to do it instead (which was really finicky to get working reliably cross-browser/device). TIL. Though, at the time (several years ago) browser support for it was not as good as it was now, so I might not have been able to rely on it anyway. |
It might need to be a render-blocking JS (for anchor links to have the offset on first render -- I don't know when the browser does the actual scroll though). That isn't the worst thing ever, but may be possible+valuable to avoid? Thinking about this a bit, we may be able to add a class to the |
Oh, right—I recall having to deal with the specifics of this when I was implementing a JS-based solution to this a few years ago before
Yeah, I thought about that too, but the problem is there would be no way to know before the page is rendered what to actually set the scroll margin to, since the directive height could vary substantially depending on its contents, the current viewport width and other factors. I also don't know how easy that would be to add the class to the root document node from inside a directive |
|
Spending some time thinking about this, I think the idea of having a page wide status text in the background is a good way to achieve the goal of avoiding user confusion. The goal of #2992 is to make it easier to see the banners we've added, and showing the status via colours and background text should help as well. The tricky thing, of course, is figuring out if we can do it in a reasonably accessible manner. |
|
See PR #3682 to add directives to add a sticky warning banner. |
|
Merged, but before adding the next batch let's check #3682 (comment) and #3756 (review): do we need the blank line, or can we modify the custom directives somehow? |
|
I've filed #3765 if we want to try to modify the custom directives to use an option instead of an argument for the related links (there's one bikeshedding item in there). |
and others
While discussing the question of updating or superseding/deprecating PEPs, it occurred to me that it would probably be a good idea to display PEPs that aren't active (have been superseded, rejected or otherwise no longer apply) in a way that their status is more apparent than just the one header line at the top, or (like PEP 302) a single note section at the top. If we could have a background text, background colour, floating notice on the side or any kind of visual indication that the text is not authoritative (anymore) even when following a direct link to a section in the PEP, that would be great.
The text was updated successfully, but these errors were encountered: