author | Christian Urban <urbanc@in.tum.de> |
Tue, 16 Dec 2008 17:28:05 +0000 | |
changeset 58 | f3794c231898 |
parent 54 | 1783211b3494 |
child 59 | b5914f3c643c |
permissions | -rw-r--r-- |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
1 |
theory Readme |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
2 |
imports Base |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
3 |
begin |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
4 |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
5 |
chapter {* Comments for Authors *} |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
6 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
7 |
text {* |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
8 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
9 |
\begin{itemize} |
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
10 |
\item The cookbook can be compiled on the command-line with: |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
11 |
|
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
12 |
\begin{center} |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
13 |
@{text "isabelle make"} |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
14 |
\end{center} |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
15 |
|
49 | 16 |
\item You can include references to other Isabelle manuals using the |
47
4daf913fdbe1
hakked latex so that it does not display ML {* *}; general tuning
Christian Urban <urbanc@in.tum.de>
parents:
44
diff
changeset
|
17 |
reference names from those manuals. To do this the following |
54
1783211b3494
tuned; added document antiquotation ML_response_fake_both
Christian Urban <urbanc@in.tum.de>
parents:
53
diff
changeset
|
18 |
four \LaTeX{} commands are defined: |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
19 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
20 |
\begin{center} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
21 |
\begin{tabular}{l|c|c} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
22 |
& Chapters & Sections\\\hline |
58 | 23 |
Implementation Manual & @{text "\\ichcite{\<dots>}"} & @{text "\\isccite{\<dots>}"}\\ |
24 |
Isar Reference Manual & @{text "\\rchcite{\<dots>}"} & @{text "\\rsccite{\<dots>}"}\\ |
|
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
25 |
\end{tabular} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
26 |
\end{center} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
27 |
|
58 | 28 |
So @{text "\\ichcite{ch:logic}"} yields a reference for the chapter about logic |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
29 |
in the implementation manual, namely \ichcite{ch:logic}. |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
30 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
31 |
\item There are various document antiquotations defined for the |
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
32 |
cookbook. They allow to check the written text against the current |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
33 |
Isabelle code and also allow to show responses of the ML-compiler. |
52 | 34 |
Therefore authors are strongly encouraged to use antiquotations wherever |
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
35 |
appropriate. |
52 | 36 |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
37 |
The following antiquotations are defined: |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
38 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
39 |
\begin{itemize} |
58 | 40 |
\item[$\bullet$] @{text "@{ML \"expr\" for vars in structs}"} should be used |
41 |
for displaying any ML-ex\-pression, because the antiquotation checks whether |
|
42 |
the expression is valid ML-code. The @{text "for"}- and @{text |
|
43 |
"in"}-arguments are optional. The former is used for evaluating open |
|
44 |
expressions by giving a list of free variables. The latter is used to |
|
45 |
indicate in which structure or structures the ML-expression should be |
|
46 |
evaluated. Examples are: |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
47 |
|
54
1783211b3494
tuned; added document antiquotation ML_response_fake_both
Christian Urban <urbanc@in.tum.de>
parents:
53
diff
changeset
|
48 |
\begin{center}\small |
58 | 49 |
\begin{tabular}{lll} |
50 |
@{text "@{ML \"1 + 3\"}"} & & @{ML "1 + 3"}\\ |
|
51 |
@{text "@{ML \"a + b\" for a b}"} & produce & @{ML "a + b" for a b}\\ |
|
52 |
@{text "@{ML Ident in OuterLex}"} & & @{ML Ident in OuterLex}\\ |
|
53 |
\end{tabular} |
|
54 |
\end{center} |
|
55 |
||
56 |
\item[$\bullet$] @{text "@{ML_response \"expr\" \"pat\"}"} should be used to |
|
57 |
display ML-expressions and their response. The first expression is checked |
|
58 |
like in the antiquotation @{text "@{ML \"expr\"}"}; the second is a pattern |
|
59 |
that specifies the result the first expression produces. This pattern can |
|
60 |
contain @{text "\<dots>"} for parts that you like to omit. The response of the |
|
61 |
first expression will be checked against this pattern. Examples are: |
|
62 |
||
63 |
\begin{center}\small |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
64 |
\begin{tabular}{l} |
58 | 65 |
@{text "@{ML_response \"1+2\" \"3\"}"}\\ |
66 |
@{text "@{ML_response \"(1+2,3)\" \"(3,\<dots>)\"}"} |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
67 |
\end{tabular} |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
68 |
\end{center} |
52 | 69 |
|
58 | 70 |
which produce respectively |
71 |
||
72 |
\begin{center}\small |
|
73 |
\begin{tabular}{p{3cm}p{3cm}} |
|
74 |
@{ML_response "1+2" "3"} & |
|
75 |
@{ML_response "(1+2,3)" "(3,\<dots>)"} |
|
76 |
\end{tabular} |
|
77 |
\end{center} |
|
78 |
||
79 |
Note that this antiquotation can only be used when the result can be |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
80 |
constructed: it does not work when the code produces an exception or returns |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
81 |
an abstract datatype (like @{ML_type thm} or @{ML_type cterm}). |
49 | 82 |
|
58 | 83 |
\item[$\bullet$] @{text "@{ML_response_fake \"expr\" \"pat\"}"} works just |
84 |
like the antiquotation @{text "@{ML_response \"expr\" \"pat\"}"} above, |
|
85 |
except that the result-specification is not checked. Use this antiquotation |
|
86 |
when the result cannot be constructed or the code generates an |
|
87 |
exception. Examples are: |
|
88 |
||
89 |
\begin{center}\small |
|
90 |
\begin{tabular}{ll} |
|
91 |
@{text "@{ML_response"} & @{text "\"cterm_of @{theory} @{term \\\"a + b = c\\\"}\"}"}\\ |
|
92 |
& @{text "\"a + b = c\"}"}\smallskip\\ |
|
93 |
@{text "@{ML_response"} & @{text "\"($$ \\\"x\\\") (explode \\\"world\\\")\""}\\ |
|
94 |
& @{text "\"Exception FAIL raised\"}"} |
|
95 |
\end{tabular} |
|
96 |
\end{center} |
|
97 |
||
54
1783211b3494
tuned; added document antiquotation ML_response_fake_both
Christian Urban <urbanc@in.tum.de>
parents:
53
diff
changeset
|
98 |
|
58 | 99 |
\item[$\bullet$] @{text "@{ML_response_fake_both \"expr\" \"pat\"}"} can be |
54
1783211b3494
tuned; added document antiquotation ML_response_fake_both
Christian Urban <urbanc@in.tum.de>
parents:
53
diff
changeset
|
100 |
used to show erroneous code. Neither the code nor the response will be |
58 | 101 |
checked. An example is: |
52 | 102 |
|
58 | 103 |
\begin{center}\small |
104 |
\begin{tabular}{ll} |
|
105 |
@{text "@{ML_response_fake_both"} & @{text "\"@{cterm \\\"1 + True\\\"}\""}\\ |
|
106 |
& @{text "\"Type unification failed \<dots>\"}"} |
|
107 |
\end{tabular} |
|
108 |
\end{center} |
|
109 |
||
110 |
\item[$\bullet$] @{text "@{ML_file \"name\"}"} should be used when |
|
52 | 111 |
referring to a file. It checks whether the file exists. |
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
112 |
\end{itemize} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
113 |
|
58 | 114 |
The listed antiquotations honour options including @{text "[display]"} and |
115 |
@{text "[quotes]"}. For example |
|
116 |
||
117 |
\begin{center}\small |
|
118 |
@{text "@{ML [quotes] \"\\\"foo\\\" ^ \\\"bar\\\"\"}"} \;\;produces\;\; @{text [quotes] "foobar"} |
|
119 |
\end{center} |
|
120 |
||
121 |
while |
|
122 |
||
123 |
\begin{center}\small |
|
124 |
@{text "@{ML \"\\\"foo\\\" ^ \\\"bar\\\"\"}"} \;\;produces only\;\; @{text "foobar"} |
|
125 |
\end{center} |
|
126 |
||
127 |
||
52 | 128 |
|
49 | 129 |
\item Functions and value bindings cannot be defined inside antiquotations; they need |
130 |
to be included inside \isacommand{ML} \isa{\isacharverbatimopen \ldots \isacharverbatimclose} |
|
58 | 131 |
environments. In this way they are also checked by the compiler. Some \LaTeX-hack in |
132 |
the Cookbook, however, ensures that the environment markers are not printed. |
|
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
133 |
|
53
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
134 |
\item Line numbers can be printed using |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
135 |
\isacommand{ML} \isa{\%linenumbers} \isa{\isacharverbatimopen \ldots \isacharverbatimclose} |
0c3580c831a4
removed the @{ML ...} antiquotation in favour of @{ML_open ...x}
Christian Urban <urbanc@in.tum.de>
parents:
52
diff
changeset
|
136 |
for ML-code or \isacommand{lemma} \isa{\%linenumbers} @{text "..."} for proofs. |
52 | 137 |
|
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
138 |
\end{itemize} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
139 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
140 |
*} |
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
141 |
|
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
142 |
|
49 | 143 |
|
44
dee4b3e66dfe
added a readme chapter for prospective authors; added commands for referring to the Isar Reference Manual
Christian Urban <urbanc@in.tum.de>
parents:
diff
changeset
|
144 |
end |