marking stuff deprecated in documentation

[Neil Van Dyke]

There's still a problem of people stumbling upon deprecated stuff in the
Racket manuals, and going to a lot of trouble to use it without
realizing that it's deprecated.

For a very quick fix, how about appending "[DEPRECATED]" to certain
manual titles, as an easy way of marking each page of the manual?

For example, the title: "PLaneT: Automatic Package Distribution"
is changed to: "PLaneT: Automatic Package Distribution [DEPRECATED]"

This could also be done to individual "compatibility" chapters/section
headers of otherwise non-deprecated manuals.

Also, move things like the PLaneT manual to the "Legacy Languages and
Libraries" category. Maybe append "[DEPRECATED]" to the titles of the
other manuals in that category, as well.

Neil V.

[Alexis King]

I know this is at least somewhat orthogonal to the points you’ve made, but perhaps it would be best to standardize how “warning” messages are rendered in documentation. For example, the “unstable: may change without warning” messages are quite useful, but I have no idea how I’d render those in my own documentation.

> --
> You received this message because you are subscribed to the Google Groups "Racket Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to racket-dev+...@googlegroups.com.
> To post to this group, send email to racke...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/561C49EF.3010805%40neilvandyke.org.
> For more options, visit https://groups.google.com/d/optout.

[Greg Hendershott]

Only recently did I learn about and start to use `history`:

http://docs.racket-lang.org/scribble/Version_History.html

This could be used as-is with the `#:changed` clause:

@history[#:changed "1.7"]{Deprecated. Instead use @racket[shiny-thing].}

But now that you mention it, a new explicit `#:deprecated` clause
would be useful. Ideally it could render such that the CSS could style
it more dramatically.

> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/842B8014-65AB-4D62-8380-46F60E7756A1%40gmail.com.

[Vincent St-Amour]

Someone correct me if I'm wrong, but my understanding is that, in the
context of Racket at least, "deprecated" implies that we will be
removing that code in the near-ish future. As we recently did for, e.g.,
class100.

My understanding is also that we don't want to remove things like
mzscheme, mzlib, planet, or compatibility. So using the above definition
of deprecated, we don't want to deprecate those.

With that said, though, I very much agree with your sentiment: we should
have a clear way of signaling that people shouldn't use those. As we've
learned from the "unstable" collection, even large warnings are not
enough for that if there's valuable stuff in there.

With the package system, however, it's possible to remove code from the
main distribution without breaking code that depends on it (it just
needs the right dependencies). So it should be possible to essentially
do the same for the compatibility-lib package (which contains most of
the things I suspect you'd want to deprecate) as we did for the
unstable family of packages, and move it out of the main distribution.
In the process, we can move the last few bits of useful functionality
that exists in these collections, but not in more modern Racket
equivalents.

If we do that, then most people won't have that package installed, it
won't show up when they search the docs, and we win. And we can do that
without breaking anyone's code (assuming they have the proper
dependencies already).

(That may be trickier to do with planet, though, as I think it may be
embedded pretty deeply into our toolchain.)

Doing that for compatibility-lib and other non-recommended libraries
(like srfis) is on my to-do list, but not currently on the top.

Vincent

[Greg Hendershott]

Oh then maybe I'm misunderstanding "deprecated".

I was thinking of it from the narrow/selfish point of view of a (new
system) package developer. In that system, deprecated can't mean "will
be removed soon", because you can't ever remove things from a package.
(Packages are supposed to be backward compatible, even with a new
major version number. If you want to remove stuff, you're supposed to
make another package. (I'm not trying to re-open that discussion, now,
just follow the status quo.))

So I was thinking of it as purely advice/admonition: "Starting with
version N, you ought to use Shiny instead of Finicky." However,
Finicky will remain forever in that package per se.

I don't know whether that's "deprecated" or not, but it's a thing.

I'm curious to know the answer to Alexis' question: Semantics aside,
how do I simply make something with a standard warning appearance? In
many cases that's probably sufficient. I went looking for examples of
this in the docs, so I could go look for its Scribble. But I couldn't
find any. Alexis do you have a link to an example?

> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/m2twpupy61.wl-stamourv%40eecs.northwestern.edu.

[Alexis King]

> I'm curious to know the answer to Alexis' question: Semantics aside,
> how do I simply make something with a standard warning appearance? In
> many cases that's probably sufficient. I went looking for examples of
> this in the docs, so I could go look for its Scribble. But I couldn't
> find any. Alexis do you have a link to an example?

Originally I thought what I was thinking of was in unstable/, but I realized I was incorrect. What I was actually thinking of was mzlib. For example, take a look at the deprecation warning at the top of this page:

http://mirror.racket-lang.org/releases/6.2.1/doc/mzlib/mzlib_class.html

The distinguishing characteristics are the indentation and, of course, the big yellow “NOTE” in front of everything.

[Sam Tobin-Hochstadt]

The warning is generated by `deprecated`, from `scribble/manual`.

Sam

On Tue, Oct 13, 2015 at 3:50 PM, Alexis King <lexi....@gmail.com> wrote:
>> I'm curious to know the answer to Alexis' question: Semantics aside,
>> how do I simply make something with a standard warning appearance? In
>> many cases that's probably sufficient. I went looking for examples of
>> this in the docs, so I could go look for its Scribble. But I couldn't
>> find any. Alexis do you have a link to an example?
>

> Originally I thought what I was thinking of was in unstable/, but I realized I was incorrect. What I was actually thinking of was mzlib. For example, take a look at the deprecation warning at the top of this page:
>
> http://mirror.racket-lang.org/releases/6.2.1/doc/mzlib/mzlib_class.html
>
> The distinguishing characteristics are the indentation and, of course, the big yellow “NOTE” in front of everything.
>

> --
> You received this message because you are subscribed to the Google Groups "Racket Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to racket-dev+...@googlegroups.com.
> To post to this group, send email to racke...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/F237DB13-1CA2-4414-A074-ADFDCF02B8D7%40gmail.com.