1.1 --- a/doc-src/IsarRef/IsaMakefile Mon Jun 02 22:50:29 2008 +0200
1.2 +++ b/doc-src/IsarRef/IsaMakefile Mon Jun 02 22:50:54 2008 +0200
1.3 @@ -23,8 +23,8 @@
1.4
1.5 $(LOG)/HOL-IsarRef.gz: Thy/ROOT.ML ../antiquote_setup.ML \
1.6 Thy/Introduction.thy Thy/Outer_Syntax.thy Thy/Spec.thy Thy/Proof.thy \
1.7 - Thy/pure.thy Thy/Generic.thy Thy/HOL_Specific.thy \
1.8 - Thy/Quick_Reference.thy Thy/ML_Tactic.thy
1.9 + Thy/pure.thy Thy/Document_Preparation.thy Thy/Generic.thy \
1.10 + Thy/HOL_Specific.thy Thy/Quick_Reference.thy Thy/ML_Tactic.thy
1.11 @$(USEDIR) -s IsarRef HOL Thy
1.12
1.13
2.1 --- a/doc-src/IsarRef/Makefile Mon Jun 02 22:50:29 2008 +0200
2.2 +++ b/doc-src/IsarRef/Makefile Mon Jun 02 22:50:54 2008 +0200
2.3 @@ -13,7 +13,7 @@
2.4
2.5 NAME = isar-ref
2.6
2.7 -FILES = isar-ref.tex style.sty Thy/document/Generic.tex \
2.8 +FILES = isar-ref.tex style.sty basics.tex Thy/document/Generic.tex \
2.9 Thy/document/HOLCF_Specific.tex Thy/document/HOL_Specific.tex \
2.10 Thy/document/ML_Tactic.tex Thy/document/Proof.tex \
2.11 Thy/document/Quick_Reference.tex Thy/document/Spec.tex \
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/doc-src/IsarRef/Thy/Document_Preparation.thy Mon Jun 02 22:50:54 2008 +0200
3.3 @@ -0,0 +1,427 @@
3.4 +(* $Id$ *)
3.5 +
3.6 +theory Document_Preparation
3.7 +imports Main
3.8 +begin
3.9 +
3.10 +chapter {* Document preparation \label{ch:document-prep} *}
3.11 +
3.12 +text {*
3.13 + Isabelle/Isar provides a simple document preparation system based on
3.14 + existing {PDF-\LaTeX} technology, with full support of hyper-links
3.15 + (both local references and URLs) and bookmarks. Thus the results
3.16 + are equally well suited for WWW browsing and as printed copies.
3.17 +
3.18 + \medskip Isabelle generates {\LaTeX} output as part of the run of a
3.19 + \emph{logic session} (see also \cite{isabelle-sys}). Getting
3.20 + started with a working configuration for common situations is quite
3.21 + easy by using the Isabelle @{verbatim mkdir} and @{verbatim make}
3.22 + tools. First invoke
3.23 +\begin{ttbox}
3.24 + isatool mkdir Foo
3.25 +\end{ttbox}
3.26 + to initialize a separate directory for session @{verbatim Foo} ---
3.27 + it is safe to experiment, since @{verbatim "isatool mkdir"} never
3.28 + overwrites existing files. Ensure that @{verbatim "Foo/ROOT.ML"}
3.29 + holds ML commands to load all theories required for this session;
3.30 + furthermore @{verbatim "Foo/document/root.tex"} should include any
3.31 + special {\LaTeX} macro packages required for your document (the
3.32 + default is usually sufficient as a start).
3.33 +
3.34 + The session is controlled by a separate @{verbatim IsaMakefile}
3.35 + (with crude source dependencies by default). This file is located
3.36 + one level up from the @{verbatim Foo} directory location. Now
3.37 + invoke
3.38 +\begin{ttbox}
3.39 + isatool make Foo
3.40 +\end{ttbox}
3.41 + to run the @{verbatim Foo} session, with browser information and
3.42 + document preparation enabled. Unless any errors are reported by
3.43 + Isabelle or {\LaTeX}, the output will appear inside the directory
3.44 + @{verbatim ISABELLE_BROWSER_INFO}, as reported by the batch job in
3.45 + verbose mode.
3.46 +
3.47 + \medskip You may also consider to tune the @{verbatim usedir}
3.48 + options in @{verbatim IsaMakefile}, for example to change the output
3.49 + format from @{verbatim pdf} to @{verbatim dvi}, or activate the
3.50 + @{verbatim "-D"} option to retain a second copy of the generated
3.51 + {\LaTeX} sources.
3.52 +
3.53 + \medskip See \emph{The Isabelle System Manual} \cite{isabelle-sys}
3.54 + for further details on Isabelle logic sessions and theory
3.55 + presentation. The Isabelle/HOL tutorial \cite{isabelle-hol-book}
3.56 + also covers theory presentation issues.
3.57 +*}
3.58 +
3.59 +
3.60 +section {* Markup commands \label{sec:markup} *}
3.61 +
3.62 +text {*
3.63 + \begin{matharray}{rcl}
3.64 + @{command_def "chapter"} & : & \isarkeep{local{\dsh}theory} \\
3.65 + @{command_def "section"} & : & \isarkeep{local{\dsh}theory} \\
3.66 + @{command_def "subsection"} & : & \isarkeep{local{\dsh}theory} \\
3.67 + @{command_def "subsubsection"} & : & \isarkeep{local{\dsh}theory} \\
3.68 + @{command_def "text"} & : & \isarkeep{local{\dsh}theory} \\
3.69 + @{command_def "text_raw"} & : & \isarkeep{local{\dsh}theory} \\[0.5ex]
3.70 + @{command_def "sect"} & : & \isartrans{proof}{proof} \\
3.71 + @{command_def "subsect"} & : & \isartrans{proof}{proof} \\
3.72 + @{command_def "subsubsect"} & : & \isartrans{proof}{proof} \\
3.73 + @{command_def "txt"} & : & \isartrans{proof}{proof} \\
3.74 + @{command_def "txt_raw"} & : & \isartrans{proof}{proof} \\
3.75 + \end{matharray}
3.76 +
3.77 + Apart from formal comments (see \secref{sec:comments}), markup
3.78 + commands provide a structured way to insert text into the document
3.79 + generated from a theory (see \cite{isabelle-sys} for more
3.80 + information on Isabelle's document preparation tools).
3.81 +
3.82 + \begin{rail}
3.83 + ('chapter' | 'section' | 'subsection' | 'subsubsection' | 'text') target? text
3.84 + ;
3.85 + ('text\_raw' | 'sect' | 'subsect' | 'subsubsect' | 'txt' | 'txt\_raw') text
3.86 + ;
3.87 + \end{rail}
3.88 +
3.89 + \begin{descr}
3.90 +
3.91 + \item [@{command "chapter"}, @{command "section"}, @{command
3.92 + "subsection"}, and @{command "subsubsection"}] mark chapter and
3.93 + section headings.
3.94 +
3.95 + \item [@{command "text"} and @{command "txt"}] specify paragraphs of
3.96 + plain text.
3.97 +
3.98 + \item [@{command "text_raw"} and @{command "txt_raw"}] insert
3.99 + {\LaTeX} source into the output, without additional markup. Thus
3.100 + the full range of document manipulations becomes available.
3.101 +
3.102 + \end{descr}
3.103 +
3.104 + The @{text "text"} argument of these markup commands (except for
3.105 + @{command "text_raw"}) may contain references to formal entities
3.106 + (``antiquotations'', see also \secref{sec:antiq}). These are
3.107 + interpreted in the present theory context, or the named @{text
3.108 + "target"}.
3.109 +
3.110 + Any of these markup elements corresponds to a {\LaTeX} command with
3.111 + the name prefixed by @{verbatim "\\isamarkup"}. For the sectioning
3.112 + commands this is a plain macro with a single argument, e.g.\
3.113 + @{verbatim "\\isamarkupchapter{"}@{text "\<dots>"}@{verbatim "}"} for
3.114 + @{command "chapter"}. The @{command "text"} markup results in a
3.115 + {\LaTeX} environment @{verbatim "\\begin{isamarkuptext}"} @{text
3.116 + "\<dots>"} @{verbatim "\\end{isamarkuptext}"}, while @{command "text_raw"}
3.117 + causes the text to be inserted directly into the {\LaTeX} source.
3.118 +
3.119 + \medskip The proof markup commands closely resemble those for theory
3.120 + specifications, but have a different formal status and produce
3.121 + different {\LaTeX} macros. Also note that the @{command_ref
3.122 + "header"} declaration (see \secref{sec:begin-thy}) admits to insert
3.123 + section markup just preceding the actual theory definition.
3.124 +*}
3.125 +
3.126 +
3.127 +section {* Antiquotations \label{sec:antiq} *}
3.128 +
3.129 +text {*
3.130 + \begin{matharray}{rcl}
3.131 + @{antiquotation_def "theory"} & : & \isarantiq \\
3.132 + @{antiquotation_def "thm"} & : & \isarantiq \\
3.133 + @{antiquotation_def "prop"} & : & \isarantiq \\
3.134 + @{antiquotation_def "term"} & : & \isarantiq \\
3.135 + @{antiquotation_def const} & : & \isarantiq \\
3.136 + @{antiquotation_def abbrev} & : & \isarantiq \\
3.137 + @{antiquotation_def typeof} & : & \isarantiq \\
3.138 + @{antiquotation_def typ} & : & \isarantiq \\
3.139 + @{antiquotation_def thm_style} & : & \isarantiq \\
3.140 + @{antiquotation_def term_style} & : & \isarantiq \\
3.141 + @{antiquotation_def "text"} & : & \isarantiq \\
3.142 + @{antiquotation_def goals} & : & \isarantiq \\
3.143 + @{antiquotation_def subgoals} & : & \isarantiq \\
3.144 + @{antiquotation_def prf} & : & \isarantiq \\
3.145 + @{antiquotation_def full_prf} & : & \isarantiq \\
3.146 + @{antiquotation_def ML} & : & \isarantiq \\
3.147 + @{antiquotation_def ML_type} & : & \isarantiq \\
3.148 + @{antiquotation_def ML_struct} & : & \isarantiq \\
3.149 + \end{matharray}
3.150 +
3.151 + The text body of formal comments (see also \secref{sec:comments})
3.152 + may contain antiquotations of logical entities, such as theorems,
3.153 + terms and types, which are to be presented in the final output
3.154 + produced by the Isabelle document preparation system (see also
3.155 + \chref{ch:document-prep}).
3.156 +
3.157 + Thus embedding of ``@{text "@{term [show_types] \"f x = a + x\"}"}''
3.158 + within a text block would cause
3.159 + \isa{{\isacharparenleft}f{\isasymColon}{\isacharprime}a\ {\isasymRightarrow}\ {\isacharprime}a{\isacharparenright}\ {\isacharparenleft}x{\isasymColon}{\isacharprime}a{\isacharparenright}\ {\isacharequal}\ {\isacharparenleft}a{\isasymColon}{\isacharprime}a{\isacharparenright}\ {\isacharplus}\ x} to appear in the final {\LaTeX} document. Also note that theorem
3.160 + antiquotations may involve attributes as well. For example,
3.161 + @{text "@{thm sym [no_vars]}"} would print the theorem's
3.162 + statement where all schematic variables have been replaced by fixed
3.163 + ones, which are easier to read.
3.164 +
3.165 + \begin{rail}
3.166 + atsign lbrace antiquotation rbrace
3.167 + ;
3.168 +
3.169 + antiquotation:
3.170 + 'theory' options name |
3.171 + 'thm' options thmrefs |
3.172 + 'prop' options prop |
3.173 + 'term' options term |
3.174 + 'const' options term |
3.175 + 'abbrev' options term |
3.176 + 'typeof' options term |
3.177 + 'typ' options type |
3.178 + 'thm\_style' options name thmref |
3.179 + 'term\_style' options name term |
3.180 + 'text' options name |
3.181 + 'goals' options |
3.182 + 'subgoals' options |
3.183 + 'prf' options thmrefs |
3.184 + 'full\_prf' options thmrefs |
3.185 + 'ML' options name |
3.186 + 'ML\_type' options name |
3.187 + 'ML\_struct' options name
3.188 + ;
3.189 + options: '[' (option * ',') ']'
3.190 + ;
3.191 + option: name | name '=' name
3.192 + ;
3.193 + \end{rail}
3.194 +
3.195 + Note that the syntax of antiquotations may \emph{not} include source
3.196 + comments @{verbatim "(*"}~@{text "\<dots>"}~@{verbatim "*)"} or verbatim
3.197 + text @{verbatim "{"}@{verbatim "*"}~@{text "\<dots>"}~@{verbatim
3.198 + "*"}@{verbatim "}"}.
3.199 +
3.200 + \begin{descr}
3.201 +
3.202 + \item [@{text "@{theory A}"}] prints the name @{text "A"}, which is
3.203 + guaranteed to refer to a valid ancestor theory in the current
3.204 + context.
3.205 +
3.206 + \item [@{text "@{thm a\<^sub>1 \<dots> a\<^sub>n}"}] prints theorems
3.207 + @{text "a\<^sub>1 \<dots> a\<^sub>n"}. Note that attribute specifications
3.208 + may be included as well (see also \secref{sec:syn-att}); the
3.209 + @{attribute_ref no_vars} rule (see \secref{sec:misc-meth-att}) would
3.210 + be particularly useful to suppress printing of schematic variables.
3.211 +
3.212 + \item [@{text "@{prop \<phi>}"}] prints a well-typed proposition @{text
3.213 + "\<phi>"}.
3.214 +
3.215 + \item [@{text "@{term t}"}] prints a well-typed term @{text "t"}.
3.216 +
3.217 + \item [@{text "@{const c}"}] prints a logical or syntactic constant
3.218 + @{text "c"}.
3.219 +
3.220 + \item [@{text "@{abbrev c x\<^sub>1 \<dots> x\<^sub>n}"}] prints a constant
3.221 + abbreviation @{text "c x\<^sub>1 \<dots> x\<^sub>n \<equiv> rhs"} as defined in
3.222 + the current context.
3.223 +
3.224 + \item [@{text "@{typeof t}"}] prints the type of a well-typed term
3.225 + @{text "t"}.
3.226 +
3.227 + \item [@{text "@{typ \<tau>}"}] prints a well-formed type @{text "\<tau>"}.
3.228 +
3.229 + \item [@{text "@{thm_style s a}"}] prints theorem @{text a},
3.230 + previously applying a style @{text s} to it (see below).
3.231 +
3.232 + \item [@{text "@{term_style s t}"}] prints a well-typed term @{text
3.233 + t} after applying a style @{text s} to it (see below).
3.234 +
3.235 + \item [@{text "@{text s}"}] prints uninterpreted source text @{text
3.236 + s}. This is particularly useful to print portions of text according
3.237 + to the Isabelle {\LaTeX} output style, without demanding
3.238 + well-formedness (e.g.\ small pieces of terms that should not be
3.239 + parsed or type-checked yet).
3.240 +
3.241 + \item [@{text "@{goals}"}] prints the current \emph{dynamic} goal
3.242 + state. This is mainly for support of tactic-emulation scripts
3.243 + within Isar --- presentation of goal states does not conform to
3.244 + actual human-readable proof documents.
3.245 +
3.246 + Please do not include goal states into document output unless you
3.247 + really know what you are doing!
3.248 +
3.249 + \item [@{text "@{subgoals}"}] is similar to @{text "@{goals}"}, but
3.250 + does not print the main goal.
3.251 +
3.252 + \item [@{text "@{prf a\<^sub>1 \<dots> a\<^sub>n}"}] prints the (compact)
3.253 + proof terms corresponding to the theorems @{text "a\<^sub>1 \<dots>
3.254 + a\<^sub>n"}. Note that this requires proof terms to be switched on
3.255 + for the current object logic (see the ``Proof terms'' section of the
3.256 + Isabelle reference manual for information on how to do this).
3.257 +
3.258 + \item [@{text "@{full_prf a\<^sub>1 \<dots> a\<^sub>n}"}] is like @{text
3.259 + "@{prf a\<^sub>1 \<dots> a\<^sub>n}"}, but displays the full proof terms,
3.260 + i.e.\ also displays information omitted in the compact proof term,
3.261 + which is denoted by ``@{text _}'' placeholders there.
3.262 +
3.263 + \item [@{text "@{ML s}"}, @{text "@{ML_type s}"}, and @{text
3.264 + "@{ML_struct s}"}] check text @{text s} as ML value, type, and
3.265 + structure, respectively. The source is displayed verbatim.
3.266 +
3.267 + \end{descr}
3.268 +
3.269 + \medskip The following standard styles for use with @{text
3.270 + thm_style} and @{text term_style} are available:
3.271 +
3.272 + \begin{descr}
3.273 +
3.274 + \item [@{text lhs}] extracts the first argument of any application
3.275 + form with at least two arguments -- typically meta-level or
3.276 + object-level equality, or any other binary relation.
3.277 +
3.278 + \item [@{text rhs}] is like @{text lhs}, but extracts the second
3.279 + argument.
3.280 +
3.281 + \item [@{text "concl"}] extracts the conclusion @{text C} from a rule
3.282 + in Horn-clause normal form @{text "A\<^sub>1 \<Longrightarrow> \<dots> A\<^sub>n \<Longrightarrow> C"}.
3.283 +
3.284 + \item [@{text "prem1"}, \dots, @{text "prem9"}] extract premise
3.285 + number @{text "1, \<dots>, 9"}, respectively, from from a rule in
3.286 + Horn-clause normal form @{text "A\<^sub>1 \<Longrightarrow> \<dots> A\<^sub>n \<Longrightarrow> C"}
3.287 +
3.288 + \end{descr}
3.289 +
3.290 + \medskip
3.291 + The following options are available to tune the output. Note that most of
3.292 + these coincide with ML flags of the same names (see also \cite{isabelle-ref}).
3.293 +
3.294 + \begin{descr}
3.295 +
3.296 + \item[@{text "show_types = bool"} and @{text "show_sorts = bool"}]
3.297 + control printing of explicit type and sort constraints.
3.298 +
3.299 + \item[@{text "show_structs = bool"}] controls printing of implicit
3.300 + structures.
3.301 +
3.302 + \item[@{text "long_names = bool"}] forces names of types and
3.303 + constants etc.\ to be printed in their fully qualified internal
3.304 + form.
3.305 +
3.306 + \item[@{text "short_names = bool"}] forces names of types and
3.307 + constants etc.\ to be printed unqualified. Note that internalizing
3.308 + the output again in the current context may well yield a different
3.309 + result.
3.310 +
3.311 + \item[@{text "unique_names = bool"}] determines whether the printed
3.312 + version of qualified names should be made sufficiently long to avoid
3.313 + overlap with names declared further back. Set to @{text false} for
3.314 + more concise output.
3.315 +
3.316 + \item[@{text "eta_contract = bool"}] prints terms in @{text
3.317 + \<eta>}-contracted form.
3.318 +
3.319 + \item[@{text "display = bool"}] indicates if the text is to be
3.320 + output as multi-line ``display material'', rather than a small piece
3.321 + of text without line breaks (which is the default).
3.322 +
3.323 + \item[@{text "break = bool"}] controls line breaks in non-display
3.324 + material.
3.325 +
3.326 + \item[@{text "quotes = bool"}] indicates if the output should be
3.327 + enclosed in double quotes.
3.328 +
3.329 + \item[@{text "mode = name"}] adds @{text name} to the print mode to
3.330 + be used for presentation (see also \cite{isabelle-ref}). Note that
3.331 + the standard setup for {\LaTeX} output is already present by
3.332 + default, including the modes @{text latex} and @{text xsymbols}.
3.333 +
3.334 + \item[@{text "margin = nat"} and @{text "indent = nat"}] change the
3.335 + margin or indentation for pretty printing of display material.
3.336 +
3.337 + \item[@{text "source = bool"}] prints the source text of the
3.338 + antiquotation arguments, rather than the actual value. Note that
3.339 + this does not affect well-formedness checks of @{antiquotation
3.340 + "thm"}, @{antiquotation "term"}, etc. (only the @{antiquotation
3.341 + "text"} antiquotation admits arbitrary output).
3.342 +
3.343 + \item[@{text "goals_limit = nat"}] determines the maximum number of
3.344 + goals to be printed.
3.345 +
3.346 + \item[@{text "locale = name"}] specifies an alternative locale
3.347 + context used for evaluating and printing the subsequent argument.
3.348 +
3.349 + \end{descr}
3.350 +
3.351 + For boolean flags, ``@{text "name = true"}'' may be abbreviated as
3.352 + ``@{text name}''. All of the above flags are disabled by default,
3.353 + unless changed from ML.
3.354 +
3.355 + \medskip Note that antiquotations do not only spare the author from
3.356 + tedious typing of logical entities, but also achieve some degree of
3.357 + consistency-checking of informal explanations with formal
3.358 + developments: well-formedness of terms and types with respect to the
3.359 + current theory or proof context is ensured here.
3.360 +*}
3.361 +
3.362 +
3.363 +section {* Tagged commands \label{sec:tags} *}
3.364 +
3.365 +text {*
3.366 + Each Isabelle/Isar command may be decorated by presentation tags:
3.367 +
3.368 + \indexouternonterm{tags}
3.369 + \begin{rail}
3.370 + tags: ( tag * )
3.371 + ;
3.372 + tag: '\%' (ident | string)
3.373 + \end{rail}
3.374 +
3.375 + The tags @{text "theory"}, @{text "proof"}, @{text "ML"} are already
3.376 + pre-declared for certain classes of commands:
3.377 +
3.378 + \medskip
3.379 +
3.380 + \begin{tabular}{ll}
3.381 + @{text "theory"} & theory begin/end \\
3.382 + @{text "proof"} & all proof commands \\
3.383 + @{text "ML"} & all commands involving ML code \\
3.384 + \end{tabular}
3.385 +
3.386 + \medskip The Isabelle document preparation system (see also
3.387 + \cite{isabelle-sys}) allows tagged command regions to be presented
3.388 + specifically, e.g.\ to fold proof texts, or drop parts of the text
3.389 + completely.
3.390 +
3.391 + For example ``@{command "by"}~@{text "%invisible auto"}'' would
3.392 + cause that piece of proof to be treated as @{text invisible} instead
3.393 + of @{text "proof"} (the default), which may be either show or hidden
3.394 + depending on the document setup. In contrast, ``@{command
3.395 + "by"}~@{text "%visible auto"}'' would force this text to be shown
3.396 + invariably.
3.397 +
3.398 + Explicit tag specifications within a proof apply to all subsequent
3.399 + commands of the same level of nesting. For example, ``@{command
3.400 + "proof"}~@{text "%visible \<dots>"}~@{command "qed"}'' would force the
3.401 + whole sub-proof to be typeset as @{text visible} (unless some of its
3.402 + parts are tagged differently).
3.403 +*}
3.404 +
3.405 +
3.406 +section {* Draft presentation *}
3.407 +
3.408 +text {*
3.409 + \begin{matharray}{rcl}
3.410 + @{command_def "display_drafts"}@{text "\<^sup>*"} & : & \isarkeep{\cdot} \\
3.411 + @{command_def "print_drafts"}@{text "\<^sup>*"} & : & \isarkeep{\cdot} \\
3.412 + \end{matharray}
3.413 +
3.414 + \begin{rail}
3.415 + ('display\_drafts' | 'print\_drafts') (name +)
3.416 + ;
3.417 + \end{rail}
3.418 +
3.419 + \begin{descr}
3.420 +
3.421 + \item [@{command "display_drafts"}~@{text paths} and @{command
3.422 + "print_drafts"}~@{text paths}] perform simple output of a given list
3.423 + of raw source files. Only those symbols that do not require
3.424 + additional {\LaTeX} packages are displayed properly, everything else
3.425 + is left verbatim.
3.426 +
3.427 + \end{descr}
3.428 +*}
3.429 +
3.430 +end
4.1 --- a/doc-src/IsarRef/Thy/ROOT.ML Mon Jun 02 22:50:29 2008 +0200
4.2 +++ b/doc-src/IsarRef/Thy/ROOT.ML Mon Jun 02 22:50:54 2008 +0200
4.3 @@ -8,6 +8,7 @@
4.4 use_thy "Outer_Syntax";
4.5 use_thy "Spec";
4.6 use_thy "Proof";
4.7 +use_thy "Document_Preparation";
4.8 use_thy "pure";
4.9 use_thy "Generic";
4.10 use_thy "HOL_Specific";