From dd3e14ec4dd2386cc8af61157975118acb4d6ee2 Mon Sep 17 00:00:00 2001 From: Benjamin Paassen Date: Sun, 4 Jan 2015 12:31:36 +0100 Subject: improved documentation. --- src/core/model/Domain.hpp | 229 +++++++++++++++++++++++++++++++++------------- 1 file changed, 166 insertions(+), 63 deletions(-) (limited to 'src/core/model/Domain.hpp') diff --git a/src/core/model/Domain.hpp b/src/core/model/Domain.hpp index cd74a19..7e4e9f7 100644 --- a/src/core/model/Domain.hpp +++ b/src/core/model/Domain.hpp @@ -30,24 +30,65 @@ * terms "StructuredClass" and "FieldDescriptor". * On the top level you would start with a StructuredClass, say "book", which * in turn might contain two FieldDescriptors, one for the meta data of ones - * book and one for the actual structure. Consider the following (simplified) - * XML notation (TODO: Use a non-simplified notation as soon as the format is - * clear.) - * - * - * - * - * Here we would reference the possible child classes, e.g. section, - * paragraph, etc. - * - * - * - * - * Here we would reference the possible child classes for meta, - * information, e.g. authors, date, version, etc. - * - * - * + * book and one for the actual structure. Consider the following XML: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * * * Note that we define one field as the TREE (meaning the main or default * document structure) and one mearly as SUBTREE, relating to supporting @@ -58,11 +99,19 @@ * TREE field and at least one permitted child must exist, either primitive or * as another StructuredClass. * - * The translation to context free grammars is roughly as follows: + * The translation to context free grammars is as follows: * - * BOOK := book BOOK_STRUCTURE BOOK_META - * BOOK_STRUCTURE := SECTION BOOK_STRUCTURE | PARAGRAPH BOOK_STRUCTURE | epsilon - * BOOK_META := AUTHOR BOOK_META | DATE BOOK_META + * BOOK := BOOK_TREE + * BOOK_TREE := CHAPTER BOOK_TREE | PARAGRAPH BOOK_TREE | epsilon + * CHAPTER := CHAPTER_TREE + * CHAPTER_TREE := SECTION CHAPTER_TREE | PARAGRAPH CHAPTER_TREE | epsilon + * SECTION :=
SECTION_TREE
+ * SECTION_TREE := SUBSECTION SECTION_TREE | PARAGRAPH SECTION_TREE | + * epsilon + * SUBSECTION := SUBSECTION_TREE + * SUBSECTION_TREE := PARAGRAPH SUBSECTION_TREE | epsilon + * PARAGRAPH := PARAGRAPH_CONTENT + * PARAGRAPH_CONTENT := string * * Note that this translation recurs to further nonterminals like SECTION but * necessarily produces one "book" terminal. Also note that, in principle, @@ -70,11 +119,72 @@ * the proper StructuredClass. This can be regulated by the "cardinality" * property of a StructuredClass. * + * It is possible to add further fields, like we would in the "headings" domain + * to add titles to our structure. + * + * + * + * + * + * + * + * + * + * + * + * ... + * + * + * + * + * + * + * + * This would change the context free grammar as follows: + * + * BOOK := HEADING BOOK_TREE + * HEADING := PARAGRAPH + * * AnnotationClasses on the other hand do not specify a context free grammar. * They merely specify what kinds of Annotations are allowed within this domain * and which fields or attributes they have. Note that Annotations are allowed * to define structured children that manifest e.g. meta information of that - * Annotation. + * Annotation. An example for that would be the "comment" domain: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * Here we have comment annotations, which have a reply tree as sub structure. * * @author Benjamin Paaßen (bpaassen@techfak.uni-bielefeld.de) */ @@ -105,13 +215,17 @@ class Domain; * Hierarchy. * * As an example consider the "paragraph" StructuredClass, which might allow - * the actual text content. Here is the according simplified XML (TODO: replace - * with a non-simplified version as soon as the XML syntax is clear.) + * the actual text content. Here is the according XML: * - * - * - * + * + * + * + * + * + * + * + * + * * * Accordingly the primitiveType field of a FieldDescriptor may only be * defined if the type is set to "PRIMITIVE". If the type is something else @@ -286,36 +400,28 @@ typedef RangeSet Cardinality; * consult the Header documentation above. * * Note that a StructuredClass may "invade" an existing Domain description by - * defining itself as a viable child in one existing field. Consider a "section" - * StructuredClass (continuing the example in the header documentation): - * - * - * - * - * paragraph - * - * - * - * - * Of course in most cases we do not only want to allow paragraphs inside - * sections, but also (for example) lists. How would one add that - * without manipulating the existing domain or having to define an entirely - * new domain in which section allows for lists? - * - * Our solution to this problem is the parent mechanism. The simplified XML - * (TODO: Use non-simplified version as soon as possible) for the "list" - * StructuredClass would look like this: - * - * - * - * - * item - * - * - * - * section.structure - * - * + * defining itself as a viable child in one existing field. Consider the + * example of the "heading" domain from the header documentation again: + * + * + * + * + * + * + * + * + * + * + * + * ... + * + * + * + * + * + * + * + * The "parent" construct allows to "invade" another domain. * * This does indeed interfere with an existing domain and one must carefully * craft such parent references to not create undesired side effects. However @@ -404,8 +510,7 @@ public: Handle attributesDescriptor = nullptr, // TODO: What would be a wise default value for isa? Handle isa = nullptr, - bool transparent = false, - bool root = false) + bool transparent = false, bool root = false) : Descriptor(mgr, std::move(name), domain, attributesDescriptor), cardinality(cardinality), isa(acquire(isa)), @@ -497,9 +602,7 @@ extern const Rtti Descriptor; extern const Rtti StructuredClass; extern const Rtti AnnotationClass; extern const Rtti Domain; - } - } #endif /* _OUSIA_MODEL_DOMAIN_HPP_ */ -- cgit v1.2.3