Isabelle_DOF
/
Isabelle_DOF
1
0
Fork 2
Code Issues 1 Pull Requests Releases Wiki Activity

First Pass of Chap 4 - Added invariant syntax description, more semantic content

This commit is contained in:
Burkhart Wolff 2020-10-26 12:27:33 +01:00
parent f093b033f5
commit abd32a802d
3 changed files with 152 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
examples/technical_report/Isabelle_DOF-Manual/00_Frontmatter.thy
View File

@ -24,6 +24,7 @@ setup \<open>DOF_lib.define_shortcut \<^binding>\<open>isadof\<close> "\\isad
setup \<open> DOF_lib.define_shortcut \<^binding>\<open>TeXLive\<close>"\\TeXLive" setup \<open> DOF_lib.define_shortcut \<^binding>\<open>TeXLive\<close>"\\TeXLive"
#> DOF_lib.define_shortcut \<^binding>\<open>BibTeX\<close> "\\BibTeX{}" #> DOF_lib.define_shortcut \<^binding>\<open>BibTeX\<close> "\\BibTeX{}"
#> DOF_lib.define_shortcut \<^binding>\<open>LaTeX\<close> "\\LaTeX{}" #> DOF_lib.define_shortcut \<^binding>\<open>LaTeX\<close> "\\LaTeX{}"
#> DOF_lib.define_shortcut \<^binding>\<open>TeX\<close> "\\TeX{}"
#> DOF_lib.define_shortcut \<^binding>\<open>pdf\<close> "PDF" #> DOF_lib.define_shortcut \<^binding>\<open>pdf\<close> "PDF"
#> DOF_lib.define_shortcut \<^binding>\<open>pdftex\<close> "\\pdftex{}" #> DOF_lib.define_shortcut \<^binding>\<open>pdftex\<close> "\\pdftex{}"
\<close> \<close>

285
examples/technical_report/Isabelle_DOF-Manual/04_RefMan.thy
View File

@ -20,14 +20,14 @@ theory
begin begin
(*>*) (*>*)
chapter*[isadof_ontologies::text_section]\<open>Developing Ontologies\<close> chapter*[isadof_ontologies::technical]\<open>Developing Ontologies\<close>
text\<open> text\<open>
In this chapter, we explain the concepts for modeling new ontologies, developing a document In this chapter, we explain the concepts for modeling new ontologies, developing a document
representation for them, as well as developing new document templates. representation for them, as well as developing new document templates.
\<close> \<close>
section*[infrastructure::text_section]\<open>Overview and Technical Infrastructure\<close> section*[infrastructure::technical]\<open>Overview and Technical Infrastructure\<close>
text\<open> text\<open>
\<^isadof> is embedded in the underlying generic document model of Isabelle as described in \<^isadof> is embedded in the underlying generic document model of Isabelle as described in
\<^introduction>\<open>dof\<close>. Recall that the document language can be extended dynamically, \<^ie>, new \<^introduction>\<open>dof\<close>. Recall that the document language can be extended dynamically, \<^ie>, new
@ -36,12 +36,13 @@ text\<open>
Isabelle's document model. Isabelle's document model.
\<^isadof> consists consists basically of four components: \<^isadof> consists consists basically of four components:
\<^item> an own \<^emph>\<open>family of text-elements\<close> such as @{command "title*"}, @{command "chapter*"} \<^item> an own \<^emph>\<open>family of text-elements\<close> such as \<^boxed_theory_text>\<open>title*\<close>, \<^boxed_theory_text>\<open>chapter*\<close>
@{command "text*"}, etc., which can be annotated with meta-information defined in the \<^boxed_theory_text>\<open>text*\<close>, etc., which can be annotated with meta-information defined in the
underlying ontology definition and allow to build a \<^emph>\<open>core\<close> document, underlying ontology definition and allow to build a \<^emph>\<open>core\<close> document,
\<^item> the \<^emph>\<open>ontology definition language\<close> (called ODL) which allow for the definitions \<^item> the \<^emph>\<open>ontology definition language\<close> (called ODL) which allow for the definitions
of document-classes and necessary auxiliary datatypes, of document-classes and necessary auxiliary datatypes,
\<^item> an infrastructure for ontology-specific \<^emph>\<open>layout definitions\<close>, exploiting this meta-information, and \<^item> an infrastructure for ontology-specific \<^emph>\<open>layout definitions\<close>, exploiting this meta-information,
and
\<^item> an infrastructure for generic \<^emph>\<open>layout definitions\<close> for documents following, \<^eg>, the format \<^item> an infrastructure for generic \<^emph>\<open>layout definitions\<close> for documents following, \<^eg>, the format
guidelines of publishers or standardization bodies. guidelines of publishers or standardization bodies.
\<close> \<close>
@ -54,7 +55,7 @@ text\<open>
for which further manual setup steps might be required or that are not fully tested. Also note for which further manual setup steps might be required or that are not fully tested. Also note
that the \<^LaTeX>-class files required by the templates need to be already installed on your that the \<^LaTeX>-class files required by the templates need to be already installed on your
system. This is mostly a problem for publisher specific templates (\<^eg>, Springer's system. This is mostly a problem for publisher specific templates (\<^eg>, Springer's
\path{llncs.cls}), which cannot be re-distributed due to copyright restrictions. \<^path>\<open>llncs.cls\<close>), which cannot be re-distributed due to copyright restrictions.
\<close> \<close>
subsection\<open>Ontologies\<close> subsection\<open>Ontologies\<close>
@ -96,18 +97,18 @@ text\<open>
following steps: following steps:
\<^item> create a new sub-directory \inlinebash|foo| in the directory \inlinebash|src/ontologies| \<^item> create a new sub-directory \inlinebash|foo| in the directory \inlinebash|src/ontologies|
\<^item> definition of the ontological concepts, using \<^isadof>'s Ontology Definition Language (ODL), in \<^item> definition of the ontological concepts, using \<^isadof>'s Ontology Definition Language (ODL), in
a new theory file \path{src/ontologies/foo/foo.thy}. a new theory file \<^path>\<open>src/ontologies/foo/foo.thy\<close>.
\<^item> definition of the document representation for the ontological concepts in a \LaTeX-style \<^item> definition of the document representation for the ontological concepts in a \LaTeX-style
file \path{src/ontologies/foo/DOF-foo.sty} file \<^path>\<open>src/ontologies/foo/DOF-foo.sty\<close>
\<^item> registration (as import) of the new ontology in the file. \<^item> registration (as import) of the new ontology in the file.
\path{src/ontologies/ontologies.thy}. \<^path>\<open>src/ontologies/ontologies.thy\<close>.
\<^item> activation of the new document setup by executing the install script. You can skip the lengthy \<^item> activation of the new document setup by executing the install script. You can skip the lengthy
checks for the AFP entries and the installation of the Isabelle patch by using the checks for the AFP entries and the installation of the Isabelle patch by using the
\inlinebash|--skip-patch-and-afp| option: \inlinebash|--skip-patch-and-afp| option:
\begin{bash} \begin{bash}
ë\prompt{\isadofdirn}ë ./install --skip-patch-and-afp ë\prompt{\isadofdirn}ë ./install --skip-patch-and-afp
\end{bash} \end{bash}
\<close> \<close>
subsection\<open>Document Templates\<close> subsection\<open>Document Templates\<close>
@ -116,7 +117,7 @@ text\<open>
etc.) of the generated documents and are the the main technical means for implementing layout etc.) of the generated documents and are the the main technical means for implementing layout
requirements that are, \<^eg>, required by publishers or standardization bodies. Document-templates requirements that are, \<^eg>, required by publishers or standardization bodies. Document-templates
are stored in a directory are stored in a directory
\path{src/document-templates}:\<^index>\<open>document template!directory structure\<close> \<^path>\<open>src/document-templates\<close>:\<^index>\<open>document template!directory structure\<close>
\begin{center} \begin{center}
\begin{minipage}{.9\textwidth} \begin{minipage}{.9\textwidth}
\dirtree{% \dirtree{%
@ -193,13 +194,13 @@ text\<open>
text\<open> text\<open>
Attributes referring to other ontological concepts are called \<^emph>\<open>links\<close>. The HOL-types inside the Attributes referring to other ontological concepts are called \<^emph>\<open>links\<close>. The HOL-types inside the
document specification language support built-in types for Isabelle/HOL \<^boxed_theory_text>\<open>typ\<close>'s, document specification language support built-in types for Isabelle/HOL \<^boxed_theory_text>\<open>typ\<close>'s,
\<^boxed_theory_text>\<open>term\<close>'s, and \<^boxed_theory_text>\<open>thm\<close>'s reflecting internal Isabelle's internal types for \<^boxed_theory_text>\<open>term\<close>'s, and \<^boxed_theory_text>\<open>thm\<close>'s reflecting internal Isabelle's internal
these entities; when denoted in HOL-terms to instantiate an attribute, for example, there is a types for these entities; when denoted in HOL-terms to instantiate an attribute, for example,
specific syntax (called \<^emph>\<open>inner syntax antiquotations\<close>) that is checked by there is a specific syntax (called \<^emph>\<open>inner syntax antiquotations\<close>) that is checked by
\<^isadof> for consistency. \<^isadof> for consistency.
Document classes\bindex{document class}\index{class!document@see document class} support Document classes\<^bindex>\<open>document class\<close>\<^index>\<open>class!document@see document class\<close> support
\<^boxed_theory_text>\<open>where\<close>-clauses\index{where clause} containing a regular expression over class \<^boxed_theory_text>\<open>where\<close>-clauses\<^index>\<open>where clause\<close> containing a regular expression over class
names. Classes with a \<^boxed_theory_text>\<open>where\<close> were called names. Classes with a \<^boxed_theory_text>\<open>where\<close> were called
\<^emph>\<open>monitor classes\<close>.\<^bindex>\<open>monitor class\<close>\<^index>\<open>class!monitor@see monitor class\<close> While document \<^emph>\<open>monitor classes\<close>.\<^bindex>\<open>monitor class\<close>\<^index>\<open>class!monitor@see monitor class\<close> While document
classes and their inheritance relation structure meta-data of text-elements in an object-oriented classes and their inheritance relation structure meta-data of text-elements in an object-oriented
@ -208,8 +209,9 @@ text\<open>
A major design decision of ODL is to denote attribute values by HOL-terms and HOL-types. A major design decision of ODL is to denote attribute values by HOL-terms and HOL-types.
Consequently, ODL can refer to any predefined type defined in the HOL library, \<^eg>, Consequently, ODL can refer to any predefined type defined in the HOL library, \<^eg>,
\<^boxed_theory_text>\<open>string\<close> or \<^boxed_theory_text>\<open>int\<close> as well as parameterized types, \<^eg>, \<^boxed_theory_text>\<open>_ option\<close>, \<^boxed_theory_text>\<open>string\<close> or \<^boxed_theory_text>\<open>int\<close> as well as parameterized types, \<^eg>,
\<^boxed_theory_text>\<open>_ list\<close>, \<^boxed_theory_text>\<open>_ set\<close>, or products \<^boxed_theory_text>\<open>_ \<times> _\<close>. As a consequence of the \<^boxed_theory_text>\<open>_ option\<close>, \<^boxed_theory_text>\<open>_ list\<close>, \<^boxed_theory_text>\<open>_ set\<close>, or products
\<^boxed_theory_text>\<open>_ \<times> _\<close>. As a consequence of the
document model, ODL definitions may be arbitrarily intertwined with standard HOL type definitions. document model, ODL definitions may be arbitrarily intertwined with standard HOL type definitions.
Finally, document class definitions result in themselves in a HOL-types in order to allow \<^emph>\<open>links\<close> Finally, document class definitions result in themselves in a HOL-types in order to allow \<^emph>\<open>links\<close>
to and between ontological concepts. to and between ontological concepts.
@ -276,37 +278,43 @@ definition of a \<^boxed_theory_text>\<open>doc_class\<close> reject problematic
subsection*["odl-manual1"::technical]\<open>Defining Document Classes\<close> subsection*["odl-manual1"::technical]\<open>Defining Document Classes\<close>
text\<open> text\<open>
A document class\bindex{document class} can be defined using the @{command "doc_class"} keyword: A document class\<^bindex>\<open>document class\<close> can be defined using the @{command "doc_class"} keyword:
\<^item> \<open>class_id\<close>:\index{class\_id@\<open>class_id\<close>} a type-\<open>name\<close> that has been introduced \<^item> \<open>class_id\<close>:\<^index>\<open>class\_id@\<open>class_id\<close>\<close> a type-\<open>name\<close> that has been introduced
via a \<open>doc_class_specification\<close>. via a \<open>doc_class_specification\<close>.
\<^item> \<open>doc_class_specification\<close>:\index{doc\_class\_specification@\<open>doc_class_specification\<close>} \<^item> \<open>doc_class_specification\<close>:\<^index>\<open>doc\_class\_specification@\<open>doc_class_specification\<close>\<close>
We call document classes with an \<open>accepts_clause\<close> We call document classes with an \<open>accepts_clause\<close>
\<^emph>\<open>monitor classes\<close> or \<^emph>\<open>monitors\<close> for short. \<^emph>\<open>monitor classes\<close> or \<^emph>\<open>monitors\<close> for short.
\<^rail>\<open> @@{command "doc_class"} class_id '=' (class_id '+')? (attribute_decl+) \<newline> \<^rail>\<open> @@{command "doc_class"} class_id '=' (class_id '+')? (attribute_decl+) \<newline>
(invariant_decl*)
(accepts_clause rejects_clause?)?\<close> (accepts_clause rejects_clause?)?\<close>
\<^item> \<open>attribute_decl\<close>:\index{attribute\_decl@\<open>attribute_decl\<close>} \<^item> \<open>attribute_decl\<close>:\<^index>\<open>attribute\_decl@\<open>attribute_decl\<close>\<close>
\<^rail>\<open> name '::' '"' type '"' default_clause? \<close> \<^rail>\<open> name '::' '"' type '"' default_clause? \<close>
\<^item> \<open>accepts_clause\<close>:\index{accepts\_clause@\<open>accepts_clause\<close>} \<^item> \<open>invariant_decl\<close>:\<^index>\<open>invariant\_decl@\<open>invariant_decl\<close>\<close>
An invariants can be specified as predicate over document classes represented as
records in HOL. Note that sufficient type information must be provided in order to
disambiguate the argument of the \<open>\<lambda>\<close>-expression.
\<^rail>\<open> 'inv' (name '::')? '"' term '"' \<close>
\<^item> \<open>accepts_clause\<close>:\<^index>\<open>accepts\_clause@\<open>accepts_clause\<close>\<close>
\<^rail>\<open> 'accepts' '"' regexpr '"'\<close> \<^rail>\<open> 'accepts' '"' regexpr '"'\<close>
\<^item> \<open>rejects_clause\<close>:\index{rejects\_clause@\<open>rejects_clause\<close>} \<^clearpage>
\<^item> \<open>rejects_clause\<close>:\<^index>\<open>rejects\_clause@\<open>rejects_clause\<close>\<close>
\<^rail>\<open> 'rejects' (class_id * ',') \<close> \<^rail>\<open> 'rejects' (class_id * ',') \<close>
\<^item> \<open>default_clause\<close>:\index{default\_clause@\<open>default_clause\<close>} \<^item> \<open>default_clause\<close>:\<^index>\<open>default\_clause@\<open>default_clause\<close>\<close>
\<^rail>\<open> '<=' '"' expr '"' \<close> \<^rail>\<open> '<=' '"' expr '"' \<close>
\clearpage \<^item> \<open>regexpr\<close>:\<^index>\<open>regexpr@\<open>regexpr\<close>\<close>
\<^item> \<open>regexpr\<close>:\index{regexpr@\<open>regexpr\<close>}
\<^rail>\<open> '\<lfloor>' class_id '\<rfloor>' | '(' regexpr ')' | (regexpr '||' regexpr) | (regexpr '~~' regexpr) \<^rail>\<open> '\<lfloor>' class_id '\<rfloor>' | '(' regexpr ')' | (regexpr '||' regexpr) | (regexpr '~~' regexpr)
| ('\<lbrace>' regexpr '\<rbrace>') | ( '\<lbrace>' regexpr '\<rbrace>\<^sup>*') \<close> | ('\<lbrace>' regexpr '\<rbrace>') | ( '\<lbrace>' regexpr '\<rbrace>\<^sup>*') \<close>
Regular expressions describe sequences of \<open>class_id\<close>s (and indirect sequences of document Regular expressions describe sequences of \<open>class_id\<close>s (and indirect sequences of document
items corresponding to the \<open>class_id\<close>s). The constructors for alternative, sequence, items corresponding to the \<open>class_id\<close>s). The constructors for alternative, sequence,
repetitions and non-empty sequence follow in the top-down order of the above diagram. repetitions and non-empty sequence follow in the top-down order of the above diagram.
\<close> \<close>
text\<open> text\<open>
\<^isadof> provides a default document representation (\<^ie>, content and layout of the generated \<^isadof> provides a default document representation (\<^ie>, content and layout of the generated
PDF) that only prints the main text, omitting all attributes. \<^isadof> provides the PDF) that only prints the main text, omitting all attributes. \<^isadof> provides the
\inlineltx|\newisadof[]{}|\index{newisadof@\inlineltx{\newisadof}}\index{document class!PDF} \inlineltx|\newisadof[]{}|\<^index>\<open>newisadof@\inlineltx{\newisadof}\<close>\<^index>\<open>document class!PDF\<close>
command for defining a dedicated layout for a document class in \LaTeX. Such a document command for defining a dedicated layout for a document class in \<^LaTeX>. Such a document
class-specific \LaTeX-definition can not only provide a specific layout (\<^eg>, a specific class-specific \<^LaTeX>-definition can not only provide a specific layout (\<^eg>, a specific
highlighting, printing of certain attributes), it can also generate entries in in the table of highlighting, printing of certain attributes), it can also generate entries in in the table of
contents or an index. Overall, the \inlineltx|\newisadof[]{}| command follows the structure contents or an index. Overall, the \inlineltx|\newisadof[]{}| command follows the structure
of the \<^boxed_theory_text>\<open>doc_class\<close>-command: of the \<^boxed_theory_text>\<open>doc_class\<close>-command:
@ -321,42 +329,42 @@ text\<open>
\end{ltx} \end{ltx}
The \<open>class_id\<close> is the full-qualified name of the document class and the list of \<open>attribute_decl\<close> The \<open>class_id\<close> is the full-qualified name of the document class and the list of \<open>attribute_decl\<close>
needs to declare all attributes of the document class. Within the \LaTeX-definition of the document needs to declare all attributes of the document class. Within the \<^LaTeX>-definition of the document
class representation, the identifier \inlineltx|#1| refers to the content of the main text of the class representation, the identifier \inlineltx|#1| refers to the content of the main text of the
document class (written in \<^boxed_theory_text>\<open>\<open> ... \<close>\<close>) and the attributes can be referenced document class (written in \<^boxed_theory_text>\<open>\<open> ... \<close>\<close>) and the attributes can be referenced
by their name using the \inlineltx|\commandkey{...}|-command (see the documentation of the by their name using the \inlineltx|\commandkey{...}|-command (see the documentation of the
\LaTeX-package ``keycommand''~@{cite "chervet:keycommand:2010"} for details). Usually, the \<^LaTeX>-package ``keycommand''~@{cite "chervet:keycommand:2010"} for details). Usually, the
representations definition needs to be wrapped in a representations definition needs to be wrapped in a
\inlineltx|\begin{isarmarkup}...\end{isamarkup}|-environment, to ensure the correct context \inlineltx|\begin{isarmarkup}...\end{isamarkup}|-environment, to ensure the correct context
within Isabelle's \LaTeX-setup. within Isabelle's \<^LaTeX>-setup.
Moreover, \<^isadof> also provides the following two variants of \inlineltx|\newisadof{}[]{}|: Moreover, \<^isadof> also provides the following two variants of \inlineltx|\newisadof{}[]{}|:
\<^item> \inlineltx|\renewisadof{}[]{}|\index{renewisadof@\inlineltx{\renewisadof}} for re-defining \<^item> \inlineltx|\renewisadof{}[]{}|\<^index>\<open>renewisadof@\inlineltx{\renewisadof}\<close> for re-defining
(over-writing) an already defined command, and (over-writing) an already defined command, and
\<^item> \inlineltx|\provideisadof{}[]{}|\index{provideisadof@\inlineltx{\provideisadof}} for providing \<^item> \inlineltx|\provideisadof{}[]{}|\<^index>\<open>provideisadof@\inlineltx{\provideisadof}\<close> for providing
a definition if it is not yet defined. a definition if it is not yet defined.
\<close> \<close>
text\<open> text\<open>
While arbitrary \LaTeX-commands can be used within these commands, While arbitrary \<^LaTeX>-commands can be used within these commands,
special care is required for arguments containing special characters (\<^eg>, the special care is required for arguments containing special characters (\<^eg>, the
underscore ``\_'') that do have a special meaning in \LaTeX. underscore ``\_'') that do have a special meaning in \<^LaTeX>.
Moreover, as usual, special care has to be taken for commands that write into aux-files Moreover, as usual, special care has to be taken for commands that write into aux-files
that are included in a following \LaTeX-run. For such complex examples, we refer the interested that are included in a following \<^LaTeX>-run. For such complex examples, we refer the interested
reader, in general, to the style files provided in the \<^isadof> distribution. In particular reader, in general, to the style files provided in the \<^isadof> distribution. In particular
the definitions of the concepts \<^boxed_theory_text>\<open>title*\<close> and \<^boxed_theory_text>\<open>author*\<close> in the file the definitions of the concepts \<^boxed_theory_text>\<open>title*\<close> and \<^boxed_theory_text>\<open>author*\<close> in the
\path{ontologies/scholarly_paper/DOF-scholarly_paper.sty} show examples of protecting special file \<^file>\<open>../../../src/ontologies/scholarly_paper/DOF-scholarly_paper.sty\<close> show examples of protecting
characters in definitions that need to make use of a entries in an aux-file. special characters in definitions that need to make use of a entries in an aux-file.
\<close> \<close>
subsection\<open>Common Ontology Library (COL)\<close> subsection\<open>Common Ontology Library (COL)\<close>
text\<open>\<^isadof> uses the concept of implicit abstract classes (or: \emph{shadow classes}). text\<open>\<^isadof> uses the concept of implicit abstract classes (or: \<^emph>\<open>shadow classes\<close>).
These refer to the set of possible \<^boxed_theory_text>\<open>doc_class\<close> declarations that posses a number These refer to the set of possible \<^boxed_theory_text>\<open>doc_class\<close> declarations that posses a number
of attributes with their types in common. Shadow classes represent an implicit requirement of attributes with their types in common. Shadow classes represent an implicit requirement
(or pre-condition) on a given class to posses these attributes in order to work properly (or pre-condition) on a given class to posses these attributes in order to work properly
for certain \<^isadof> commands. for certain \<^isadof> commands.
shadow classes will find concrete instances in COL, but \<^isadof> text elements do not \emph{depend} shadow classes will find concrete instances in COL, but \<^isadof> text elements do not \<^emph>\<open>depend\<close>
on our COL definitions: Ontology developers are free to build own class instances for these on our COL definitions: Ontology developers are free to build own class instances for these
shadow classes, with own attributes and, last not least, own definitions of invariants independent shadow classes, with own attributes and, last not least, own definitions of invariants independent
from ours. from ours.
@ -374,20 +382,20 @@ FORMAL_STATEMENT_ALIKE =
\<close>} \<close>}
These shadow-classes correspond to semantic macros These shadow-classes correspond to semantic macros
@{ML "Onto_Macros.enriched_document_command"}, \<^ML>\<open>Onto_Macros.enriched_document_command\<close>,
@{ML "Onto_Macros.assertion_cmd'"}, and \<^ML>\<open>Onto_Macros.assertion_cmd'\<close>, and
@{ML "Onto_Macros.enriched_formal_statement_command"}.\<close> \<^ML>\<open>Onto_Macros.enriched_formal_statement_command\<close>.\<close>
text\<open> \<^isadof> provides a Common Ontology Library (COL)\index{Common Ontology Library@see COL}\bindex{COL} text\<open> \<^isadof> provides a Common Ontology Library (COL)\<^index>\<open>Common Ontology Library@see COL\<close>
that introduces ontology concepts that are either sample instances for shadow classes as we use \<^bindex>\<open>COL\<close> that introduces ontology concepts that are either sample instances for shadow
them in our own document generation processes or, in some cases, are classes as we use them in our own document generation processes or, in some cases, are
so generic that they we expect them to be useful for all types of documents (figures, for example). so generic that they we expect them to be useful for all types of documents (figures, for example).
\<close> \<close>
text\<open> text\<open>
In particular it defines the super-class \<^boxed_theory_text>\<open>text_element\<close>: the In particular it defines the super-class \<^boxed_theory_text>\<open>text_element\<close>: the root of all
root of all text-elements, text-elements,
@{boxed_theory_text [display]\<open> @{boxed_theory_text [display]\<open>
doc_class text_element = doc_class text_element =
@ -396,13 +404,13 @@ doc_class text_element =
variants :: "String.literal set" <= "{STR ''outline'', STR ''document''}" variants :: "String.literal set" <= "{STR ''outline'', STR ''document''}"
\<close>} \<close>}
Here, \<^boxed_theory_text>\<open>level\<close> defines the section-level (\<^eg>, using a \LaTeX-inspired hierarchy: Here, \<^boxed_theory_text>\<open>level\<close> defines the section-level (\<^eg>, using a \<^LaTeX>-inspired hierarchy:
from \<^boxed_theory_text>\<open>Some -1\<close> (corresponding to \inlineltx|\part|) to from \<^boxed_theory_text>\<open>Some -1\<close> (corresponding to \inlineltx|\part|) to
\<^boxed_theory_text>\<open>Some 0\<close> (corresponding to \inlineltx|\chapter|, respectively, \<^boxed_theory_text>\<open>chapter*\<close>) \<^boxed_theory_text>\<open>Some 0\<close> (corresponding to \inlineltx|\chapter|, respectively, \<^boxed_theory_text>\<open>chapter*\<close>)
to \<^boxed_theory_text>\<open>Some 3\<close> (corresponding to \inlineltx|\subsubsection|, respectively, to \<^boxed_theory_text>\<open>Some 3\<close> (corresponding to \inlineltx|\subsubsection|, respectively,
\<^boxed_theory_text>\<open>subsubsection*\<close>). Using an invariant, a derived ontology could, \<^eg>, require that \<^boxed_theory_text>\<open>subsubsection*\<close>). Using an invariant, a derived ontology could, \<^eg>, require that
any sequence of technical-elements must be introduced by a text-element with a higher level any sequence of technical-elements must be introduced by a text-element with a higher level
(this would require that technical text section are introduce by a section element). (this would require that technical text section are introduce by a section element).
Similarly, we provide "minimal" instances of the \<^boxed_theory_text>\<open>ASSERTION_ALIKES\<close> Similarly, we provide "minimal" instances of the \<^boxed_theory_text>\<open>ASSERTION_ALIKES\<close>
and \<^boxed_theory_text>\<open>FORMAL_STATEMENT_ALIKE\<close> shadow classes: and \<^boxed_theory_text>\<open>FORMAL_STATEMENT_ALIKE\<close> shadow classes:
@ -417,8 +425,8 @@ doc_class "thms" =
subsubsection\<open>Example: Text Elemens with Levels\<close> subsubsection\<open>Example: Text Elemens with Levels\<close>
text\<open> text\<open>
The category ``exported constraint (EC)'' is, in the file The category ``exported constraint (EC)'' is, in the file
\path{ontologies/CENELEC_50128/CENELEC_50128.thy} defined as follows: \<^file>\<open>../../../src/ontologies/CENELEC_50128/CENELEC_50128.thy\<close> defined as follows:
@{boxed_theory_text [display]\<open> @{boxed_theory_text [display]\<open>
doc_class requirement = text_element + doc_class requirement = text_element +
@ -430,15 +438,15 @@ doc_class EC = AC +
assumption_kind :: ass_kind <= (*default *) formal assumption_kind :: ass_kind <= (*default *) formal
\<close>} \<close>}
We now define the document representations, in the file We now define the document representations, in the file
\path{ontologies/CENELEC_50128/DOF-CENELEC_50128.sty}. Let us assume that we want to \<^file>\<open>../../../src/ontologies/CENELEC_50128/DOF-CENELEC_50128.sty\<close>. Let us assume that we want to
register the definition of ECs in a dedicated table of contents (\inlineltx{tos}) register the definition of EC's in a dedicated table of contents (\inlineltx{tos})
and use an earlier defined environment \inlineltx|\begin{EC}...\end{EC}| for their graphical and use an earlier defined environment \inlineltx|\begin{EC}...\end{EC}| for their graphical
representation. Note that the \inlineltx|\newisadof{}[]{}|-command requires the representation. Note that the \inlineltx|\newisadof{}[]{}|-command requires the
full-qualified names, \<^eg>, \<^boxed_theory_text>\<open>text.CENELEC_50128.EC\<close> for the document class and full-qualified names, \<^eg>, \<^boxed_theory_text>\<open>text.CENELEC_50128.EC\<close> for the document class and
\<^boxed_theory_text>\<open>CENELEC_50128.requirement.long_name\<close> for the attribute \<^boxed_theory_text>\<open>long_name\<close>, \<^boxed_theory_text>\<open>CENELEC_50128.requirement.long_name\<close> for the attribute \<^boxed_theory_text>\<open>long_name\<close>,
inherited from the document class \<^boxed_theory_text>\<open>requirement\<close>. The representation of ECs inherited from the document class \<^boxed_theory_text>\<open>requirement\<close>. The representation of EC's
can now be defined as follows: can now be defined as follows:
\begin{ltx} \begin{ltx}
\newisadof{text.CENELEC_50128.EC}% \newisadof{text.CENELEC_50128.EC}%
@ -487,8 +495,8 @@ text\<open>We want to check the consequences of this definition and can add the
@{boxed_theory_text [display]\<open> @{boxed_theory_text [display]\<open>
text*[claim::assertions]\<open>For non-empty lists, our definition yields indeed text*[claim::assertions]\<open>For non-empty lists, our definition yields indeed
the last element of a list.\<close> the last element of a list.\<close>
assert*[claim::assertions] "last[4::int] = 4" assert*[claim1::assertions] "last[4::int] = 4"
assert*[claim::assertions] "last[1,2,3,4::int] = 4" assert*[claim2::assertions] "last[1,2,3,4::int] = 4"
\<close>} \<close>}
\<close> \<close>
@ -515,18 +523,18 @@ text\<open>
affiliation = "\<open>Université Paris-Saclay, LRI, Paris, France\<close>"]\<open>Burkhart Wolff\<close> affiliation = "\<open>Université Paris-Saclay, LRI, Paris, France\<close>"]\<open>Burkhart Wolff\<close>
\<close>} \<close>}
In general, all standard text-elements from the Isabelle document model such In general, all standard text-elements from the Isabelle document model such
as @{command "chapter"}, @{command "section"}, @{command "text"}, have in the \<^isadof> as \<^theory_text>\<open>chapter\<close>, \<^theory_text>\<open>section\<close>, \<^theory_text>\<open>text\<close>, have in the \<^isadof>
implementation their counterparts in the family of text-elements that are ontology-aware, implementation their counterparts in the family of text-elements that are ontology-aware,
\<^ie>, they dispose on a meta-argument list that allows to define that a test-element \<^ie>, they dispose on a meta-argument list that allows to define that a test-element
that has an identity as a text-object labelled as \<open>obj_id\<close>, belongs to a document class that has an identity as a text-object labelled as \<open>obj_id\<close>, belongs to a document class
\<open>class_id\<close> that has been defined earlier, and has its class-attributes set with particular \<open>class_id\<close> that has been defined earlier, and has its class-attributes set with particular
values (which are denotable in Isabelle/HOL mathematical term syntax). values (which are denotable in Isabelle/HOL mathematical term syntax).
\<^item> \<open>meta_args\<close> : \<^item> \<open>meta_args\<close> :
\<^rail>\<open>(obj_id ('::' class_id) ((attribute '=' term)) * ',')\<close> \<^rail>\<open>(obj_id ('::' class_id) ((attribute '=' term)) * ',')\<close>
\<^item> \<open>rich_meta_args\<close> : \<^item> \<open>rich_meta_args\<close> :
\<^rail>\<open> (obj_id ('::' class_id) ((attribute (('=' | '+=') term)) * ','))\<close> \<^rail>\<open> (obj_id ('::' class_id) ((attribute (('=' | '+=') term)) * ','))\<close>
\clearpage \<^clearpage>
\<^item> \<open>annotated_text_element\<close> : \<^item> \<open>annotated_text_element\<close> :
\<^rail>\<open> \<^rail>\<open>
( ( @@{command "title*"} ( ( @@{command "title*"}
@ -551,7 +559,7 @@ subsubsection\<open>Experts: Defining New Top-Level Commands\<close>
text\<open> text\<open>
Defining such new top-level commands requires some Isabelle knowledge as well as Defining such new top-level commands requires some Isabelle knowledge as well as
extending the dispatcher of the \LaTeX-backend. For the details of defining top-level extending the dispatcher of the \<^LaTeX>-backend. For the details of defining top-level
commands, we refer the reader to the Isar manual~@{cite "wenzel:isabelle-isar:2020"}. commands, we refer the reader to the Isar manual~@{cite "wenzel:isabelle-isar:2020"}.
Here, we only give a brief example how the \<^boxed_theory_text>\<open>section*\<close>-command is defined; we Here, we only give a brief example how the \<^boxed_theory_text>\<open>section*\<close>-command is defined; we
refer the reader to the source code of \<^isadof> for details. refer the reader to the source code of \<^isadof> for details.
@ -571,8 +579,8 @@ begin
end end
\<close>} \<close>}
Second, given an implementation of the functionality of the new keyword (implemented in SML), Second, given an implementation of the functionality of the new keyword (implemented in SML),
the new keyword needs to be registered, together with its parser, as outer syntax: the new keyword needs to be registered, together with its parser, as outer syntax:
\begin{sml} \begin{sml}
val _ = val _ =
@ -584,7 +592,7 @@ val _ =
\<close> \<close>
text\<open> text\<open>
Finally, for the document generation, a new dispatcher has to be defined in \LaTeX---this is Finally, for the document generation, a new dispatcher has to be defined in \<^LaTeX>---this is
mandatory, otherwise the document generation will break. These dispatcher always follow the same mandatory, otherwise the document generation will break. These dispatcher always follow the same
schemata: schemata:
@ -626,8 +634,8 @@ subsubsection\<open>Meta-types as Types\<close>
text\<open> text\<open>
To express the dependencies between text elements to the formal To express the dependencies between text elements to the formal
entities, \<^eg>, \inlinesml+term+ ($\lambda$-term), \inlinesml+typ+, or entities, \<^eg>, \<^ML_type>\<open>term\<close> (\<open>\<lambda>\<close>-term), \<^ML_type>\<open>typ\<close>, or
\inlinesml+thm+, we represent the types of the implementation language \<^ML_type>\<open>thm\<close>, we represent the types of the implementation language
\<^emph>\<open>inside\<close> the HOL type system. We do, however, not reflect the data of \<^emph>\<open>inside\<close> the HOL type system. We do, however, not reflect the data of
these types. They are just declared abstract types, these types. They are just declared abstract types,
``inhabited'' by special constant symbols carrying strings, for ``inhabited'' by special constant symbols carrying strings, for
@ -639,13 +647,13 @@ text\<open>
\<^boxed_theory_text>\<open>\<theta>\<close>. For example, the \<^boxed_theory_text>\<open>establish\<close> \<^boxed_theory_text>\<open>\<theta>\<close>. For example, the \<^boxed_theory_text>\<open>establish\<close>
attribute in the previous section is the power of the ODL: here, we model attribute in the previous section is the power of the ODL: here, we model
a relation between \<^emph>\<open>claims\<close> and \<^emph>\<open>results\<close> which may be a a relation between \<^emph>\<open>claims\<close> and \<^emph>\<open>results\<close> which may be a
formal, machine-check theorem of type \inlinesml+thm+ denoted by, for formal, machine-check theorem of type \<^ML_type>\<open>thm\<close> denoted by, for
example: \<^boxed_theory_text>\<open>property = "[@{thm "system_is_safe"}]"\<close> in a example: \<^boxed_theory_text>\<open>property = "[@{thm "system_is_safe"}]"\<close> in a
system context \<^boxed_theory_text>\<open>\<theta>\<close> where this theorem is system context \<^boxed_theory_text>\<open>\<theta>\<close> where this theorem is
established. Similarly, attribute values like established. Similarly, attribute values like
\<^boxed_theory_text>\<open>property = "@{term \<open>A \<leftrightarrow> B\<close>}"\<close> \<^boxed_theory_text>\<open>property = "@{term \<open>A \<leftrightarrow> B\<close>}"\<close>
require that the HOL-string \<^boxed_theory_text>\<open>A \<leftrightarrow> B\<close> is require that the HOL-string \<^boxed_theory_text>\<open>A \<leftrightarrow> B\<close> is
again type-checked and represents indeed a formula in $\theta$. Another instance of again type-checked and represents indeed a formula in \<open>\<theta>\<close>. Another instance of
this process, which we call \<open>second-level type-checking\<close>, are term-constants this process, which we call \<open>second-level type-checking\<close>, are term-constants
generated from the ontology such as generated from the ontology such as
\<^boxed_theory_text>\<open>@{definition <string>}\<close>. \<^boxed_theory_text>\<open>@{definition <string>}\<close>.
@ -654,8 +662,8 @@ text\<open>
subsubsection*["sec:monitors"::technical]\<open>ODL Monitors\<close> subsubsection*["sec:monitors"::technical]\<open>ODL Monitors\<close>
text\<open> text\<open>
We call a document class with an accept-clause a \<^emph>\<open>monitor\<close>.\bindex{monitor} Syntactically, an We call a document class with an accept-clause a \<^emph>\<open>monitor\<close>.\<^bindex>\<open>monitor\<close> Syntactically, an
accept-clause\index{accept-clause} contains a regular expression over class identifiers. accept-clause\<^index>\<open>accept-clause\<close> contains a regular expression over class identifiers.
For example: For example:
@{boxed_theory_text [display]\<open> @{boxed_theory_text [display]\<open>
@ -679,10 +687,10 @@ text\<open>
admissible instances along the class hierarchy: admissible instances along the class hierarchy:
\<^item> a superclass in the reject-list and a subclass in the \<^item> a superclass in the reject-list and a subclass in the
accept-expression forbids instances superior to the subclass, and accept-expression forbids instances superior to the subclass, and
\<^item> a subclass $S$ in the reject-list and a superclass $T$ in the \<^item> a subclass $S$ in the reject-list and a superclass \<open>T\<close> in the
accept-list allows instances of superclasses of $T$ to occur freely, accept-list allows instances of superclasses of \<open>T\<close> to occur freely,
instances of $T$ to occur in the specified order and forbids instances of \<open>T\<close> to occur in the specified order and forbids
instances of $S$. instances of \<open>S\<close>.
\<close> \<close>
text\<open> text\<open>
Monitored document sections can be nested and overlap; thus, it is Monitored document sections can be nested and overlap; thus, it is
@ -707,9 +715,10 @@ text\<open>
subsubsection*["sec:class_inv"::technical]\<open>ODL Class Invariants\<close> subsubsection*["sec:class_inv"::technical]\<open>ODL Class Invariants\<close>
text\<open> text\<open>
Ontological classes as described so far are too liberal in many situations. For example, one Ontological classes as described so far are too liberal in many situations. For example, one
would like to express that any instance of a \<^boxed_theory_text>\<open>result\<close> class finally has a non-empty would like to express that any instance of a \<^boxed_theory_text>\<open>result\<close> class finally has a
property list, if its \<^boxed_theory_text>\<open>kind\<close> is \<^boxed_theory_text>\<open>proof\<close>, or that the \<^boxed_theory_text>\<open>establish\<close> non-empty property list, if its \<^boxed_theory_text>\<open>kind\<close> is \<^boxed_theory_text>\<open>proof\<close>, or that
relation between \<^boxed_theory_text>\<open>claim\<close> and \<^boxed_theory_text>\<open>result\<close> is surjective. the \<^boxed_theory_text>\<open>establish\<close> relation between \<^boxed_theory_text>\<open>claim\<close> and
\<^boxed_theory_text>\<open>result\<close> is surjective.
In a high-level syntax, this type of constraints could be expressed, \<^eg>, by: In a high-level syntax, this type of constraints could be expressed, \<^eg>, by:
@ -722,12 +731,12 @@ text\<open>
where \<^boxed_theory_text>\<open>result\<close>, \<^boxed_theory_text>\<open>conclusion\<close>, and \<^boxed_theory_text>\<open>introduction\<close> are the set of where \<^boxed_theory_text>\<open>result\<close>, \<^boxed_theory_text>\<open>conclusion\<close>, and \<^boxed_theory_text>\<open>introduction\<close> are the set of
all possible instances of these document classes. All specified constraints are already checked all possible instances of these document classes. All specified constraints are already checked
in the IDE of \dof while editing; it is however possible to delay a final error message till the in the IDE of \<^dof> while editing; it is however possible to delay a final error message till the
closing of a monitor (see next section). The third constraint enforces that the user sets the closing of a monitor (see next section). The third constraint enforces that the user sets the
\<^boxed_theory_text>\<open>authored_by\<close> set, otherwise an error will be reported. \<^boxed_theory_text>\<open>authored_by\<close> set, otherwise an error will be reported.
For the moment, there is no high-level syntax for the definition of class invariants. A For the moment, there is no high-level syntax for the definition of class invariants. A
formulation, in SML, of the first class-invariant in \autoref{sec:class_inv} is straight-forward: formulation, in SML, of the first class-invariant in \<^technical>\<open>sec:class_inv\<close> is straight-forward:
\begin{sml} \begin{sml}
fun check_result_inv oid {is_monitor:bool} ctxt = fun check_result_inv oid {is_monitor:bool} ctxt =
@ -743,11 +752,11 @@ fun check_result_inv oid {is_monitor:bool} ctxt =
"tiny_cert.result" check_result_inv) "tiny_cert.result" check_result_inv)
\end{sml} \end{sml}
The \inlinesml{setup}-command (last line) registers the \<^boxed_theory_text>\<open>check_result_inv\<close> function The \<^ML>\<open>Theory.setup\<close>-command (last line) registers the \<^boxed_theory_text>\<open>check_result_inv\<close> function
into the \<^isadof> kernel, which activates any creation or modification of an instance of into the \<^isadof> kernel, which activates any creation or modification of an instance of
\<^boxed_theory_text>\<open>result\<close>. We cannot replace \<^boxed_theory_text>\<open>compute_attr_access\<close> by the corresponding \<^boxed_theory_text>\<open>result\<close>. We cannot replace \<^boxed_theory_text>\<open>compute_attr_access\<close> by the
antiquotation \<^boxed_theory_text>\<open>@{docitem_value kind::oid}\<close>, since \<^boxed_theory_text>\<open>oid\<close> is bound to a corresponding antiquotation \<^boxed_theory_text>\<open>@{docitem_value kind::oid}\<close>, since
variable here and can therefore not be statically expanded. \<^boxed_theory_text>\<open>oid\<close> is bound to a variable here and can therefore not be statically expanded.
\<close> \<close>
@ -755,20 +764,20 @@ section*["document-templates"::technical]\<open>Defining Document Templates\<clo
subsection\<open>The Core Template\<close> subsection\<open>The Core Template\<close>
text\<open> text\<open>
Document-templates\bindex{document template} define the overall layout (page size, margins, fonts, Document-templates\<^bindex>\<open>document template\<close> define the overall layout (page size, margins, fonts,
etc.) of the generated documents and are the the main technical means for implementing layout etc.) of the generated documents and are the the main technical means for implementing layout
requirements that are, \<^eg>, required by publishers or standardization bodies. requirements that are, \<^eg>, required by publishers or standardization bodies.
If a new layout is already supported by a \LaTeX-class, then developing basic support for it If a new layout is already supported by a \<^LaTeX>-class, then developing basic support for it
is straight forwards: after reading the authors guidelines of the new template, is straight forwards: after reading the authors guidelines of the new template,
Developing basic support for a new document template is straight forwards In most cases, it is Developing basic support for a new document template is straight forwards In most cases, it is
sufficient to replace the document class in \autoref{lst:dc} of the template and add the sufficient to replace the document class in \autoref{lst:dc} of the template and add the
\LaTeX-packages that are (strictly) required by the used \LaTeX-setup. In general, we recommend \<^LaTeX>-packages that are (strictly) required by the used \<^LaTeX>-setup. In general, we recommend
to only add \LaTeX-packages that are always necessary fro this particular template, as loading to only add \<^LaTeX>-packages that are always necessary fro this particular template, as loading
packages in the templates minimizes the freedom users have by adapting the \path{preample.tex}. packages in the templates minimizes the freedom users have by adapting the \<^path>\<open>preample.tex\<close>.
Moreover, you might want to add/modify the template specific configuration Moreover, you might want to add/modify the template specific configuration
(\autoref{lst:config-start}-\ref{lst:config-end}). The new template should be stored in (\autoref{lst:config-start}-\ref{lst:config-end}). The new template should be stored in
\path{src/document-templates} and its file name should start with the prefix \path{root-}. After \<^path>\<open>src/document-templates\<close> and its file name should start with the prefix \<^path>\<open>root-\<close>. After
adding a new template, call the \inlinebash{install} script (see @{docitem "infrastructure"} adding a new template, call the \inlinebash{install} script (see \<^technical>\<open>infrastructure\<close>
The common structure of an \<^isadof> document template looks as follows: The common structure of an \<^isadof> document template looks as follows:
\begin{ltx}[escapechar=ë, numbers=left,numberstyle=\tiny,xleftmargin=5mm] \begin{ltx}[escapechar=ë, numbers=left,numberstyle=\tiny,xleftmargin=5mm]
@ -808,33 +817,33 @@ text\<open>
subsection\<open>Tips, Tricks, and Known Limitations\<close> subsection\<open>Tips, Tricks, and Known Limitations\<close>
text\<open> text\<open>
In this sectin, we sill discuss several tips and tricks for developing In this sectin, we sill discuss several tips and tricks for developing
new or adapting existing document templates or \LaTeX-represenations of ontologies. new or adapting existing document templates or \<^LaTeX>-represenations of ontologies.
\<close> \<close>
subsubsection\<open>Getting Started\<close> subsubsection\<open>Getting Started\<close>
text\<open> text\<open>
In general, we recommend to create a test project (\<^eg>, using \inlinebash|isabelle mkroot_DOF|) In general, we recommend to create a test project (\<^eg>, using \inlinebash|isabelle mkroot_DOF|)
to develop new document templates or ontology representations. The default setup of the \<^isadof> to develop new document templates or ontology representations. The default setup of the \<^isadof>
build system generated a \path{output/document} directory with a self-contained \LaTeX-setup. In build system generated a \<^path>\<open>output/document\<close> directory with a self-contained \<^LaTeX>-setup. In
this directory, you can directly use \LaTeX{} on the main file, called \path{root.tex}: this directory, you can directly use \<^LaTeX> on the main file, called \<^path>\<open>root.tex\<close>:
\begin{bash} \begin{bash}
ë\prompt{MyProject/output/document}ë pdflatex root.tex ë\prompt{MyProject/output/document}ë pdflatex root.tex
\end{bash} \end{bash}
This allows you to develop and check your \LaTeX-setup without the overhead of running This allows you to develop and check your \<^LaTeX>-setup without the overhead of running
\inlinebash|isabelle build| after each change of your template (or ontology-style). Note that \inlinebash|isabelle build| after each change of your template (or ontology-style). Note that
the content of the \path{output} directory is overwritten by executing the content of the \<^path>\<open>output\<close> directory is overwritten by executing
\inlinebash|isabelle build|. \inlinebash|isabelle build|.
\<close> \<close>
subsubsection\<open>Truncated Warning and Error Messages\<close> subsubsection\<open>Truncated Warning and Error Messages\<close>
text\<open> text\<open>
By default, \LaTeX{} cuts of many warning or error messages after 79 characters. Due to the By default, \<^LaTeX> cuts of many warning or error messages after 79 characters. Due to the
use of full-qualified names in \<^isadof>, this can often result in important information being use of full-qualified names in \<^isadof>, this can often result in important information being
cut off. Thus, it can be very helpful to configure \LaTeX{} in such a way that it prints cut off. Thus, it can be very helpful to configure \<^LaTeX> in such a way that it prints
long error or warning messages. This can easily be done on the command line for individual long error or warning messages. This can easily be done on the command line for individual
\LaTeX{} invocations: \<^LaTeX> invocations:
\begin{bash} \begin{bash}
ë\prompt{MyProject/output/document}ë max_print_line=200 error_line=200 half_error_line=100 pdflatex root.tex ë\prompt{MyProject/output/document}ë max_print_line=200 error_line=200 half_error_line=100 pdflatex root.tex
@ -845,16 +854,16 @@ subsubsection\<open>Deferred Declaration of Information\<close>
text\<open> text\<open>
During document generation, sometimes, information needs to be printed prior to its During document generation, sometimes, information needs to be printed prior to its
declaration in a \<^isadof> theory. This violation the declaration-before-use-principle declaration in a \<^isadof> theory. This violation the declaration-before-use-principle
requires that information is written into an auxiliary file during the first run of \LaTeX{} requires that information is written into an auxiliary file during the first run of \<^LaTeX>
so that the information is available at further runs of \LaTeX{}. While, on the one hand, so that the information is available at further runs of \<^LaTeX>. While, on the one hand,
this is a standard process (\<^eg>, used for updating references), implementing it correctly this is a standard process (\<^eg>, used for updating references), implementing it correctly
requires a solid understanding of \LaTeX's expansion mechanism. In this context, the recently requires a solid understanding of \<^LaTeX>'s expansion mechanism. In this context, the recently
introduced \inlineltx|\expanded{}|-primitive introduced \inlineltx|\expanded{}|-primitive
(see \url{https://www.texdev.net/2018/12/06/a-new-primitive-expanded}) is particularly useful. (see \<^url>\<open>https://www.texdev.net/2018/12/06/a-new-primitive-expanded\<close>) is particularly useful.
Examples of its use can be found, \<^eg>, in the ontology-styles Examples of its use can be found, \<^eg>, in the ontology-styles
\path{ontologies/scholarly_paper/DOF-scholarly_paper.sty} or \<^file>\<open>../../../src/ontologies/scholarly_paper/DOF-scholarly_paper.sty\<close> or
\path{ontologies/CENELEC_50128/DOF-CENELEC_50128.sty}. For details about the expansion mechanism \<^file>\<open>../../../src/ontologies/CENELEC_50128/DOF-CENELEC_50128.sty\<close>. For details about the expansion mechanism
in general, we refer the reader to the \LaTeX{} literature (\<^eg>,~@{cite "knuth:texbook:1986" in general, we refer the reader to the \<^LaTeX> literature (\<^eg>,~@{cite "knuth:texbook:1986"
and "mittelbach.ea:latex:1999" and "eijkhout:latex-cs:2012"}). and "mittelbach.ea:latex:1999" and "eijkhout:latex-cs:2012"}).
\<close> \<close>
@ -863,19 +872,19 @@ subsubsection\<open>Authors and Affiliation Information\<close>
text\<open> text\<open>
In the context of academic papers, the defining the representations for the author and In the context of academic papers, the defining the representations for the author and
affiliation information is particularly challenges as, firstly, they inherently are breaking affiliation information is particularly challenges as, firstly, they inherently are breaking
the declare-before-use-principle and, secondly, each publisher uses a different \LaTeX-setup the declare-before-use-principle and, secondly, each publisher uses a different \<^LaTeX>-setup
for their declaration. Moreover, the mapping from the ontological modeling to the document for their declaration. Moreover, the mapping from the ontological modeling to the document
representation might also need to bridge the gap between different common modeling styles of representation might also need to bridge the gap between different common modeling styles of
authors and their affiliations, namely: affiliations as attributes of authors vs. authors and authors and their affiliations, namely: affiliations as attributes of authors vs. authors and
affiliations both as entities with a many-to-many relationship. affiliations both as entities with a many-to-many relationship.
The ontology representation The ontology representation
\path{ontologies/scholarly_paper/DOF-scholarly_paper.sty} contains an example that, firstly, \<^file>\<open>../../../src/ontologies/scholarly_paper/DOF-scholarly_paper.sty\<close> contains an example that, firstly,
shows how to write the author and affiliation information into the auxiliary file for re-use shows how to write the author and affiliation information into the auxiliary file for re-use
in the next \LaTeX-run and, secondly, shows how to collect the author and affiliation in the next \<^LaTeX>-run and, secondly, shows how to collect the author and affiliation
information into an \inlineltx|\author| and a \inlineltx|\institution| statement, each of information into an \inlineltx|\author| and a \inlineltx|\institution| statement, each of
which containing the information for all authors. The collection of the author information which containing the information for all authors. The collection of the author information
is provided by the following \LaTeX-code: is provided by the following \<^LaTeX>-code:
\begin{ltx} \begin{ltx}
\def\dof@author{}% \def\dof@author{}%
@ -898,7 +907,7 @@ can now be used in the definition of the representation of the concept
\<^boxed_theory_text>\<open>text.scholarly_paper.author\<close>, which writes the collected information in the \<^boxed_theory_text>\<open>text.scholarly_paper.author\<close>, which writes the collected information in the
job's aux-file. The intermediate step of writing this information into the job's aux-file is necessary, job's aux-file. The intermediate step of writing this information into the job's aux-file is necessary,
as the author and affiliation information is required right at the begin of the document as the author and affiliation information is required right at the begin of the document
(\<^ie>, when \LaTeX's \inlineltx|\maketitle| is invoked) while \<^isadof> allows to define authors at (\<^ie>, when \<^LaTeX>'s \inlineltx|\maketitle| is invoked) while \<^isadof> allows to define authors at
any place within a document: any place within a document:
\begin{ltx} \begin{ltx}
@ -944,7 +953,7 @@ subsubsection\<open>Restricting the Use of Ontologies to Specific Templates\<clo
text\<open> text\<open>
As ontology representations might rely on features only provided by certain templates As ontology representations might rely on features only provided by certain templates
(\LaTeX-classes), authors of ontology representations might restrict their use to (\<^LaTeX>-classes), authors of ontology representations might restrict their use to
specific classes. This can, \<^eg>, be done using the \inlineltx|\@ifclassloaded{}| command: specific classes. This can, \<^eg>, be done using the \inlineltx|\@ifclassloaded{}| command:
\begin{ltx} \begin{ltx}
@ -956,21 +965,21 @@ text\<open>
\end{ltx} \end{ltx}
For a real-world example testing for multiple classes, see For a real-world example testing for multiple classes, see
\path{ontologies/scholarly_paper/DOF-scholarly_paper.sty}): \<^file>\<open>../../../src/ontologies/scholarly_paper/DOF-scholarly_paper.sty\<close>:
We encourage this clear and machine-checkable enforcement of restrictions while, at the same We encourage this clear and machine-checkable enforcement of restrictions while, at the same
time, we also encourage to provide a package option to overwrite them. The latter allows time, we also encourage to provide a package option to overwrite them. The latter allows
inherited ontologies to overwrite these restrictions and, therefore, to provide also support inherited ontologies to overwrite these restrictions and, therefore, to provide also support
for additional document templates. For example, the ontology \<^boxed_theory_text>\<open>technical_report\<close> for additional document templates. For example, the ontology \<^boxed_theory_text>\<open>technical_report\<close>
extends the \<^boxed_theory_text>\<open>scholarly_paper\<close> ontology and its \LaTeX supports provides support extends the \<^boxed_theory_text>\<open>scholarly_paper\<close> ontology and its \<^LaTeX> supports provides support
for the \inlineltx|scrrept|-class which is not supported by the \LaTeX support for for the \inlineltx|scrrept|-class which is not supported by the \<^LaTeX> support for
\<^boxed_theory_text>\<open>scholarly_paper\<close>. \<^boxed_theory_text>\<open>scholarly_paper\<close>.
\<close> \<close>
subsubsection\<open>Outdated Version of \path{comment.sty}\<close> subsubsection\<open>Outdated Version of \<^path>\<open>comment.sty\<close>\<close>
text\<open> text\<open>
Isabelle's \LaTeX-setup relies on an ancient version of \path{comment.sty} that, moreover, Isabelle's \<^LaTeX>-setup relies on an ancient version of \<^path>\<open>comment.sty\<close> that, moreover,
is used in plain\TeX-mode. This is known to cause issues with some modern \LaTeX-classes is used in plain\<^TeX>-mode. This is known to cause issues with some modern \<^LaTeX>-classes
such as LPICS. Such a conflict might require the help of an Isabelle wizard. such as LPICS. Such a conflict might require the help of an Isabelle wizard.
\<close> \<close>

5
src/ontologies/scholarly_paper/scholarly_paper.thy
View File

@ -423,6 +423,8 @@ section\<open>Miscelleous\<close>
subsection\<open>Layout Trimming Commands\<close> subsection\<open>Layout Trimming Commands\<close>
setup\<open> DOF_lib.define_macro \<^binding>\<open>hs\<close> "\\hspace{" "}" (K(K())) \<close> setup\<open> DOF_lib.define_macro \<^binding>\<open>hs\<close> "\\hspace{" "}" (K(K())) \<close>
setup\<open> DOF_lib.define_macro \<^binding>\<open>vs\<close> "\\vspace{" "}" (K(K())) \<close> setup\<open> DOF_lib.define_macro \<^binding>\<open>vs\<close> "\\vspace{" "}" (K(K())) \<close>
setup\<open> DOF_lib.define_shortcut \<^binding>\<open>clearpage\<close> "\\clearpage{}" \<close>
subsection\<open>Common Abbreviations\<close> subsection\<open>Common Abbreviations\<close>
setup \<open> DOF_lib.define_shortcut \<^binding>\<open>eg\<close> "\\eg" setup \<open> DOF_lib.define_shortcut \<^binding>\<open>eg\<close> "\\eg"
@ -430,7 +432,8 @@ setup \<open> DOF_lib.define_shortcut \<^binding>\<open>eg\<close> "\\eg"
#> DOF_lib.define_shortcut \<^binding>\<open>ie\<close> "\\ie" #> DOF_lib.define_shortcut \<^binding>\<open>ie\<close> "\\ie"
#> DOF_lib.define_shortcut \<^binding>\<open>etc\<close> "\\etc"\<close> #> DOF_lib.define_shortcut \<^binding>\<open>etc\<close> "\\etc"\<close>
(* Latin: „id est“ meaning „that is to say“. *) (* Latin: „id est“ meaning „that is to say“. *)
(* this is an alternative style for macro definitions equivalent to setup ... setup ...*)
(* this is an alternative style for macro definitions equivalent to setup ... setup ...*)
end end