# HG changeset patch # User wenzelm # Date 1212439854 -7200 # Node ID 3ff111ed85a1d86bb860caaa21b618285a6838af # Parent 8fcf19f2168b6699d1b35b8561aadde39f377802 added Document_Preparation; diff -r 8fcf19f2168b -r 3ff111ed85a1 doc-src/IsarRef/IsaMakefile --- 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 diff -r 8fcf19f2168b -r 3ff111ed85a1 doc-src/IsarRef/Makefile --- 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 \ diff -r 8fcf19f2168b -r 3ff111ed85a1 doc-src/IsarRef/Thy/Document_Preparation.thy --- /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 "\"}@{verbatim "}"} for + @{command "chapter"}. The @{command "text"} markup results in a + {\LaTeX} environment @{verbatim "\\begin{isamarkuptext}"} @{text + "\"} @{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 "\"}~@{verbatim "*)"} or verbatim + text @{verbatim "{"}@{verbatim "*"}~@{text "\"}~@{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 \ a\<^sub>n}"}] prints theorems + @{text "a\<^sub>1 \ 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 \}"}] prints a well-typed proposition @{text + "\"}. + + \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 \ x\<^sub>n}"}] prints a constant + abbreviation @{text "c x\<^sub>1 \ x\<^sub>n \ rhs"} as defined in + the current context. + + \item [@{text "@{typeof t}"}] prints the type of a well-typed term + @{text "t"}. + + \item [@{text "@{typ \}"}] prints a well-formed type @{text "\"}. + + \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 \ a\<^sub>n}"}] prints the (compact) + proof terms corresponding to the theorems @{text "a\<^sub>1 \ + 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 \ a\<^sub>n}"}] is like @{text + "@{prf a\<^sub>1 \ 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 \ \ A\<^sub>n \ C"}. + + \item [@{text "prem1"}, \dots, @{text "prem9"}] extract premise + number @{text "1, \, 9"}, respectively, from from a rule in + Horn-clause normal form @{text "A\<^sub>1 \ \ A\<^sub>n \ 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 + \}-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 \"}~@{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 diff -r 8fcf19f2168b -r 3ff111ed85a1 doc-src/IsarRef/Thy/ROOT.ML --- 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";