diff options
author | Lex Spoon <lex@lexspoon.org> | 2006-06-13 15:47:43 +0000 |
---|---|---|
committer | Lex Spoon <lex@lexspoon.org> | 2006-06-13 15:47:43 +0000 |
commit | faf05d692e042dcb6ac7137c2f5dcf373df77526 (patch) | |
tree | 0865b248914d7ca9f86c45503c5599b1d382f7fc | |
parent | 150014366e457e0a30f185b4debca2303f0f58d3 (diff) | |
download | scala-faf05d692e042dcb6ac7137c2f5dcf373df77526.tar.gz scala-faf05d692e042dcb6ac7137c2f5dcf373df77526.tar.bz2 scala-faf05d692e042dcb6ac7137c2f5dcf373df77526.zip |
rewrote the man page to describe a new command ...
rewrote the man page to describe a new command unifying "scala",
"scalaint", and "scalascript"
-rw-r--r-- | src/manual/scala/man1/scala.scala | 176 |
1 files changed, 116 insertions, 60 deletions
diff --git a/src/manual/scala/man1/scala.scala b/src/manual/scala/man1/scala.scala index 827bd09cb2..ab2b5044e7 100644 --- a/src/manual/scala/man1/scala.scala +++ b/src/manual/scala/man1/scala.scala @@ -13,79 +13,109 @@ object scala extends Command { val name = Section("NAME", - MBold(command) & " " & NDash & " Launcher for the " & - Link("Scala 2", "http://scala.epfl.ch/") & " language") + MBold(command) & " " & NDash & " Run code in the " & + Link("Scala 2", "http://scala.epfl.ch/") & + " language") val synopsis = Section("SYNOPSIS", - CmdLine(" [ " & Argument("options") & " ] " & - Argument("class file") & " [ " & Argument("args") & " ]")) + CmdLine(" [ " & Argument("compiler-options") & " - ] " & + "[ [ -object | -script ] " + & " " & Argument("object-or-file") + & " " & Argument("arguments") & " ]")) val parameters = Section("PARAMETERS", DefinitionList( Definition( - Mono(Argument("options")), - "Command line options. See " & Link(Bold("OPTIONS"), "#options") & - " below."), + Mono(Argument("compiler-options")), + "Options for the compiler. See " & + Link(Bold("scalac") & "(1)", "scalac.html")), + + Definition( + Mono("-object"), + "The following argument specifies a pre-compiled class to run."), + Definition( - Mono(Argument("class file")), - "Name of the class to be invoked."), + Mono("-script"), + "The following argument specifies a script file to run."), + + Definition( + Mono(Argument("object-or-file")), + "A top-level object or a script file to run"), + Definition( - Mono(Argument("args")), - "Program arguments passed to the main function."))) + Mono(Argument("arguments")), + "Arguments to pass to the object or script"))) val description = Section("DESCRIPTION", - "The " & MBold(command) & " utility launches a Scala application. " & - "It does this by starting a Java runtime environment, loading a " & - "specified class, and invoking that class's " & Bold("main") & - " method. The method must have the following signature:", + "The "&MBold(command)&" utility runs Scala code using a Java runtime "& + "environment. The Scala code to run is " & + "specified in one of three ways:", + + BulletList( + "With no arguments specified, an interactive interpreter starts " & + "and reads commands interactively.", + + "With -object specified, the fully qualified name of a top-level " & + "Scala object may be specified. The object should previously have " & + "been compiled using " & Link(Bold("scalac") & "(1)", "scalac.html") & + ".", + + "With -script specified, a file containing Scala code may be " & + "specified." + ), + + "If " & Argument("object-or-file") & " is specified but both -object " & + " and -script are omitted, then " & MBold(command) & + " will check whether a file of the " & + "specified name exists. If it does, then it will treat it as a " & + "script file; if it does not, then it will treat it as the name " & + "of an object", + + "In all three cases, arbitrary scalac options may be specified. "& + "The most common option is to specify a classpath with " & + Mono("-classpath") & ", but see the " & + Link(Bold("scalac") & "(1)", "scalac.html") & " page for " & + "full details.", + + + "If an object is specified to run, then that object must be a top-level " & + "Scala object with the specified name. The object must define a method " & + Bold("main") & " with the following signature:", BlockQuote(Mono(Bold("def") & " main(args: Array[String]): Unit")), "The method must return a " & Bold("Unit") & " value, and it must " & - "accept a " & Bold("String") & " array as a parameter. By default, " & - "the first non-option argument is the name of the class to be invoked. "& - "A fully-qualified class name should be used.", + "accept a " & Bold("String") & " array as a parameter. All arguments " & + "specified on the command line will be passed as " & + "arguments to the " & Bold("main") & " method.", + + "If a script file is specified to run, then the file is read and all " & + "Scala statements and declarations in the file are processed in order. ", + + "Script files may have an optional header fthat is ignored if " & + "present. There are two ways to format the header: either beginning with " & + Mono("#!") & " and ending with " & Mono("!#") & ", or beginning with " & + Mono("::#!") & " and ending with " & Mono("::!#") & ".", + + "Such a header must have each header boundary start at the beginning of a " & + "line. Headers can be used to make stand-alone script files, as shown " & + "in the examples below.") - "The Scala runtime searches for the startup class, and other classes " & - "used, in three sets of locations: the bootstrap class path, the " & - "installed extensions, and the user class path.") val options = Section("OPTIONS", - "The launcher has a set of standard options that are supported on the " & - "current runtime environment and will be supported in future releases. " & - "An additional set of non-standard options are specific to the current " & - "virtual machine implementation and are subject to change in the future. " & - "Non-standard options begin with " & CmdOption("X") & ".", - - Section("Standard Options", - DefinitionList( - Definition( - CmdOption("cp") & "| " & CmdOption("classpath", Argument("path")), - "Specify where to find user class files (on Unix-based systems " & - "a colon-separated list of paths, on Windows-based systems, a " & - "semicolon-separate list of paths)."), - Definition( - CmdOption("D", Argument("name") & "=" & Argument("value")), - "Set a system property."), - Definition( - CmdOption("verbose", "[:class|gc|jni]"), - "Enable verbose output."), - Definition( - CmdOption("showversion"), - "Print product version and continue."), - Definition( - CmdOption("version"), - "Print product version and exit."), - Definition( - CmdOption("help"), - "Print this help message."))), - - Section("Non-Standard Options", - "Same options as the " & MBold("java") & " command.")) + "If any compiler options are specified, they must be first in the " & + "command line and must be followed by a bare hypen (" & Quote("-") & + ") character. " & + "If no arguments are specified after the optional compiler arguments, " & + "then an interactive interpreter is started. Otherwise, either a " & + "script file is run, or a pre-compiled Scala object is run. It " & + "is possible to distinguish the last two cases by using an explicit " & + Mono("-object") & " or " & Mono("-script") & " flag, but usually the " & + "program can guess correctly.") val environment = Section("ENVIRONMENT", @@ -97,39 +127,65 @@ object scala extends Command { val examples = Section("EXAMPLES", + "Here are some examples of running Scala code:", + DefinitionList( Definition( "Execute a Scala program generated in the current directory", CmdLine("hello.HelloWorld")), + Definition( "Execute a Scala program generated in a user-defined " & "directory " & Bold("classes"), CmdLine(CmdOption("classpath", "classes") & "hello.HelloWorld")), + Definition( "Execute a Scala program using a user-defined " & MBold("java") & " " & "command", MBold("env JAVACMD") & Mono("=/usr/local/bin/cacao ") & - CmdLine(CmdOption("classpath", "classes") & "hello.HelloWorld")))) + CmdLine(CmdOption("classpath", "classes") & "hello.HelloWorld"))), + + "Here is a complete Scala script for Unix: ", + + CodeSample( + "#!/bin/sh\n" + + "exec scalascript \"$0\" \"$@\"\n" + + "!#\n" + + "Console.println(\"Hello, world!\")\n" + + "argv.toList foreach Console.println"), + + "Here is a complete Scala script for Unix: ", + + CodeSample( + "::#!\n" + + "@echo off\n" + + "call scalascript %0 %*\n" + + "goto :eof\n" + + "::!#\n" + + "Console.println(\"Hello, world!\")\n" + + "argv.toList foreach Console.println")) + val exitStatus = Section("EXIT STATUS", - MBold(command) & " returns a zero exit status if it succeeds. " & - "Non zero is returned in case of failure.") + "The " & MBold(command) & " command " & + "returns a zero exit status if it succeeds. " & + "Non zero is returned in case of any error. If a script or " & + "top-level object is executed and returns a value, then that " & + "return value is passed on to " & MBold(command) & ".") val seeAlso = Section("SEE ALSO", Link(Bold("sbaz") & "(1)", "sbaz.html") & ", " & Link(Bold("scalac") & "(1)", "scalac.html") & ", " & Link(Bold("scaladoc") & "(1)", "scaladoc.html") & ", " & - Link(Bold("scalaint") & "(1)", "scalaint.html") & ", " & - Link(Bold("scalap") & "(1)", "scalap.html") & ", " & - Link(Bold("scalascript") & "(1)", "scalascript.html")) + Link(Bold("scalap") & "(1)", "scalap.html")) def manpage = new Document { title = command date = lastModified - author = "Stephane Micheloud" - version = "0.2" + author = "LAMP" + version = "0.3" sections = List( name, synopsis, |