some description of main build options;

--- a/doc-src/System/Thy/Sessions.thy	Sat Jul 28 18:20:47 2012 +0200
+++ b/doc-src/System/Thy/Sessions.thy	Sat Jul 28 19:37:35 2012 +0200
@@ -115,14 +115,22 @@
   again.
 
   \end{description}
+*}
 
-  Plenty of examples may be found in the Isabelle distribution, such
-  as in @{file "~~/src/HOL/ROOT"}.  *}
+subsubsection {* Examples *}
+
+text {* See @{file "~~/src/HOL/ROOT"} for a diversity of practically
+  relevant situations. *}
 
 
 section {* System build options \label{sec:system-options} *}
 
-text {* FIXME *}
+text {* See @{file "~~/etc/options"} for the main defaults provided by
+  the Isabelle distribution.
+
+  Note that Isabelle/jEdit \secref{sec:tool-jedit} includes a simple
+  editing mode @{verbatim "isabelle-options"} for this file-format.
+*}
 
 
 section {* Invoking the build process \label{sec:tool-build} *}

--- a/etc/options	Sat Jul 28 18:20:47 2012 +0200
+++ b/etc/options	Sat Jul 28 19:37:35 2012 +0200
@@ -1,39 +1,63 @@
 (* :mode=isabelle-options: *)
 
 declare browser_info : bool = false
+  -- "generate theory browser information"
 
 declare document : string = ""
+  -- "build document in given format: pdf, dvi, dvi.gz, ps, ps.gz, or false"
 declare document_variants : string = "outline=/proof,/ML"
+  -- "declare alternative document variants (separated by colons)"
 declare document_graph : bool = false
+  -- "generate session graph image for document"
 declare document_dump : string = ""
+  -- "dump generated document sources into given directory"
 declare document_dump_mode : string = "all"
-declare no_document : bool = false
+  -- "specific document dump mode: all, tex, tex+sty"
 
 declare threads : int = 0
+  -- "maximum number of worker threads for prover process (0 = hardware max.)"
 declare threads_trace : int = 0
+  -- "level of tracing information for multithreading"
 declare parallel_proofs : int = 2
+  -- "level of parallel proof checking: 0, 1, 2"
 declare parallel_proofs_threshold : int = 100
+  -- "threshold for sub-proof parallelization"
 
 declare print_mode : string = ""
+  -- "additional print modes for prover output (separated by commas)"
 
 declare proofs : int = 1
+  -- "level of detail for proof objects: 0, 1, 2"
 declare quick_and_dirty : bool = false
+  -- "if true then some tools will OMIT some proofs"
 
 declare condition : string = ""
+  -- "required environment variables for subsequent theories (separated by commas)"
 
 declare show_question_marks : bool = true
+  -- "show leading question mark of schematic variables"
 
 declare names_long : bool = false
+  -- "show fully qualified names"
 declare names_short : bool = false
+  -- "show base names only"
 declare names_unique : bool = true
+  -- "show partially qualified names, as required for unique name resolution"
 
 declare pretty_margin : int = 76
+  -- "right margin / page width of pretty printer in Isabelle/ML"
 
 declare thy_output_display : bool = false
+  -- "indicate output as multi-line display-style material"
+declare thy_output_break : bool = false
+  -- "control line breaks in non-display material"
 declare thy_output_quotes : bool = false
+  -- "indicate if the output should be enclosed in double quotes"
 declare thy_output_indent : int = 0
+  -- "indentation for pretty printing of display material"
 declare thy_output_source : bool = false
-declare thy_output_break : bool = false
+  -- "print original source text rather than internal representation"
 
 declare timing : bool = false
+  -- "global timing of toplevel command execution and theory processing"
 

--- a/src/Pure/System/options.scala	Sat Jul 28 18:20:47 2012 +0200
+++ b/src/Pure/System/options.scala	Sat Jul 28 19:37:35 2012 +0200
@@ -35,7 +35,7 @@
     val DECLARE = "declare"
     val DEFINE = "define"
 
-    val syntax = Outer_Syntax.empty + ":" + "=" + DECLARE + DEFINE
+    val syntax = Outer_Syntax.empty + ":" + "=" + "--" + DECLARE + DEFINE
 
     val entry: Parser[Options => Options] =
     {
@@ -44,9 +44,8 @@
       val option_value = atom("option value", tok => tok.is_name || tok.is_float)
 
       keyword(DECLARE) ~! (option_name ~ keyword(":") ~ option_type ~
-      keyword("=") ~ option_value ~ opt(text)) ^^
-        { case _ ~ (a ~ _ ~ b ~ _ ~ c ~ d) =>
-            (options: Options) => options.declare(a, b, c, d.getOrElse("")) } |
+      keyword("=") ~ option_value ~ (keyword("--") ~! text ^^ { case _ ~ x => x } | success(""))) ^^
+        { case _ ~ (a ~ _ ~ b ~ _ ~ c ~ d) => (options: Options) => options.declare(a, b, c, d) } |
       keyword(DEFINE) ~! (option_name ~ keyword("=") ~ option_value) ^^
         { case _ ~ (a ~ _ ~ b) => (options: Options) => options.define(a, b) }
     }