help: add new deprecated topic

Add a deprecated topic which lists most of the commands and options that are not
recommended anymore.

mercurial/help/deprecated.txt

@@ -0,0 +1,30 b''
+Mercurial evolves over time, some features, options, commands may be replaced by
+better and more secure alternatives. This topic will help you migrating your
+existing usage and/or configuration to newer features.
+
+Commands
+========
+
+The following commands are still available but their use are not recommended:
+
+``locate``
+
+This command has been replaced by `hg files`.
+
+``parents``
+
+This command can be replaced by `hg summary` or `hg log` with appropriate
+revsets. See `hg help revsets` for more information.
+
+``tip``
+
+The recommended alternative is `hg heads`.
+
+Options
+=======
+
+``web.allowpull``
+    Renamed to `allow-pull`.
+
+``web.allow_push``
+    Renamed to `allow-push`.

contrib/wix/help.wxs

@@ -19,6 +19,7 b''
           <File Name="color.txt" />
           <File Name="config.txt" KeyPath="yes" />
           <File Name="dates.txt" />
+          <File Name="deprecated.txt" />
           <File Name="diffs.txt" />
           <File Name="environment.txt" />
           <File Name="extensions.txt" />

mercurial/help.py

@@ -232,6 +232,7 b' helptable = sorted(['
     (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
     (['color'], _("Colorizing Outputs"), loaddoc('color')),
     (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
+    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated')),
     (["dates"], _("Date Formats"), loaddoc('dates')),
     (["flags"], _("Command-line flags"), loaddoc('flags')),
     (["patterns"], _("File Name Patterns"), loaddoc('patterns')),

tests/test-globalopts.t

@@ -353,6 +353,7 b' Testing -h/--help:'
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
+   deprecated    Deprecated Features
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
@@ -436,6 +437,7 b' Testing -h/--help:'
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
+   deprecated    Deprecated Features
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features

tests/test-help.t

@@ -110,6 +110,7 b' the extension is unknown.'
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
+   deprecated    Deprecated Features
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
@@ -189,6 +190,7 b' the extension is unknown.'
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
+   deprecated    Deprecated Features
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
@@ -889,6 +891,7 b' Test that default list of commands omits'
    color         Colorizing Outputs
    config        Configuration Files
    dates         Date Formats
+   deprecated    Deprecated Features
    diffs         Diff Formats
    environment   Environment Variables
    extensions    Using Additional Features
@@ -2032,6 +2035,13 b' Dish up an empty repo; serve it cold.'
   Date Formats
   </td></tr>
   <tr><td>
+  <a href="/help/deprecated">
+  deprecated
+  </a>
+  </td><td>
+  Deprecated Features
+  </td></tr>
+  <tr><td>
   <a href="/help/diffs">
   diffs
   </a>

tests/test-hgweb-json.t

@@ -1914,6 +1914,10 b' help/ shows help topics'
         "topic": "dates"
       },
       {
+        "summary": "Deprecated Features",
+        "topic": "deprecated"
+      },
+      {
         "summary": "Diff Formats",
         "topic": "diffs"
       },