From f104f853a637ee3a197d6094f362e45ed64f4d27 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Wed, 4 Nov 2015 13:09:16 -0500 Subject: [PATCH] man/stap.1: hold forth on DEPRECATION Explain that our deprecation is done for the users' benefit. --- man/stap.1 | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/man/stap.1 b/man/stap.1 index 6cd48786a..57e6983d7 100644 --- a/man/stap.1 +++ b/man/stap.1 @@ -2262,6 +2262,22 @@ systemtap with the flag will output a warning if any possible incompatible elements have been parsed. Deprecation historical details may be found in the NEWS file. +The purpose of deprecation facility is to improve the experience of +scripts written for newer versions of systemtap (by adding better +alternatives and removing conflicting or messy older alternatives), +while at the same time permitting scripts written for older versions +of systemtap to continue running. Deprecation is thus intended a +.I service to users +(and an inconvenience to systemtap's developers), rather than the +other way around. + +Please note that underscore-prefixed identifiers in the tapset +sometimes undergo such changes that are difficult to preserve +compatibility for, even with the deprecation mechanisms. Avoid +relying on these in your scripts; instead propose them for promotion +to non-underscored status. + + .SH FILES .TP Important files and their corresponding paths can be located in the -- 2.43.5