Skip to content

Commit

Permalink
More documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@io7m
io7m committed Sep 29, 2024
1 parent 9cf3ab8 commit b8efc09
Show file tree
Hide file tree
Showing 9 changed files with 280 additions and 9 deletions.
30 changes: 30 additions & 0 deletions com.io7m.laurel.documentation/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,36 @@
</configuration>
</execution>

<execution>
<id>unpack-sources-schema</id>
<phase>package</phase>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<configuration>
<includes>**/database.sql</includes>
<includeGroupIds>${project.groupId}</includeGroupIds>
<classifier>sources</classifier>
<failOnMissingClassifierArtifact>false</failOnMissingClassifierArtifact>
<outputDirectory>${project.build.directory}/documentation/</outputDirectory>
</configuration>
</execution>

<execution>
<id>unpack-sources-schema-epub</id>
<phase>package</phase>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<configuration>
<includes>**/database.sql</includes>
<includeGroupIds>${project.groupId}</includeGroupIds>
<classifier>sources</classifier>
<failOnMissingClassifierArtifact>false</failOnMissingClassifierArtifact>
<outputDirectory>${project.build.directory}/epub/</outputDirectory>
</configuration>
</execution>

<execution>
<id>make-classpath</id>
<phase>package</phase>
Expand Down
2 changes: 1 addition & 1 deletion ...io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-captions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
</Paragraph>
</Subsection>

<Subsection title="Format">
<Subsection title="Format" id="370548e2-5213-41c6-8976-13dc0d3e4356">
<Paragraph>
Captions must conform to the following format:
</Paragraph>
Expand Down
11 changes: 11 additions & 0 deletions ...7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-categories.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -253,4 +253,15 @@
</Paragraph>
</Subsection>

<Subsection title="Format" id="8996e713-1146-49ac-a5b3-1d426ff7628e">
<Paragraph>
Categories must conform to the following format:
</Paragraph>
<FormalItem title="Category Format">
<Verbatim><![CDATA[
category ::= [a-z0-9A-Z_-][a-z0-9A-Z_ \-']*
]]></Verbatim>
</FormalItem>
</Subsection>

</Section>
69 changes: 66 additions & 3 deletions ...o7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-filemodel.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,71 @@

<Section xmlns="urn:com.io7m.structural:8:0"
id="a3b1b8a8-bbe1-4ed1-905d-969ef333c92e"
xmlns:xi="http://www.w3.org/2001/XInclude"
title="File Model">
<Paragraph>
File model...
</Paragraph>

<Subsection title="Overview">
<Paragraph>
The applications stores the dataset in a structure known as the <Term type="term">file model</Term>.
</Paragraph>
</Subsection>

<Subsection title="Format">
<Subsection title="Overview">
<Paragraph>
The <Term type="term">file model</Term>'s underlying representation is an
<LinkExternal target="https://www.sqlite.org">SQLite</LinkExternal> database. The database contains
all of the
<Link target="405b6ebe-a489-4849-8b02-57129078ab7e">images</Link>,
<Link target="605e7b9d-a54f-4c3c-914c-c6978d2d50f7">captions</Link>,
<Link target="3d9f296a-0946-4bb3-81f1-c5185b23973e">categories</Link>,
<Link target="9e2689f2-e0b3-42bb-a3c4-a01741d1a0cd">metadata</Link>,
and the
<Link target="4c2388b3-da2f-46ba-b796-52028873ed4c">undo history</Link>.
</Paragraph>
</Subsection>
<Subsection title="Schema">
<Paragraph>
The database uses the following schema:
</Paragraph>
<FormalItem title="Schema">
<Verbatim><xi:include href="com/io7m/laurel/filemodel/internal/database.sql" parse="text"/></Verbatim>
</FormalItem>
<Paragraph>
The <Term type="expression">schema_version</Term> table's single row <Term type="term">MUST</Term>
contain <Term type="constant">com.io7m.laurel</Term> in the
<Term type="expression">version_application_id</Term> column.
</Paragraph>
<Paragraph>
Limitations in SQLite mean that it is, unfortunately, impractical to enforce invariants such as
<Link target="8996e713-1146-49ac-a5b3-1d426ff7628e">category</Link> and
<Link target="370548e2-5213-41c6-8976-13dc0d3e4356">caption</Link> formats at the database level.
</Paragraph>
</Subsection>
</Subsection>

<Subsection title="Undo" id="f9c3839f-9ec0-45e1-b5dd-dfb7a08b92af">
<Paragraph>
When an <Term type="term">undoable</Term> command is successfully executed on the file model, the
parameters of the original command, and the data that was modified, is stored in the
<Term type="table">undo</Term> table. When a command is <Term type="term">undone</Term>, that same
data is moved to the <Term type="table">redo</Term> table.
</Paragraph>
<Paragraph>
The data and parameters are serialized to
<LinkExternal target="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Properties.html">
Java Properties
</LinkExternal>
format, but the precise names and types of the keys is currently unspecified. This means that, although
applications other than <Term type="package">Laurel</Term> can open and manipulate datasets, they will currently
need to do some mild reverse engineering to manipulate the history.
</Paragraph>
</Subsection>

<Footnote id="0cf245a9-1562-4f6a-a22f-d5b20fd3aaec">
Tables are required to be <LinkExternal target="https://sqlite.org/stricttables.html">STRICT</LinkExternal>.
Flexible typing is a bug and not a feature, regardless of how many times the SQLite documentation extols the
virtues of being able to accidentally insert malformed data into database tables.
</Footnote>

</Section>
22 changes: 19 additions & 3 deletions com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-history.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,23 @@
<Section xmlns="urn:com.io7m.structural:8:0"
id="4c2388b3-da2f-46ba-b796-52028873ed4c"
title="History">
<Paragraph>
History...
</Paragraph>

<Subsection title="Overview">
<Paragraph>
The application stores the complete, persistent history of every change ever made to the dataset.
</Paragraph>
</Subsection>

<Subsection title="Implementation">
<Paragraph>
The undo and redo stacks are stored in the <Link target="f9c3839f-9ec0-45e1-b5dd-dfb7a08b92af">file model</Link>.
</Paragraph>
<Paragraph>
Each command that is executed on the file model is <Term type="term">invertible</Term>. That is, each command
knows how to perform an action, and how to revert that action. By storing the complete sequence of executed
commands, it is effectively possible to take a dataset and repeatedly undo operations until the dataset is back at
the blank starting state.
</Paragraph>
</Subsection>

</Section>
135 changes: 135 additions & 0 deletions ...io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-metadata.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
<?xml version="1.0" encoding="UTF-8" ?>

<Section xmlns="urn:com.io7m.structural:8:0"
id="9e2689f2-e0b3-42bb-a3c4-a01741d1a0cd"
title="Metadata">

<Subsection title="Overview">
<Paragraph>
Metadata in the application is a simple string key/value store. Keys are unique.
</Paragraph>
</Subsection>

<Subsection title="Dublin Core">
<Paragraph>
It is recommended that creators annotate datasets with the standard
<LinkExternal target="https://www.dublincore.org/specifications/dublin-core/dcmi-terms/">
Dublin Core
</LinkExternal>
metadata terms, summarized in the following table:
</Paragraph>
<FormalItem title="Recommended Metadata">
<Table type="genericTable">
<Columns>
<Column>Name</Column>
<Column>Description</Column>
</Columns>
<Row>
<Cell>
<Term type="constant">dc:title</Term>
</Cell>
<Cell>
The dataset title.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:creator</Term>
</Cell>
<Cell>
The dataset creator.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:subject</Term>
</Cell>
<Cell>
The dataset subject.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:description</Term>
</Cell>
<Cell>
A human-readable description of the dataset.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:publisher</Term>
</Cell>
<Cell>
A organization publishing the dataset.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:contributor</Term>
</Cell>
<Cell>
The contributors to the dataset.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:date</Term>
</Cell>
<Cell>
The dataset publication or creation date.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:type</Term>
</Cell>
<Cell>
The type (recommended: "dataset").
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:format</Term>
</Cell>
<Cell>
The format (recommended: "com.io7m.laurel").
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:identifier</Term>
</Cell>
<Cell>
The dataset identifier.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:source</Term>
</Cell>
<Cell>
The dataset source URI.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:language</Term>
</Cell>
<Cell>
The dataset language.
</Cell>
</Row>
<Row>
<Cell>
<Term type="constant">dc:rights</Term>
</Cell>
<Cell>
The dataset rights/license.
</Cell>
</Row>
</Table>
</FormalItem>
</Subsection>

</Section>
1 change: 1 addition & 0 deletions ....laurel.documentation/src/main/resources/com/io7m/laurel/documentation/implementation.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
<xi:include href="i-categories.xml"/>
<xi:include href="i-images.xml"/>
<xi:include href="i-history.xml"/>
<xi:include href="i-metadata.xml"/>
<xi:include href="i-filemodel.xml"/>
<xi:include href="i-validation.xml"/>
</Section>
17 changes: 16 additions & 1 deletion com.io7m.laurel.filemodel/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@
<includeProjectDependencies>false</includeProjectDependencies>
<arguments>
<argument>${project.basedir}/src/main/resources/com/io7m/laurel/filemodel/internal/database.xml</argument>
<argument>${project.build.directory}/database.sql</argument>
<argument>${project.build.directory}/generated-resources/jooq/com/io7m/laurel/filemodel/internal/database.sql</argument>
<argument>ROLES</argument>
<argument>GRANTS</argument>
<argument>FUNCTIONS</argument>
Expand Down Expand Up @@ -197,6 +197,21 @@
</sources>
</configuration>
</execution>
<execution>
<id>add-jooq-resources</id>
<phase>generate-sources</phase>
<goals>
<goal>add-resource</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>${project.build.directory}/generated-resources/jooq</directory>
<filtering>false</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
Expand Down
2 changes: 1 addition & 1 deletion com.io7m.laurel.filemodel/src/main/jooq/configuration.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
- ? matches a single character in a directory / file name -->
<property>
<key>scripts</key>
<value>target/database.sql</value>
<value>target/generated-resources/jooq/com/io7m/laurel/filemodel/internal/database.sql</value>
</property>

<!-- The sort order of the scripts within a directory, where:
Expand Down

0 comments on commit b8efc09

Please sign in to comment.