Merged revisions 82871,82960-82961 via svnmerge from
svn+ssh://svn.python.org/python/branches/py3k

........
  r82871 | georg.brandl | 2010-07-14 10:00:22 +0200 (Mi, 14 Jul 2010) | 1 line

  #9258: fix copy-paste errors.
........
  r82960 | georg.brandl | 2010-07-19 08:52:35 +0200 (Mo, 19 Jul 2010) | 1 line

  Clarify.
........
  r82961 | georg.brandl | 2010-07-19 08:57:52 +0200 (Mo, 19 Jul 2010) | 1 line

  Clarify :option: description.
........
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index dd33e81..34a79d4 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -502,8 +502,9 @@
 
 .. describe:: option
 
-   A command-line option to an executable program.  The leading hyphen(s) must
-   be included.
+   A command-line option of Python.  The leading hyphen(s) must be included.
+   If a matching ``cmdoption`` directive exists, it is linked to.  For options
+   of other programs or scripts, use simple ````code```` markup.
 
 .. describe:: program