Fixes SI-4909 and SI-5763

Finally, -sourcepath is split into:
-Ysourcepath     - for the library bootstrapping
-doc-source-path - for scaladoc links to source code

(squished the resident compiler test fix into this commit)

Review by @jsuereth.

16 files changed, 130 insertions, 74 deletions

diff --git a/src/compiler/scala/tools/ant/FastScalac.scala b/src/compiler/scala/tools/ant/FastScalac.scala
index c0d7441ad5..616c93faeb 100644
--- a/src/compiler/scala/tools/ant/FastScalac.scala
+++ b/src/compiler/scala/tools/ant/FastScalac.scala
@@ -100,7 +100,7 @@ class FastScalac extends Scalac {
       List(
         /*scalac*/
         s.bootclasspath, s.classpath, s.extdirs, s.dependencyfile, s.encoding,
-        s.outdir, s.sourcepath,
+        s.outdir, s.Ysourcepath,
         /*fsc*/
         s.server
       ) filter (_.value != "") flatMap (x => List(x.name, x.value))
diff --git a/src/compiler/scala/tools/ant/ScalaMatchingTask.scala b/src/compiler/scala/tools/ant/ScalaMatchingTask.scala
index 2931f481e2..f459075565 100644
--- a/src/compiler/scala/tools/ant/ScalaMatchingTask.scala
+++ b/src/compiler/scala/tools/ant/ScalaMatchingTask.scala
@@ -10,13 +10,20 @@ package scala.tools.ant
 
 import java.io.{ File, InputStream, FileWriter }
 
-import org.apache.tools.ant.{ Task, BuildException }
+import org.apache.tools.ant.{ Task, BuildException, Project }
 import org.apache.tools.ant.taskdefs.MatchingTask
 import org.apache.tools.ant.types.{ Path, Reference }
 
 trait ScalaTask {
   self: Task =>
 
+  /** Logs a warning message from the ant task (such as deprecated warnings) */
+  protected def buildWarning(message: String): Unit = {
+      log("warning:", Project.MSG_WARN)
+      log("  " + message, Project.MSG_WARN)
+      log("", Project.MSG_WARN)
+  }
+
   /** Generates a build error. Error location will be the
    *  current task in the ant file.
    *
diff --git a/src/compiler/scala/tools/ant/Scalac.scala b/src/compiler/scala/tools/ant/Scalac.scala
index a34692f5e0..8dbb737671 100644
--- a/src/compiler/scala/tools/ant/Scalac.scala
+++ b/src/compiler/scala/tools/ant/Scalac.scala
@@ -30,8 +30,8 @@ import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
  *  - `destdir`,
  *  - `classpath`,
  *  - `classpathref`,
- *  - `sourcepath`,
- *  - `sourcepathref`,
+ *  - `Ysourcepath`,
+ *  - `Ysourcepathref`,
  *  - `bootclasspath`,
  *  - `bootclasspathref`,
  *  - `extdirs`,
@@ -61,7 +61,7 @@ import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
  *  It also takes the following parameters as nested elements:
  *  - `src` (for `srcdir`),
  *  - `classpath`,
- *  - `sourcepath`,
+ *  - `Ysourcepath`,
  *  - `bootclasspath`,
  *  - `extdirs`,
  *  - `compilerarg`.
@@ -119,7 +119,7 @@ class Scalac extends ScalaMatchingTask with ScalacShared {
   /** The class path to use for this compilation. */
   protected var classpath: Option[Path] = None
   /** The source path to use for this compilation. */
-  protected var sourcepath: Option[Path] = None
+  protected var Ysourcepath: Option[Path] = None
   /** The boot class path to use for this compilation. */
   protected var bootclasspath: Option[Path] = None
   /** The path to use when finding scalac - *only used for forking!*  */
@@ -253,19 +253,32 @@ class Scalac extends ScalaMatchingTask with ScalacShared {
     createClasspath().setRefid(input)
   }
 
-  /** Sets the `sourcepath` attribute. Used by [[http://ant.apache.org Ant]].
+  // bridge to setYsourcepath
+  @deprecated("The scalac sourcepath attribute is deprecated. Please use ySourcePath instead!")
+  def setSourcepath(input: Path) = {
+    buildWarning("The scalac sourcepath attribute is deprecated. Please use ySourcePath instead!")
+    setYSourcepath(input)
+  }
+
+  @deprecated("The scalac sourcepath attribute is deprecated. Please use ySourcePath instead!")
+  def setSourcepathref(input: Reference) = {
+    buildWarning("The scalac sourcepath attribute is deprecated. Please use ySourcePath instead!")
+    setYSourcepathref(input)
+  }
+
+  /** Sets the `Ysourcepath` attribute. Used by [[http://ant.apache.org Ant]].
    *  @param input The value of `sourcepath`. */
-  def setSourcepath(input: Path) {
-    sourcepath = setOrAppend(sourcepath, input)
+  def setYSourcepath(input: Path) {
+    Ysourcepath = setOrAppend(Ysourcepath, input)
   }
 
   /** Sets the `sourcepath` as a nested sourcepath Ant parameter.
    *  @return A source path to be configured. */
-  def createSourcepath(): Path = createNewPath(sourcepath _, p => sourcepath = p)
+  def createSourcepath(): Path = createNewPath(Ysourcepath _, p => Ysourcepath = p)
 
-  /** Sets the `sourcepath` as an external reference Ant parameter.
+  /** Sets the `docSourcePath` as an external reference Ant parameter.
    *  @param input A reference to a source path. */
-  def setSourcepathref(input: Reference) {
+  def setYSourcepathref(input: Reference) {
     createSourcepath().setRefid(input)
   }
 
@@ -452,10 +465,10 @@ class Scalac extends ScalaMatchingTask with ScalacShared {
     if (destination.isEmpty) buildError("Member 'destination' is empty.")
     else existing(getProject resolveFile destination.get.toString)
 
-  /** Gets the value of the `sourcepath` attribute in a
+  /** Gets the value of the `ySourcepath` attribute in a
    *  Scala-friendly form.
    *  @return The source path as a list of files. */
-  protected def getSourcepath: List[File] = pathAsList(sourcepath, "sourcepath")
+  protected def getSourcepath: List[File] = pathAsList(Ysourcepath, "sourcepath")
 
   /** Gets the value of the `bootclasspath` attribute in a
    *  Scala-friendly form.
@@ -585,10 +598,10 @@ class Scalac extends ScalaMatchingTask with ScalacShared {
     settings.outdir.value = asString(destination.get)
     if (!classpath.isEmpty)
       settings.classpath.value = asString(getClasspath)
-    if (!sourcepath.isEmpty)
-      settings.sourcepath.value = asString(getSourcepath)
+    if (!Ysourcepath.isEmpty)
+      settings.Ysourcepath.value = asString(getSourcepath)
     else if (origin.get.size() > 0)
-      settings.sourcepath.value = origin.get.list()(0)
+      settings.Ysourcepath.value = origin.get.list()(0)
     if (!bootclasspath.isEmpty)
       settings.bootclasspath.value = asString(getBootclasspath)
     if (!extdirs.isEmpty) settings.extdirs.value = asString(getExtdirs)
diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala
index daa08ef8a7..060289640a 100644
--- a/src/compiler/scala/tools/ant/Scaladoc.scala
+++ b/src/compiler/scala/tools/ant/Scaladoc.scala
@@ -27,8 +27,8 @@ import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
  *  - `destdir`,
  *  - `classpath`,
  *  - `classpathref`,
- *  - `sourcepath`,
- *  - `sourcepathref`,
+ *  - `docSourcePath`,
+ *  - `docSourcePathref`,
  *  - `bootclasspath`,
  *  - `bootclasspathref`,
  *  - `extdirs`,
@@ -44,12 +44,12 @@ import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
  *  - `docgenerator`,
  *  - `docrootcontent`,
  *  - `unchecked`,
- *  - `nofail`.
+ *  - `nofail` and others :)
  *
  *  It also takes the following parameters as nested elements:
  *  - `src` (for srcdir),
  *  - `classpath`,
- *  - `sourcepath`,
+ *  - `docSourcePath`,
  *  - `bootclasspath`,
  *  - `extdirs`.
  *
@@ -90,7 +90,7 @@ class Scaladoc extends ScalaMatchingTask {
   /** The class path to use for this compilation. */
   private var classpath: Option[Path] = None
   /** The source path to use for this compilation. */
-  private var sourcepath: Option[Path] = None
+  private var docSourcePath: Option[Path] = None
   /** The boot class path to use for this compilation. */
   private var bootclasspath: Option[Path] = None
   /** The external extensions path to use for this compilation. */
@@ -214,29 +214,33 @@ class Scaladoc extends ScalaMatchingTask {
   def setClasspathref(input: Reference) =
     createClasspath().setRefid(input)
 
-  /** Sets the `sourcepath` attribute. Used by [[http://ant.apache.org Ant]].
-   *
-   *  @param input The value of `sourcepath`.
-   */
-  def setSourcepath(input: Path) =
-    if (sourcepath.isEmpty) sourcepath = Some(input)
-    else sourcepath.get.append(input)
+  // Bridge the gap between sourcepath and docSourcePath
+  @deprecated("The scaladoc sourcepath attribute is deprecated. Please use docSourcePath instead.")
+  def setSourcepath(input: Path) = {
+    buildWarning("The scaladoc sourcepath attribute is deprecated. Please use docSourcePath instead.")
+    setDocSourcePath(input)
+  }
 
-  /** Sets the `sourcepath` as a nested sourcepath Ant parameter.
-   *
-   *  @return A source path to be configured.
-   */
-  def createSourcepath(): Path = {
-    if (sourcepath.isEmpty) sourcepath = Some(new Path(getProject))
-    sourcepath.get.createPath()
+  @deprecated("The scaladoc sourcepath attribute is deprecated. Please use docSourcePath instead.")
+  def setSourcepathref(input: Reference) = {
+    buildWarning("The scaladoc sourcepath attribute is deprecated. Please use docSourcePath instead.")
+    setDocSourcePathRef(input)
   }
 
-  /** Sets the `sourcepath` as an external reference Ant parameter.
-   *
-   *  @param input A reference to a source path.
-   */
-  def setSourcepathref(input: Reference) =
-    createSourcepath().setRefid(input)
+  /** Sets the `docSourcePath` attribute. */
+  def setDocSourcePath(input: Path) =
+    if (docSourcePath.isEmpty) docSourcePath = Some(input)
+    else docSourcePath.get.append(input)
+
+  /** Sets the `docSourcePath` as a nested docSourcePath Ant parameter. */
+  def createSourcePath(): Path = {
+    if (docSourcePath.isEmpty) docSourcePath = Some(new Path(getProject))
+    docSourcePath.get.createPath()
+  }
+
+  /** Sets the `docSourcePath` as an external reference Ant parameter. */
+  def setDocSourcePathRef(input: Reference) =
+    createSourcePath().setRefid(input)
 
   /** Sets the `bootclasspath` attribute. Used by [[http://ant.apache.org Ant]].
    *
@@ -246,7 +250,7 @@ class Scaladoc extends ScalaMatchingTask {
     if (bootclasspath.isEmpty) bootclasspath = Some(input)
     else bootclasspath.get.append(input)
 
-  /** Sets the `bootclasspath` as a nested `sourcepath` Ant parameter.
+  /** Sets the `bootclasspath` as a nested `docSourcePath` Ant parameter.
    *
    *  @return A source path to be configured.
    */
@@ -272,7 +276,7 @@ class Scaladoc extends ScalaMatchingTask {
     else extdirs.get.append(input)
   }
 
-  /** Sets the `extdirs` as a nested sourcepath Ant parameter.
+  /** Sets the `extdirs` as a nested docSourcePath Ant parameter.
    *
    *  @return An extensions path to be configured.
    */
@@ -456,8 +460,8 @@ class Scaladoc extends ScalaMatchingTask {
    *  @return The source path as a list of files.
    */
   private def getSourcepath: List[File] =
-    if (sourcepath.isEmpty) buildError("Member 'sourcepath' is empty.")
-    else sourcepath.get.list().toList map nameToFile
+    if (docSourcePath.isEmpty) buildError("Member 'sourcepath' is empty.")
+    else docSourcePath.get.list().toList map nameToFile
 
   /** Gets the value of the `bootclasspath` attribute in a
    *  Scala-friendly form.
@@ -595,12 +599,11 @@ class Scaladoc extends ScalaMatchingTask {
     docSettings.outdir.value = asString(destination.get)
     if (!classpath.isEmpty)
       docSettings.classpath.value = asString(getClasspath)
-    if (!sourcepath.isEmpty)
-      docSettings.sourcepath.value = asString(getSourcepath)
-    /*else if (origin.get.size() > 0)
-      settings.sourcepath.value = origin.get.list()(0)*/
+    if (!docSourcePath.isEmpty)
+      docSettings.docSourcePath.value = asString(getSourcepath)
     if (!bootclasspath.isEmpty)
       docSettings.bootclasspath.value = asString(getBootclasspath)
+
     if (!extdirs.isEmpty) docSettings.extdirs.value = asString(getExtdirs)
     if (!encoding.isEmpty) docSettings.encoding.value = encoding.get
     if (!doctitle.isEmpty) docSettings.doctitle.value = decodeEscapes(doctitle.get)
diff --git a/src/compiler/scala/tools/ant/sabbus/Make.scala b/src/compiler/scala/tools/ant/sabbus/Make.scala
index 57505420c5..9433c8dc5e 100644
--- a/src/compiler/scala/tools/ant/sabbus/Make.scala
+++ b/src/compiler/scala/tools/ant/sabbus/Make.scala
@@ -20,7 +20,7 @@ class Make extends Task with TaskArgs {
     if (!destinationDir.isEmpty) settings.d = destinationDir.get
     if (!compTarget.isEmpty) settings.target = compTarget.get
     if (!compilationPath.isEmpty) settings.classpath = compilationPath.get
-    if (!sourcePath.isEmpty) settings.sourcepath = sourcePath.get
+    if (!sourcePath.isEmpty) settings.Ysourcepath = sourcePath.get
     settings.extraParams = extraArgsFlat
     Compilers.make(id.get, (compilerPath.get.list.map{ path => new File(path).toURI.toURL }), settings)
   }
diff --git a/src/compiler/scala/tools/ant/sabbus/ScalacFork.scala b/src/compiler/scala/tools/ant/sabbus/ScalacFork.scala
index 5199e273d7..2ba49cc2b5 100644
--- a/src/compiler/scala/tools/ant/sabbus/ScalacFork.scala
+++ b/src/compiler/scala/tools/ant/sabbus/ScalacFork.scala
@@ -101,7 +101,7 @@ class ScalacFork extends ScalaMatchingTask with ScalacShared with TaskArgs {
 
     compTarget foreach (settings.target = _)
     compilationPath foreach (settings.classpath = _)
-    sourcePath foreach (settings.sourcepath = _)
+    sourcePath foreach (settings.Ysourcepath = _)
     settings.extraParams = extraArgsFlat
 
     if (isMSIL)
diff --git a/src/compiler/scala/tools/ant/sabbus/Settings.scala b/src/compiler/scala/tools/ant/sabbus/Settings.scala
index c62ea172ed..58e0fd42a2 100644
--- a/src/compiler/scala/tools/ant/sabbus/Settings.scala
+++ b/src/compiler/scala/tools/ant/sabbus/Settings.scala
@@ -27,8 +27,8 @@ class Settings {
   def classpath_=(p: Path): this.type = { classpathBf = Some(p); this }
 
   private var sourcepathBf: Option[Path] = None
-  def sourcepath = sourcepathBf.get
-  def sourcepath_=(p: Path): this.type = { sourcepathBf = Some(p); this }
+  def Ysourcepath = sourcepathBf.get
+  def Ysourcepath_=(p: Path): this.type = { sourcepathBf = Some(p); this }
 
   private var sourcedirBf: Option[File] = None
   def sourcedir = sourcedirBf.get
@@ -66,7 +66,7 @@ class Settings {
     (if (!gBf.isEmpty) "-g:"+g :: Nil else Nil) :::
     (if (uncheckedBf) "-unchecked" :: Nil else Nil) :::
     (if (!classpathBf.isEmpty) "-classpath" :: classpath.toString :: Nil else Nil) :::
-    (if (!sourcepathBf.isEmpty) "-sourcepath" :: sourcepath.toString :: Nil else Nil) :::
+    (if (!sourcepathBf.isEmpty) "-Ysourcepath" :: Ysourcepath.toString :: Nil else Nil) :::
     (if (!sourcedirBf.isEmpty) "-Xsourcedir" :: sourcedir.toString :: Nil else Nil) :::
     (if (!bootclasspathBf.isEmpty) "-bootclasspath" :: bootclasspath.toString :: Nil else Nil) :::
     (if (!extdirsBf.isEmpty) "-extdirs" :: extdirs.toString :: Nil else Nil) :::
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index d3a1d47de8..27aba41c33 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -62,7 +62,15 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
   }
 
   /** A setting that defines a URL to be concatenated with source locations and show a link to source files.
-   * If needed the sourcepath option can be used to exclude undesired initial part of the link to sources */
+   * If needed the docSourcePath option can be used to exclude undesired initial part of the link to sources */
+  val docSourcePath = PathSetting (
+    "-doc-source-path",
+    "The prefix in all source file paths. Will be stripped off all paths before URLs are generated.",
+    ""
+  )
+
+  /** A setting that defines a URL to be concatenated with source locations and show a link to source files.
+   * If needed the docSourcePath option can be used to exclude undesired initial part of the link to sources */
   val docsourceurl = StringSetting (
     "-doc-source-url",
     "url",
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index 3dd77d47da..f74fb38056 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -208,7 +208,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
 
     def sourceUrl = {
       def fixPath(s: String) = s.replaceAll("\\" + java.io.File.separator, "/")
-      val assumedSourceRoot  = fixPath(settings.sourcepath.value) stripSuffix "/"
+      val assumedSourceRoot  = fixPath(settings.docSourcePath.value) stripSuffix "/"
 
       if (!settings.docsourceurl.isDefault)
         inSource map { case (file, _) =>
diff --git a/src/compiler/scala/tools/nsc/interactive/tests/InteractiveTestSettings.scala b/src/compiler/scala/tools/nsc/interactive/tests/InteractiveTestSettings.scala
index 36671555d1..15592a3a21 100644
--- a/src/compiler/scala/tools/nsc/interactive/tests/InteractiveTestSettings.scala
+++ b/src/compiler/scala/tools/nsc/interactive/tests/InteractiveTestSettings.scala
@@ -46,7 +46,7 @@ trait InteractiveTestSettings extends TestSettings with PresentationCompilerInst
         println("error processing arguments (unprocessed: %s)".format(rest))
       case _ => ()
     }
-    adjustPaths(settings.bootclasspath, settings.classpath, settings.javabootclasspath, settings.sourcepath)
+    adjustPaths(settings.bootclasspath, settings.classpath, settings.javabootclasspath, settings.Ysourcepath)
   }
 
   /** If there's a file ending in .opts, read it and parse it for cmd line arguments. */
diff --git a/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala b/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
index a16b42dc47..055ea7a01f 100644
--- a/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/ScalaSettings.scala
@@ -176,6 +176,21 @@ trait ScalaSettings extends AbsScalaSettings
   val YvirtClasses    = false // too embryonic to even expose as a -Y //BooleanSetting    ("-Yvirtual-classes", "Support virtual classes")
 
   val exposeEmptyPackage = BooleanSetting("-Yexpose-empty-package", "Internal only: expose the empty package.").internalOnly()
+  val Ysourcepath     = PathSetting ("-Ysourcepath", "[Only used when bootstrapping the scala library] Indicates the path to the scala library source code so the code generated is stand-alone rather than referencing the previous library classes.", "") // Defaults.scalaSourcePath
+
+  // this should be defined StandardScalaSettings, but there we don't have withDeprecationMessage and withPostSetHook
+  // see StandardScalaSettings.sourcepath for more information
+  val deprSourcepath    = this match {
+    case s: doc.Settings    => PathSetting("-sourcepath", "Deprecated. Please use -doc-source-path.", ""). 
+                                 withDeprecationMessage ("-sourcepath is deprecated. Please use -doc-source-path."). 
+                                 withPostSetHook((v: PathSetting) => s.docSourcePath.tryToSet(List(v.value)))
+    case s: MutableSettings => PathSetting("-sourcepath", "Deprecated. Please use -Ysourcepath.",     ""). 
+                                 withDeprecationMessage ("-sourcepath is deprecated. Please use -Ysourcepath.").
+                                 withPostSetHook((v: PathSetting) => s.Ysourcepath.tryToSet(List(v.value)))
+    case _                  => PathSetting("-sourcepath", "Deprecated. Please use -doc-source-path or -Ysourcepath.", "").
+                                 withDeprecationMessage ("-sourcepath is deprecated. Please use -doc-source-path or -Ysourcepath.")
+                                 // no PostSetHook, we have no idea what's the equivalent
+  }
 
   def stop = stopAfter
 
diff --git a/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala b/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
index 1bb0948168..06838adb65 100644
--- a/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
+++ b/src/compiler/scala/tools/nsc/settings/StandardScalaSettings.scala
@@ -24,8 +24,15 @@ trait StandardScalaSettings {
   val extdirs =           PathSetting ("-extdirs", "Override location of installed extensions.", Defaults.scalaExtDirs)
   val javabootclasspath = PathSetting ("-javabootclasspath", "Override java boot classpath.", Defaults.javaBootClassPath)
   val javaextdirs =       PathSetting ("-javaextdirs", "Override java extdirs classpath.", Defaults.javaExtDirs)
-  val sourcepath =        PathSetting ("-sourcepath", "Specify location(s) of source files.", "") // Defaults.scalaSourcePath
-
+  // sourcePath is now deprecated, as it had two very different meanings confused under a single setting
+  // for the scalac compiler -- it was only used when bootstrapping the scala library, to prevent the new library 
+  //                            bytecode to depend on the old library (now -Ysource-path and .Ysourcepath) 
+  // for scaladoc --            it was used to generate the URL for the source file paths (used in conjunction with
+  //                            -doc-source-url, now -doc-source-path and .docSourcePath)
+  // to prevent .sourcepath usage:
+  def sourcepath :        PathSetting = { assert(false, "Settings.sourcepath has been deprecated. Please use either Settings.YsourcePath or Settings.docSourcePath instead."); null.asInstanceOf[PathSetting] }
+  // to bridge -sourcepath command line: we define deprSourcepath in ScalaSettings
+  
   /** Other settings.
    */
   val dependencyfile =  StringSetting ("-dependencyfile", "file", "Set dependency tracking file.", ".scala_dependencies")
diff --git a/src/compiler/scala/tools/util/PathResolver.scala b/src/compiler/scala/tools/util/PathResolver.scala
index 4c0e33e4fb..3b2bba5f8e 100644
--- a/src/compiler/scala/tools/util/PathResolver.scala
+++ b/src/compiler/scala/tools/util/PathResolver.scala
@@ -179,7 +179,7 @@ class PathResolver(settings: Settings, context: JavaContext) {
     case "bootclasspath"      => settings.bootclasspath.value
     case "extdirs"            => settings.extdirs.value
     case "classpath" | "cp"   => settings.classpath.value
-    case "sourcepath"         => settings.sourcepath.value
+    case "Ysourcepath"         => settings.Ysourcepath.value
   }
 
   /** Calculated values based on any given command line options, falling back on
@@ -193,7 +193,7 @@ class PathResolver(settings: Settings, context: JavaContext) {
     def javaUserClassPath   = if (useJavaClassPath) Defaults.javaUserClassPath else ""
     def scalaBootClassPath  = cmdLineOrElse("bootclasspath", Defaults.scalaBootClassPath)
     def scalaExtDirs        = cmdLineOrElse("extdirs", Defaults.scalaExtDirs)
-    def sourcePath          = cmdLineOrElse("sourcepath", Defaults.scalaSourcePath)
+    def sourcePath          = cmdLineOrElse("Ysourcepath", Defaults.scalaSourcePath)
 
     /** Against my better judgment, giving in to martin here and allowing
      *  CLASSPATH to be used automatically.  So for the user-specified part
diff --git a/src/manual/scala/man1/scalac.scala b/src/manual/scala/man1/scalac.scala
index 49324ffa83..be2a9d2cf7 100644
--- a/src/manual/scala/man1/scalac.scala
+++ b/src/manual/scala/man1/scalac.scala
@@ -143,9 +143,6 @@ object scalac extends Command {
           CmdOption("print"),
           "Print program with all Scala-specific features removed."),
         Definition(
-          CmdOption("sourcepath", Argument("path")),
-          "Specify location(s) of source files."),
-        Definition(
           CmdOptionBound("target:", Argument("target")),
           SeqPara(
             "Specify which backend to use (" & Mono("jvm-1.5," &
diff --git a/src/manual/scala/man1/scaladoc.scala b/src/manual/scala/man1/scaladoc.scala
index 193c77fc51..333b6ad7e1 100644
--- a/src/manual/scala/man1/scaladoc.scala
+++ b/src/manual/scala/man1/scaladoc.scala
@@ -75,7 +75,13 @@ object scaladoc extends Command {
           "Define the overall version number of the documentation, typically the version of the library being documented."),
         Definition(
           CmdOption("doc-source-url", Argument("url")),
-          "Define a URL to be concatenated with source locations for link to source files."))),
+          "Define a URL to be concatenated with source locations for link to source files."),
+        Definition(
+          CmdOption("doc-diagrams"),
+          "Generate diagrams in the current scaladoc compilation run."),
+        Definition(
+          CmdOption("doc-implicits"),
+          "List members generated from implicit conversions in the scaladoc page."))),
 
     Section("Compiler Options",
       DefinitionList(
@@ -103,8 +109,8 @@ object scaladoc extends Command {
             "include the current directory in the search path, you must " &
             "include " & Mono("\".\"") & " in the new settings.")),
         Definition(
-          CmdOption("sourcepath", Argument("path")),
-          "Specify where to find input source files."),
+          CmdOption("doc-source-path", Argument("path")),
+          "Specify the common prefix in the source files' paths. Used when generating links to source."),
         Definition(
           CmdOption("bootclasspath", Argument("path")),
           "Override location of bootstrap class files (where to find the " &
diff --git a/src/partest/scala/tools/partest/nest/Worker.scala b/src/partest/scala/tools/partest/nest/Worker.scala
index 40325c6375..f2128cc219 100644
--- a/src/partest/scala/tools/partest/nest/Worker.scala
+++ b/src/partest/scala/tools/partest/nest/Worker.scala
@@ -692,7 +692,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
               // create proper settings for the compiler
               val settings = new Settings(workerError)
               settings.outdir.value = outDir.getAbsoluteFile.getAbsolutePath
-              settings.sourcepath.value = sourcepath
+              settings.Ysourcepath.value = sourcepath
               settings.classpath.value = fileManager.CLASSPATH
               settings.Ybuildmanagerdebug.value = true
 
@@ -710,7 +710,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
                 val args = (line split ' ').toList
                 val command = new CompilerCommand(args, settings)
                 command.ok && {
-                  bM.update(filesToSet(settings.sourcepath.value, command.files), Set.empty)
+                  bM.update(filesToSet(settings.Ysourcepath.value, command.files), Set.empty)
                   !reporter.hasErrors
                 }
               }
@@ -797,7 +797,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
             NestUI.verbose("resFile: "+resFile)
 
             // run compiler in resident mode
-            // $SCALAC -d "$os_dstbase".obj -Xresident -sourcepath . "$@"
+            // $SCALAC -d "$os_dstbase".obj -Xresident -Ysourcepath . "$@"
             val sourcedir  = logFile.getParentFile.getAbsoluteFile
             val sourcepath = sourcedir.getAbsolutePath+File.separator
             NestUI.verbose("sourcepath: "+sourcepath)
@@ -805,7 +805,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
             val argList = List(
               "-d", outDir.getAbsoluteFile.getPath,
               "-Xresident",
-              "-sourcepath", sourcepath)
+              "-Ysourcepath", sourcepath)
 
             // configure input/output files
             val logOut    = new FileOutputStream(logFile)
@@ -815,7 +815,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
 
             // create compiler
             val settings = new Settings(workerError)
-            settings.sourcepath.value = sourcepath
+            settings.Ysourcepath.value = sourcepath
             settings.classpath.value = fileManager.CLASSPATH
             reporter = new ConsoleReporter(settings, scala.Console.in, logConsoleWriter)
             val command = new CompilerCommand(argList, settings)
@@ -826,7 +826,7 @@ class Worker(val fileManager: FileManager, params: TestRunParams) extends Actor
               val cmdArgs = (line split ' ').toList map (fs => new File(dir, fs).getAbsolutePath)
               NestUI.verbose("cmdArgs: "+cmdArgs)
               val sett = new Settings(workerError)
-              sett.sourcepath.value = sourcepath
+              sett.Ysourcepath.value = sourcepath
               val command = new CompilerCommand(cmdArgs, sett)
               command.ok && {
                 (new compiler.Run) compile command.files