--- a/doc-src/IsarRef/IsaMakefile Mon Jun 02 22:50:29 2008 +0200
+++ b/doc-src/IsarRef/IsaMakefile Mon Jun 02 22:50:54 2008 +0200
@@ -23,8 +23,8 @@
$(LOG)/HOL-IsarRef.gz: Thy/ROOT.ML ../antiquote_setup.ML \
Thy/Introduction.thy Thy/Outer_Syntax.thy Thy/Spec.thy Thy/Proof.thy \
- Thy/pure.thy Thy/Generic.thy Thy/HOL_Specific.thy \
- Thy/Quick_Reference.thy Thy/ML_Tactic.thy
+ Thy/pure.thy Thy/Document_Preparation.thy Thy/Generic.thy \
+ Thy/HOL_Specific.thy Thy/Quick_Reference.thy Thy/ML_Tactic.thy
@$(USEDIR) -s IsarRef HOL Thy
--- a/doc-src/IsarRef/Makefile Mon Jun 02 22:50:29 2008 +0200
+++ b/doc-src/IsarRef/Makefile Mon Jun 02 22:50:54 2008 +0200
@@ -13,7 +13,7 @@
NAME = isar-ref
-FILES = isar-ref.tex style.sty Thy/document/Generic.tex \
+FILES = isar-ref.tex style.sty basics.tex Thy/document/Generic.tex \
Thy/document/HOLCF_Specific.tex Thy/document/HOL_Specific.tex \
Thy/document/ML_Tactic.tex Thy/document/Proof.tex \
Thy/document/Quick_Reference.tex Thy/document/Spec.tex \
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc-src/IsarRef/Thy/Document_Preparation.thy Mon Jun 02 22:50:54 2008 +0200
@@ -0,0 +1,427 @@
+(* $Id$ *)
+
+theory Document_Preparation
+imports Main
+begin
+
+chapter {* Document preparation \label{ch:document-prep} *}
+
+text {*
+ Isabelle/Isar provides a simple document preparation system based on
+ existing {PDF-\LaTeX} technology, with full support of hyper-links
+ (both local references and URLs) and bookmarks. Thus the results
+ are equally well suited for WWW browsing and as printed copies.
+
+ \medskip Isabelle generates {\LaTeX} output as part of the run of a
+ \emph{logic session} (see also \cite{isabelle-sys}). Getting
+ started with a working configuration for common situations is quite
+ easy by using the Isabelle @{verbatim mkdir} and @{verbatim make}
+ tools. First invoke
+\begin{ttbox}
+ isatool mkdir Foo
+\end{ttbox}
+ to initialize a separate directory for session @{verbatim Foo} ---
+ it is safe to experiment, since @{verbatim "isatool mkdir"} never
+ overwrites existing files. Ensure that @{verbatim "Foo/ROOT.ML"}
+ holds ML commands to load all theories required for this session;
+ furthermore @{verbatim "Foo/document/root.tex"} should include any
+ special {\LaTeX} macro packages required for your document (the
+ default is usually sufficient as a start).
+
+ The session is controlled by a separate @{verbatim IsaMakefile}
+ (with crude source dependencies by default). This file is located
+ one level up from the @{verbatim Foo} directory location. Now
+ invoke
+\begin{ttbox}
+ isatool make Foo
+\end{ttbox}
+ to run the @{verbatim Foo} session, with browser information and
+ document preparation enabled. Unless any errors are reported by
+ Isabelle or {\LaTeX}, the output will appear inside the directory
+ @{verbatim ISABELLE_BROWSER_INFO}, as reported by the batch job in
+ verbose mode.
+
+ \medskip You may also consider to tune the @{verbatim usedir}
+ options in @{verbatim IsaMakefile}, for example to change the output
+ format from @{verbatim pdf} to @{verbatim dvi}, or activate the
+ @{verbatim "-D"} option to retain a second copy of the generated
+ {\LaTeX} sources.
+
+ \medskip See \emph{The Isabelle System Manual} \cite{isabelle-sys}
+ for further details on Isabelle logic sessions and theory
+ presentation. The Isabelle/HOL tutorial \cite{isabelle-hol-book}
+ also covers theory presentation issues.
+*}
+
+
+section {* Markup commands \label{sec:markup} *}
+
+text {*
+ \begin{matharray}{rcl}
+ @{command_def "chapter"} & : & \isarkeep{local{\dsh}theory} \\
+ @{command_def "section"} & : & \isarkeep{local{\dsh}theory} \\
+ @{command_def "subsection"} & : & \isarkeep{local{\dsh}theory} \\
+ @{command_def "subsubsection"} & : & \isarkeep{local{\dsh}theory} \\
+ @{command_def "text"} & : & \isarkeep{local{\dsh}theory} \\
+ @{command_def "text_raw"} & : & \isarkeep{local{\dsh}theory} \\[0.5ex]
+ @{command_def "sect"} & : & \isartrans{proof}{proof} \\
+ @{command_def "subsect"} & : & \isartrans{proof}{proof} \\
+ @{command_def "subsubsect"} & : & \isartrans{proof}{proof} \\
+ @{command_def "txt"} & : & \isartrans{proof}{proof} \\
+ @{command_def "txt_raw"} & : & \isartrans{proof}{proof} \\
+ \end{matharray}
+
+ Apart from formal comments (see \secref{sec:comments}), markup
+ commands provide a structured way to insert text into the document
+ generated from a theory (see \cite{isabelle-sys} for more
+ information on Isabelle's document preparation tools).
+
+ \begin{rail}
+ ('chapter' | 'section' | 'subsection' | 'subsubsection' | 'text') target? text
+ ;
+ ('text\_raw' | 'sect' | 'subsect' | 'subsubsect' | 'txt' | 'txt\_raw') text
+ ;
+ \end{rail}
+
+ \begin{descr}
+
+ \item [@{command "chapter"}, @{command "section"}, @{command
+ "subsection"}, and @{command "subsubsection"}] mark chapter and
+ section headings.
+
+ \item [@{command "text"} and @{command "txt"}] specify paragraphs of
+ plain text.
+
+ \item [@{command "text_raw"} and @{command "txt_raw"}] insert
+ {\LaTeX} source into the output, without additional markup. Thus
+ the full range of document manipulations becomes available.
+
+ \end{descr}
+
+ The @{text "text"} argument of these markup commands (except for
+ @{command "text_raw"}) may contain references to formal entities
+ (``antiquotations'', see also \secref{sec:antiq}). These are
+ interpreted in the present theory context, or the named @{text
+ "target"}.
+
+ Any of these markup elements corresponds to a {\LaTeX} command with
+ the name prefixed by @{verbatim "\\isamarkup"}. For the sectioning
+ commands this is a plain macro with a single argument, e.g.\
+ @{verbatim "\\isamarkupchapter{"}@{text "\<dots>"}@{verbatim "}"} for
+ @{command "chapter"}. The @{command "text"} markup results in a
+ {\LaTeX} environment @{verbatim "\\begin{isamarkuptext}"} @{text
+ "\<dots>"} @{verbatim "\\end{isamarkuptext}"}, while @{command "text_raw"}
+ causes the text to be inserted directly into the {\LaTeX} source.
+
+ \medskip The proof markup commands closely resemble those for theory
+ specifications, but have a different formal status and produce
+ different {\LaTeX} macros. Also note that the @{command_ref
+ "header"} declaration (see \secref{sec:begin-thy}) admits to insert
+ section markup just preceding the actual theory definition.
+*}
+
+
+section {* Antiquotations \label{sec:antiq} *}
+
+text {*
+ \begin{matharray}{rcl}
+ @{antiquotation_def "theory"} & : & \isarantiq \\
+ @{antiquotation_def "thm"} & : & \isarantiq \\
+ @{antiquotation_def "prop"} & : & \isarantiq \\
+ @{antiquotation_def "term"} & : & \isarantiq \\
+ @{antiquotation_def const} & : & \isarantiq \\
+ @{antiquotation_def abbrev} & : & \isarantiq \\
+ @{antiquotation_def typeof} & : & \isarantiq \\
+ @{antiquotation_def typ} & : & \isarantiq \\
+ @{antiquotation_def thm_style} & : & \isarantiq \\
+ @{antiquotation_def term_style} & : & \isarantiq \\
+ @{antiquotation_def "text"} & : & \isarantiq \\
+ @{antiquotation_def goals} & : & \isarantiq \\
+ @{antiquotation_def subgoals} & : & \isarantiq \\
+ @{antiquotation_def prf} & : & \isarantiq \\
+ @{antiquotation_def full_prf} & : & \isarantiq \\
+ @{antiquotation_def ML} & : & \isarantiq \\
+ @{antiquotation_def ML_type} & : & \isarantiq \\
+ @{antiquotation_def ML_struct} & : & \isarantiq \\
+ \end{matharray}
+
+ The text body of formal comments (see also \secref{sec:comments})
+ may contain antiquotations of logical entities, such as theorems,
+ terms and types, which are to be presented in the final output
+ produced by the Isabelle document preparation system (see also
+ \chref{ch:document-prep}).
+
+ Thus embedding of ``@{text "@{term [show_types] \"f x = a + x\"}"}''
+ within a text block would cause
+ \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
+ antiquotations may involve attributes as well. For example,
+ @{text "@{thm sym [no_vars]}"} would print the theorem's
+ statement where all schematic variables have been replaced by fixed
+ ones, which are easier to read.
+
+ \begin{rail}
+ atsign lbrace antiquotation rbrace
+ ;
+
+ antiquotation:
+ 'theory' options name |
+ 'thm' options thmrefs |
+ 'prop' options prop |
+ 'term' options term |
+ 'const' options term |
+ 'abbrev' options term |
+ 'typeof' options term |
+ 'typ' options type |
+ 'thm\_style' options name thmref |
+ 'term\_style' options name term |
+ 'text' options name |
+ 'goals' options |
+ 'subgoals' options |
+ 'prf' options thmrefs |
+ 'full\_prf' options thmrefs |
+ 'ML' options name |
+ 'ML\_type' options name |
+ 'ML\_struct' options name
+ ;
+ options: '[' (option * ',') ']'
+ ;
+ option: name | name '=' name
+ ;
+ \end{rail}
+
+ Note that the syntax of antiquotations may \emph{not} include source
+ comments @{verbatim "(*"}~@{text "\<dots>"}~@{verbatim "*)"} or verbatim
+ text @{verbatim "{"}@{verbatim "*"}~@{text "\<dots>"}~@{verbatim
+ "*"}@{verbatim "}"}.
+
+ \begin{descr}
+
+ \item [@{text "@{theory A}"}] prints the name @{text "A"}, which is
+ guaranteed to refer to a valid ancestor theory in the current
+ context.
+
+ \item [@{text "@{thm a\<^sub>1 \<dots> a\<^sub>n}"}] prints theorems
+ @{text "a\<^sub>1 \<dots> a\<^sub>n"}. Note that attribute specifications
+ may be included as well (see also \secref{sec:syn-att}); the
+ @{attribute_ref no_vars} rule (see \secref{sec:misc-meth-att}) would
+ be particularly useful to suppress printing of schematic variables.
+
+ \item [@{text "@{prop \<phi>}"}] prints a well-typed proposition @{text
+ "\<phi>"}.
+
+ \item [@{text "@{term t}"}] prints a well-typed term @{text "t"}.
+
+ \item [@{text "@{const c}"}] prints a logical or syntactic constant
+ @{text "c"}.
+
+ \item [@{text "@{abbrev c x\<^sub>1 \<dots> x\<^sub>n}"}] prints a constant
+ abbreviation @{text "c x\<^sub>1 \<dots> x\<^sub>n \<equiv> rhs"} as defined in
+ the current context.
+
+ \item [@{text "@{typeof t}"}] prints the type of a well-typed term
+ @{text "t"}.
+
+ \item [@{text "@{typ \<tau>}"}] prints a well-formed type @{text "\<tau>"}.
+
+ \item [@{text "@{thm_style s a}"}] prints theorem @{text a},
+ previously applying a style @{text s} to it (see below).
+
+ \item [@{text "@{term_style s t}"}] prints a well-typed term @{text
+ t} after applying a style @{text s} to it (see below).
+
+ \item [@{text "@{text s}"}] prints uninterpreted source text @{text
+ s}. This is particularly useful to print portions of text according
+ to the Isabelle {\LaTeX} output style, without demanding
+ well-formedness (e.g.\ small pieces of terms that should not be
+ parsed or type-checked yet).
+
+ \item [@{text "@{goals}"}] prints the current \emph{dynamic} goal
+ state. This is mainly for support of tactic-emulation scripts
+ within Isar --- presentation of goal states does not conform to
+ actual human-readable proof documents.
+
+ Please do not include goal states into document output unless you
+ really know what you are doing!
+
+ \item [@{text "@{subgoals}"}] is similar to @{text "@{goals}"}, but
+ does not print the main goal.
+
+ \item [@{text "@{prf a\<^sub>1 \<dots> a\<^sub>n}"}] prints the (compact)
+ proof terms corresponding to the theorems @{text "a\<^sub>1 \<dots>
+ a\<^sub>n"}. Note that this requires proof terms to be switched on
+ for the current object logic (see the ``Proof terms'' section of the
+ Isabelle reference manual for information on how to do this).
+
+ \item [@{text "@{full_prf a\<^sub>1 \<dots> a\<^sub>n}"}] is like @{text
+ "@{prf a\<^sub>1 \<dots> a\<^sub>n}"}, but displays the full proof terms,
+ i.e.\ also displays information omitted in the compact proof term,
+ which is denoted by ``@{text _}'' placeholders there.
+
+ \item [@{text "@{ML s}"}, @{text "@{ML_type s}"}, and @{text
+ "@{ML_struct s}"}] check text @{text s} as ML value, type, and
+ structure, respectively. The source is displayed verbatim.
+
+ \end{descr}
+
+ \medskip The following standard styles for use with @{text
+ thm_style} and @{text term_style} are available:
+
+ \begin{descr}
+
+ \item [@{text lhs}] extracts the first argument of any application
+ form with at least two arguments -- typically meta-level or
+ object-level equality, or any other binary relation.
+
+ \item [@{text rhs}] is like @{text lhs}, but extracts the second
+ argument.
+
+ \item [@{text "concl"}] extracts the conclusion @{text C} from a rule
+ in Horn-clause normal form @{text "A\<^sub>1 \<Longrightarrow> \<dots> A\<^sub>n \<Longrightarrow> C"}.
+
+ \item [@{text "prem1"}, \dots, @{text "prem9"}] extract premise
+ number @{text "1, \<dots>, 9"}, respectively, from from a rule in
+ Horn-clause normal form @{text "A\<^sub>1 \<Longrightarrow> \<dots> A\<^sub>n \<Longrightarrow> C"}
+
+ \end{descr}
+
+ \medskip
+ The following options are available to tune the output. Note that most of
+ these coincide with ML flags of the same names (see also \cite{isabelle-ref}).
+
+ \begin{descr}
+
+ \item[@{text "show_types = bool"} and @{text "show_sorts = bool"}]
+ control printing of explicit type and sort constraints.
+
+ \item[@{text "show_structs = bool"}] controls printing of implicit
+ structures.
+
+ \item[@{text "long_names = bool"}] forces names of types and
+ constants etc.\ to be printed in their fully qualified internal
+ form.
+
+ \item[@{text "short_names = bool"}] forces names of types and
+ constants etc.\ to be printed unqualified. Note that internalizing
+ the output again in the current context may well yield a different
+ result.
+
+ \item[@{text "unique_names = bool"}] determines whether the printed
+ version of qualified names should be made sufficiently long to avoid
+ overlap with names declared further back. Set to @{text false} for
+ more concise output.
+
+ \item[@{text "eta_contract = bool"}] prints terms in @{text
+ \<eta>}-contracted form.
+
+ \item[@{text "display = bool"}] indicates if the text is to be
+ output as multi-line ``display material'', rather than a small piece
+ of text without line breaks (which is the default).
+
+ \item[@{text "break = bool"}] controls line breaks in non-display
+ material.
+
+ \item[@{text "quotes = bool"}] indicates if the output should be
+ enclosed in double quotes.
+
+ \item[@{text "mode = name"}] adds @{text name} to the print mode to
+ be used for presentation (see also \cite{isabelle-ref}). Note that
+ the standard setup for {\LaTeX} output is already present by
+ default, including the modes @{text latex} and @{text xsymbols}.
+
+ \item[@{text "margin = nat"} and @{text "indent = nat"}] change the
+ margin or indentation for pretty printing of display material.
+
+ \item[@{text "source = bool"}] prints the source text of the
+ antiquotation arguments, rather than the actual value. Note that
+ this does not affect well-formedness checks of @{antiquotation
+ "thm"}, @{antiquotation "term"}, etc. (only the @{antiquotation
+ "text"} antiquotation admits arbitrary output).
+
+ \item[@{text "goals_limit = nat"}] determines the maximum number of
+ goals to be printed.
+
+ \item[@{text "locale = name"}] specifies an alternative locale
+ context used for evaluating and printing the subsequent argument.
+
+ \end{descr}
+
+ For boolean flags, ``@{text "name = true"}'' may be abbreviated as
+ ``@{text name}''. All of the above flags are disabled by default,
+ unless changed from ML.
+
+ \medskip Note that antiquotations do not only spare the author from
+ tedious typing of logical entities, but also achieve some degree of
+ consistency-checking of informal explanations with formal
+ developments: well-formedness of terms and types with respect to the
+ current theory or proof context is ensured here.
+*}
+
+
+section {* Tagged commands \label{sec:tags} *}
+
+text {*
+ Each Isabelle/Isar command may be decorated by presentation tags:
+
+ \indexouternonterm{tags}
+ \begin{rail}
+ tags: ( tag * )
+ ;
+ tag: '\%' (ident | string)
+ \end{rail}
+
+ The tags @{text "theory"}, @{text "proof"}, @{text "ML"} are already
+ pre-declared for certain classes of commands:
+
+ \medskip
+
+ \begin{tabular}{ll}
+ @{text "theory"} & theory begin/end \\
+ @{text "proof"} & all proof commands \\
+ @{text "ML"} & all commands involving ML code \\
+ \end{tabular}
+
+ \medskip The Isabelle document preparation system (see also
+ \cite{isabelle-sys}) allows tagged command regions to be presented
+ specifically, e.g.\ to fold proof texts, or drop parts of the text
+ completely.
+
+ For example ``@{command "by"}~@{text "%invisible auto"}'' would
+ cause that piece of proof to be treated as @{text invisible} instead
+ of @{text "proof"} (the default), which may be either show or hidden
+ depending on the document setup. In contrast, ``@{command
+ "by"}~@{text "%visible auto"}'' would force this text to be shown
+ invariably.
+
+ Explicit tag specifications within a proof apply to all subsequent
+ commands of the same level of nesting. For example, ``@{command
+ "proof"}~@{text "%visible \<dots>"}~@{command "qed"}'' would force the
+ whole sub-proof to be typeset as @{text visible} (unless some of its
+ parts are tagged differently).
+*}
+
+
+section {* Draft presentation *}
+
+text {*
+ \begin{matharray}{rcl}
+ @{command_def "display_drafts"}@{text "\<^sup>*"} & : & \isarkeep{\cdot} \\
+ @{command_def "print_drafts"}@{text "\<^sup>*"} & : & \isarkeep{\cdot} \\
+ \end{matharray}
+
+ \begin{rail}
+ ('display\_drafts' | 'print\_drafts') (name +)
+ ;
+ \end{rail}
+
+ \begin{descr}
+
+ \item [@{command "display_drafts"}~@{text paths} and @{command
+ "print_drafts"}~@{text paths}] perform simple output of a given list
+ of raw source files. Only those symbols that do not require
+ additional {\LaTeX} packages are displayed properly, everything else
+ is left verbatim.
+
+ \end{descr}
+*}
+
+end
--- a/doc-src/IsarRef/Thy/ROOT.ML Mon Jun 02 22:50:29 2008 +0200
+++ b/doc-src/IsarRef/Thy/ROOT.ML Mon Jun 02 22:50:54 2008 +0200
@@ -8,6 +8,7 @@
use_thy "Outer_Syntax";
use_thy "Spec";
use_thy "Proof";
+use_thy "Document_Preparation";
use_thy "pure";
use_thy "Generic";
use_thy "HOL_Specific";