nicolas.meric
/
Isabelle_DOF
forked from Isabelle_DOF/Isabelle_DOF
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Pass on manual

This commit is contained in:
Nicolas Méric 2023-04-25 08:29:56 +02:00
parent 1cfc4ac88a
commit 86bf3ea5b9
5 changed files with 41 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Isabelle_DOF/thys/Isa_DOF.thy
View File

@ -2720,12 +2720,13 @@ fun pretty_docitem_antiquotation_generic cid_decl ctxt ({unchecked, define}, src
val inline = Config.get ctxt Document_Antiquotation.thy_output_display
val _ = check_and_mark ctxt cid_decl {strict_checking = not unchecked}
{inline = inline} pos str
val cid_decl' = DOF_core.output_name cid_decl
in
(case (define,inline) of
(true,false) => XML.enclose("{\\isaDofDOTlabel[type={"^cid_decl^"}] {")"}}"
|(false,false)=> XML.enclose("{\\isaDofDOTref[type={"^cid_decl^"}] {")"}}"
|(true,true) => XML.enclose("{\\isaDofDOTmacroDef[type={"^cid_decl^"}]{")"}}"
|(false,true) => XML.enclose("{\\isaDofDOTmacroExp[type={"^cid_decl^"}]{")"}}"
(true,false) => XML.enclose("{\\isaDofDOTlabel[type={"^cid_decl'^"}] {")"}}"
|(false,false)=> XML.enclose("{\\isaDofDOTref[type={"^cid_decl'^"}] {")"}}"
|(true,true) => XML.enclose("{\\isaDofDOTmacroDef[type={"^cid_decl'^"}]{")"}}"
|(false,true) => XML.enclose("{\\isaDofDOTmacroExp[type={"^cid_decl'^"}]{")"}}"
)
(Latex.text (DOF_core.output_name str, pos))
end

25
Isabelle_DOF/thys/manual/M_02_Background.thy
View File

@ -36,7 +36,7 @@ architecture may be understood as an extension and refinement of the traditional
with explicit infrastructure for building derivative systems.\<close>''~@{cite "wenzel.ea:building:2007"}
The current system framework offers moreover the following features:
\<^item> a build management grouping components into to pre-compiled sessions,
\<^item> a build management grouping components into pre-compiled sessions,
\<^item> a prover IDE (PIDE) framework~@{cite "wenzel:asynchronous:2014"} with various front-ends,
\<^item> documentation-generation,
\<^item> code generators for various target languages,
@ -75,12 +75,12 @@ declare_reference*[docModGenConcr::figure]
(*>*)
text\<open>
The Isabelle Framework is based on a \<^emph>\<open>document-centric view\<close>\<^bindex>\<open>document-centric view\<close> of
a document, treating the input in its integrality as set of (user-programmable) \<^emph>\<open>document element\<close>
a document, treating the input in its integrality as sets of (user-programmable) \<^emph>\<open>document element\<close>
that may mutually depend on and link to each other; A \<^emph>\<open>document\<close> in our sense is what is configured
in a set of \<^verbatim>\<open>ROOT\<close>- and \<^verbatim>\<open>ROOTS\<close>-files.
Isabelle assumes a hierarchical document model\<^index>\<open>document model\<close>, \<^ie>, an \<^emph>\<open>integrated\<close> document
consist of a hierarchy of \<^emph>\<open>sub-documents\<close> (files); dependencies are restricted to be
consists of a hierarchy of \<^emph>\<open>sub-documents\<close> (files); dependencies are restricted to be
acyclic at this level (c.f. @{figure (unchecked) "docModGenConcr"}).
Document parts can have different document types in order to capture documentations consisting of
documentation, models, proofs, code of various forms and other technical artifacts. We call the
@ -111,7 +111,7 @@ text*[docModGenConcr::float,
text\<open>The body of a theory file consists of a sequence of \<^emph>\<open>commands\<close> that must be introduced
by a command keyword such as \<^boxed_theory_text>\<open>requirement\<close> above. Command keywords may mark
the the begin of a text that is parsed by a command-specific parser; the end of the
the begin of a text that is parsed by a command-specific parser; the end of the
command-span is defined by the next keyword. Commands were used to define definitions, lemmas,
code and text-elements (see @{float "docModGenConcr"}(right)). \<close>
@ -120,7 +120,7 @@ text\<open> A simple text-element \<^index>\<open>text-element\<close> may look
@{boxed_theory_text [display]\<open>
text\<open> This is a simple text.\<close>\<close>}
... so it is a command \<^theory_text>\<open>text\<close> followed by an argument (here in \<open>\<open> ... \<close>\<close> parenthesis) which
contains characters. While \<^theory_text>\<open>text\<close>- elements play a major role in this manual --- document
contains characters. While \<^theory_text>\<open>text\<close>-elements play a major role in this manual --- document
generation is the main use-case of \<^dof> in its current stage --- it is important to note that there
are actually three families of ``ontology aware'' document elements with analogous
syntax to standard ones. The difference is a bracket with meta-data of the form:
@ -134,15 +134,15 @@ value*[label::classid, attr\<^sub>1=E\<^sub>1, ... attr\<^sub>n=E\<^sub>n]\<open
Other instances of document elements belonging to these families are, for example, the freeform
\<^theory_text>\<open>Definition*\<close> and \<^theory_text>\<open>Lemma*\<close> as well as their formal counterparts \<^theory_text>\<open>definition*\<close> and \<^theory_text>\<open>lemma*\<close>,
which allow in addition to their standard Isabelle functionality the creation and management of
ontology-generated meta-data associated to them (cf. -@{text_section (unchecked) "writing_doc"}).
ontology-generated meta-data associated to them (cf. @{text_section (unchecked) "writing_doc"}).
Depending on the family, we will speak about \<^emph>\<open>(formal) text-contexts\<close>,\<^bindex>\<open>formal text-contexts\<close>
\<^emph>\<open>(ML) code-contexts\<close>\<^bindex>\<open>code-contexts\<close> and \<^emph>\<open>term-contexts\<close>\<^bindex>\<open>term-contexts\<close> if we refer
to sub-elements inside the \<open>\<open>...\<close>\<close> cartouches of these command families.
Text- code- or term contexts may contain a special form comment, that may be considered as a
Text- code- or term-contexts may contain a special form comment ???, that may be considered as a
"semantic macro" or a machine-checked annotation: the so-called antiquotations\<^bindex>\<open>antiquotation\<close>.
Its Its general syntactic format reads as follows:
Its general syntactic format reads as follows:
@{boxed_theory_text [display]\<open> @{antiquotation_name (args) [more_args] \<open>sub-context\<close> }\<close>}
@ -155,7 +155,7 @@ Isabelle comes with a number of built-in antiquotations for text- and code-conte
a detailed overview can be found in @{cite "wenzel:isabelle-isar:2020"}. \<^dof> reuses this general
infrastructure but \<^emph>\<open>generates\<close> its own families of antiquotations from ontologies.\<close>
text\<open> An example for a text-element \<^index>\<open>text-element\<close> using built-in antoquotations
text\<open> An example for a text-element \<^index>\<open>text-element\<close> using built-in antiquotations
may look like this:
@{boxed_theory_text [display]\<open>
@ -191,9 +191,10 @@ text*[docModOnto::float,
\<close>
text\<open>Since Isabelle's commands are freely programmable, it is possible to implement \<^dof> as an
extension of the system. In particular, the ontology language of \<^dof> provides an ontology
definition language ODL\<^bindex>\<open>ODL\<close> that \<^emph>\<open>generates\<close> anti-quotations and the infrastructure to check and evaluate
them. This allows for checking an annotated document with respect to a given ontology, which may be
extension of the system. In particular, the ontology language of \<^dof> provides an Ontology
Definition Language (ODL)\<^bindex>\<open>ODL\<close> that \<^emph>\<open>generates\<close> anti-quotations and the infrastructure
to check and evaluate them.
This allows for checking an annotated document with respect to a given ontology, which may be
specific for a given domain-specific universe of discourse (see @{float "docModOnto"}). ODL will
be described in @{text_section (unchecked) "isadof_tour"} in more detail.\<close>

10
Isabelle_DOF/thys/manual/M_03_GuidedTour.thy
View File

@ -106,7 +106,7 @@ subsection*[document::example]\<open>Document Generation\<close>
text\<open>\<^isadof> provides an enhanced setup for generating PDF document. In particular, it does
not make use of a file called \<^verbatim>\<open>document/root.tex\<close>. Instead, the use of document templates and
ontology represenations is done within theory files. To make use of this feature, one needs
ontology representations is done within theory files. To make use of this feature, one needs
to add the option \<^verbatim>\<open>document_build = dof\<close> to the \<^verbatim>\<open>ROOT\<close> file.
An example \<^verbatim>\<open>ROOT\<close> file looks as follows:
\<close>
@ -239,10 +239,10 @@ text\<open>
engineering. We explain first the principles of its underlying ontology, for examples
using these ontologies we refer to the example sessions described in \<^technical>\<open>isadof\<close>.
You can inspect/edit the example in Isabelle's IDE, by either
You can inspect/edit an example in Isabelle's IDE, by either
\<^item> starting Isabelle/jEdit using your graphical user interface (\<^eg>, by clicking on the
Isabelle-Icon provided by the Isabelle installation) and loading the file
\<^nolinkurl>\<open>Isabelle_DOF-Example-I/IsaDofApplications.thy"\<close>
Isabelle-Icon provided by the Isabelle installation) and loading the file
\<^nolinkurl>\<open>Isabelle_DOF-Example-I/IsaDofApplications.thy\<close>
\<^item> starting Isabelle/jEdit from the command line by, \<^eg>, calling:
@{boxed_bash [display]\<open>ë\prompt{\isadofdirn}ë
@ -253,7 +253,7 @@ text\<open>
text\<open> You can build the \<^pdf>-document at the command line by calling:
@{boxed_bash [display] \<open>ë\prompt{}ë isabelle build -d . IsaDofApplications \<close>}
@{boxed_bash [display] \<open>ë\prompt{}ë isabelle build -d . Isabelle_DOF-Example-II \<close>}
\<close>
subsection*[sss::technical]\<open>A Bluffers Guide to the \<^verbatim>\<open>scholarly_paper\<close> Ontology\<close>

13
README.md
View File

@ -45,12 +45,11 @@ Isabelle/DOF is currently consisting out of two AFP entries:
The development version of Isabelle/DOF that is available in this Git repository
provides, over the AFP version, additional ontologies, document templates, and
examples that might not yet "ready for general use". Furthermore, as it is
examples that might not yet be "ready for general use". Furthermore, as it is
provided as an Isabelle component, it can also provide additional tools that
cannot be distributed via the AFP. For more details on installing the
development version, please consult the
[README_DEVELOPMENT.md](./README_DEVELOPMENT.md) file.
After installing the prerequisites, change into the directory containing
Isabelle/DOF (this should be the directory containing this ``README.md`` file)
and execute the following command for building the standard sessions of
@ -62,8 +61,8 @@ foo@bar:~$ isabelle build -D . -x Isabelle_DOF-Proofs -x HOL-Proofs
This will compile Isabelle/DOF and run the example suite.
For building the session ``Isabelle_DOF-Proofs``, the timeout might need to
increased to avoid timeouts during building the dependencies:
For building the session ``Isabelle_DOF-Proofs``, the timeout might need to
be increased to avoid timeouts during building the dependencies ??dependencies building:
```console
foo@bar:~$ isabelle build -d . -o 'timeout_scale=2' Isabelle_DOF-Proofs
@ -114,7 +113,7 @@ in a subdirectory:
requires the core ontologies provided by the ``Isabelle_DOF`` session.
Furthermore, this session is currently under consideration for a submission to
the AFP.
* [Isabelle_DOF-Ontologies](./Isabelle_DOF-Ontologies/): This session provided
* [Isabelle_DOF-Ontologies](./Isabelle_DOF-Ontologies/): This session provides
additional ontologies and document templates.
* [Isabelle_DOF-Unit-Tests](./Isabelle_DOF-Unit-Tests/): This session includes
various tests for the Isabelle/DOF system, partly depending on the ontologies
@ -181,8 +180,8 @@ SPDX-License-Identifier: BSD-2-Clause
* Sergio Bezzecchi, Paolo Crisafulli, Charlotte Pichot, and Burkhart Wolff.
[Making Agile Development Processes fit for V-style Certification
Procedures.](https://hal.archives-ouvertes.fr/hal-01702815/document). In ERTS
2018. <https://hal.archives-ouvertes.fr/hal-01702815>
Procedures.](https://hal.archives-ouvertes.fr/hal-01702815/document).
In ERTS 2018. <https://hal.archives-ouvertes.fr/hal-01702815>
## Upstream Repository

16
README_DEVELOPMENT.md
View File

@ -24,7 +24,7 @@ Both have their own advantages and disadvantages.
If you use the AFP with other Isabelle projects, you might want to install the
complete AFP. For this, please follow the instructions given at
<https://www.isa-afp.org/using.html>.
<https://www.isa-afp.org/using.html>?? using or help see manual 3.1.1.
<!--
As Isabelle session names need to be
unique, you will need to disable the entries ``Isabelle_DOF`` and
@ -54,7 +54,7 @@ Note that this option is not supported for the development version of Isabelle.
Isabelle/DOF is provided as an Isabelle component. After installing the
prerequisites, change into the directory containing Isabelle/DOF (this should be
the directory containing this `README.md` file) and execute (if you executed
the directory containing this `README_DEVELOPMENT.md` file) and execute (if you executed
this command already during the installation of the prerequisites, you can skip
it now):
@ -62,7 +62,8 @@ it now):
foo@bar:~$ isabelle components -u .
```
The final step for the installation is:
Then execute the following command for building the standard sessions of
Isabelle/DOF:
```console
foo@bar:~$ isabelle build -D . -x Isabelle_DOF-Proofs -x HOL-Proofs
@ -70,6 +71,13 @@ foo@bar:~$ isabelle build -D . -x Isabelle_DOF-Proofs -x HOL-Proofs
This will compile Isabelle/DOF and run the example suite.
For building the session ``Isabelle_DOF-Proofs``, the timeout might need to
be increased to avoid timeouts during building the dependencies ??dependencies building:
```console
foo@bar:~$ isabelle build -d . -o 'timeout_scale=2' Isabelle_DOF-Proofs
```
## Usage
Overall, the use of the development version follows the description available
@ -78,7 +86,7 @@ for the AFP version. Hence, for details please consult the Isabelle/DOF manual.
### Creating a New Project
The DOF-plugin provides an alternative to Isabelle's ``mkroot`` command.
Isabelle projects that use DOF need to be created using
Isabelle projects that use DOF need to be created using:
```console
foo@bar:~$ isabelle dof_mkroot