issue-8 externalize examples

examples/Makefile

@@ -0,0 +1,35 @@
+RDF =  $(wildcard rdf/*.rdf)
+TTL =  $(patsubst rdf/%,ttl/%,$(RDF:.rdf=.ttl))
+PUML = $(wildcard puml/*.puml)
+PNG =  $(patsubst puml/%,png/%,$(PUML:.puml=.png))
+
+none:
+	@echo make rdf, ttl, png, iirds-terms
+
+rdf::
+	perl collect-examples.pl
+
+ttl: $(TTL)
+
+ttl/%.ttl: rdf/%.rdf
+	owl.bat write --input=rdfxml --useCommaByDefault $^ $@
+
+png: $(PNG)
+
+png/%.png: ttl/%.ttl puml/%.puml
+	cat $^ > temp.ttl
+	perl -S rdfpuml.pl temp.ttl
+	plantuml temp.puml
+	rm temp.puml
+	mv temp.png $@
+
+iirds-terms::
+	cat ttl/*|riot.bat --syntax ttl --out ntriples|grep rdf-syntax-ns#type   |cut -f3 -d" "|perl -ne 's{<http://iirds.tekom.de/iirds#(.*)>}{iirds:$$1} and print'|sort|uniq>iirds-class-eg.txt
+	cat ttl/*|riot.bat --syntax ttl --out ntriples|                           cut -f2 -d" "|perl -ne 's{<http://iirds.tekom.de/iirds#(.*)>}{iirds:$$1} and print'|sort|uniq>iirds-prop-eg.txt
+	cat ttl/*|riot.bat --syntax ttl --out ntriples|grep -v rdf-syntax-ns#type|cut -f3 -d" "|perl -ne 's{<http://iirds.tekom.de/iirds#(.*)>}{iirds:$$1} and print'|sort|uniq>iirds-obj-eg.txt  
+	grep ^iirds ../../iirds-models/iirds-core.ttl |grep rdfs:Class                    |cut -f1 -d" "|sort>iirds-class-def.txt
+	grep ^iirds ../../iirds-models/iirds-core.ttl |grep rdf:Property                  |cut -f1 -d" "|sort>iirds-prop-def.txt
+	grep ^iirds ../../iirds-models/iirds-core.ttl |grep -vE "rdfs:Class|rdf:Property" |cut -f1 -d" "|sort>iirds-obj-def.txt
+	cat iirds-class-eg.txt  iirds-prop-eg.txt  iirds-obj-eg.txt |sort|uniq>iirds-term-eg.txt
+	cat iirds-class-def.txt iirds-prop-def.txt iirds-obj-def.txt|sort|uniq>iirds-term-def.txt
+	comm -3 iirds-term-def.txt iirds-term-eg.txt>iirds-term-missing.txt

examples/README.md

@@ -0,0 +1,37 @@
+# iiRDS Examples
+
+These are all examples included in the iiRDS spec (version [1.2 of 20231110](https://www.iirds.org/fileadmin/iiRDS_specification/20231110-1.2-release/index.html)).
+
+They are extracted with the script [collect-examples.pl](collect-examples.pl):
+- Uses all files `sections/*/*.md` in order as listed in the main [README.md](../README.md)
+  - The only files missing from that outline are `structure/syntax.md` ([#29](https://github.com/iirds-consortium/specification/issues/29))
+    and `releasenotes/releasenotes_*.md`
+- Calculates a numbering that corresponds to the spec, eg
+  - Example 36 is at [#example-content-lifecylce-status-with-party-information](https://www.iirds.org/fileadmin/iiRDS_specification/20231110-1.2-release/index.html#example-content-lifecylce-status-with-party-information)
+  - Extracted as file `example-36-Content-lifecylce-status-with-party-information`.
+  - In a couple of cases the example consists of 2 or 3 parts, added as a suffix:
+    - `example-16-Nesting-an-iiRDS-package-1, example-16-Nesting-an-iiRDS-package-2`
+    - `example-26-External-product-ontology-1`
+  - Punctuation is removed from the end of the example title
+- Adds `<rdf:RDF>` if missing, including all namespaces used in examples ([#29](https://github.com/iirds-consortium/specification/issues/29))
+- Unescapes HTML entities `&lt; &gt; &amp;`
+
+The following folders are present (see [Makefile](Makefile) for details):
+- rdf: RDF/XML extracted from the spec
+- rdf-fixed: a few of the examples have minor defects, which are fixed here.
+  TODO: extract a patch and automate file fixing.
+- ttl: converted to Turtle, which is much easier to understand than RDF/XML
+- jsonld (future): converted to JSON-LD, which is the newest iiRDS serialization
+- puml: `rdfpuml` instructions to make a diagram for a few of the examples.
+  These files can be empty, which means that a diagram is desired, but no extra instructions are needed.
+- png: generated diagrams
+
+
+## iiRDS Term Coverage in Examples
+
+There are also some files that analyze terms defined in the `iirds-core` ontology vs terms illustrated in examples 
+- classes: `iirds-class-def.txt, iirds-class-eg.txt`
+- properties: `iirds-prop-def.txt, iirds-prop-eg.txt`
+- objects (individuals): `iirds-obj-def.txt, iirds-obj-eg.txt`
+- all terms: `iirds-term-def.txt, iirds-term-eg.txt`
+- terms defined in the ontology but not illustrated in examples: `iirds-term-missing.txt`

examples/collect-examples.pl

@@ -0,0 +1,109 @@
+#!perl -w
+
+our $IN = ".."; # /iirds-specification
+our $OUT = "rdf";
+our @FILES = # list of files in order, from README.md
+  qw(
+      sections/introduction/introduction.md
+      sections/introduction/contributors.md
+      sections/introduction/scope.md
+      sections/introduction/termsanddefinitions.md
+      sections/container/package.md
+      sections/container/container.md
+      sections/container/zippackage.md
+      sections/container/nestedpackages.md
+      sections/structure/rdfsschemaandiris.md
+      sections/structure/rdfsinfounits_chunks.md
+      sections/structure/rdfsinfounitidentifier.md
+      sections/structure/rdfsinfoobject.md
+      sections/structure/rdfscontentreference.md
+      sections/structure/rdfsmediafiles.md
+      sections/structure/rdfsnestedpackages.md
+      sections/structure/rdfsinfounitrelations.md
+      sections/structure/rdfsinfotypes.md
+      sections/structure/rfdsinfosubjects.md
+      sections/structure/rdfsdocmetadata.md
+      sections/structure/rdfsproductcomponent.md
+      sections/structure/rdfsadministrative.md
+      sections/structure/rdfsnavigation.md
+      sections/structure/rdfsclassconstraints.md
+      sections/structure/rdfsstandardextensions.md
+      sections/structure/rdfsdomainextensions.md
+      sections/structure/rdfsproprietaryextensions.md
+      sections/content/unrestricted_vs_a.md
+      sections/content/selfcontained-a.md
+      sections/levels/mediaformats.md
+      sections/levels/html5format-overview.md
+      sections/levels/html5format-format.md
+      sections/levels/html5format-conformance.md
+      sections/levels/html5format-globalattributes.md
+      sections/levels/html5format-elements.md
+      sections/levels/html5tagging.md
+      sections/levels/html5format-styling.md
+      sections/structure/rdfsreference.md
+      sections/structure/rdfsdiagrams.md
+      sections/structure/references.md
+   );
+our $n = "01"; # counter
+our $nn = ""; # subsidiary counter
+our ($name, $name1);
+our $example;
+for my $file (@FILES) {
+  open STDIN, "$IN/$file" or die "can't open $IN/$file: $!\n";
+  while (<>) {
+    m{<(pre|aside) +class="example" title="(.*)">} and do {
+      $name = $2;
+      $example = $1 eq "pre" && ""; # if <pre> then start collecting; <aside> only sets name, but doesn't start the example text
+      $name =~ s{[ .]$}{};
+      $name =~ s{ }{-}g;
+      $name = $name1 = "$OUT/example-$n-$name";
+      $n++; $nn = undef;
+      next;
+    };
+    m{<pre *>\s*$} and do {
+      if ($name) {
+        $example = ""; # start collecting
+        if ($nn) {$name = "$name1-$nn"; $nn++}
+      };
+      next;
+    };
+    m{<pre class="example">} and do {
+      # one is <img> and the other is empty <rdf:RDF> element
+      $name = $example = undef;
+      $n++;
+    };
+    m{</aside>} and do {
+      if ($name && $example && $example =~ m{<}) {
+        die "got </aside>, discarding $name\n$example\n"
+      };
+      next
+    };
+    m{</pre>} and do {
+      if ($name && $example && $example =~ m{<}) { # && $example !~ m{ *<img} is already discarded
+        print "$name\n";
+        $example =~ m{<rdf:RDF} or $example = <<EOF;
+<?xml version="1.0" encoding="UTF-8"?>
+<rdf:RDF
+  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
+  xmlns:owl="http://www.w3.org/2002/07/owl#"
+  xmlns:dcterms="http://purl.org/dc/terms/"
+  xmlns:vcard="http://www.w3.org/2006/vcard/ns#"
+  xmlns:iirds="http://iirds.tekom.de/iirds#">
+$example
+</rdf:RDF>
+EOF
+        open OUT, ">$name.rdf" or die "can't create $name: $!\n";
+        print OUT $example;
+        close(OUT);
+      };
+      $nn //= "1";
+      $example = undef;
+    };
+    next unless defined $example; # are we collecting example text?
+    s{&lt;}{<}g; # HTML unescape
+    s{&gt;}{>}g;
+    s{&amp;}{&}g;
+    $example .= $_;
+  }
+}

examples/iirds-class-def.txt

@@ -0,0 +1,67 @@
+iirds:Action
+iirds:AdministrativeMetadata
+iirds:AfterUse
+iirds:ClassificationDomain
+iirds:ClassificationType
+iirds:Collection
+iirds:Component
+iirds:Concept
+iirds:Conformity
+iirds:ContentLifeCycleStatus
+iirds:ContentLifeCycleStatusValue
+iirds:DesignAndRealization
+iirds:DirectoryNode
+iirds:DirectoryNodeType
+iirds:Document
+iirds:DocumentType
+iirds:DocumentationMetadata
+iirds:DownTime
+iirds:Event
+iirds:ExternalClassification
+iirds:Form
+iirds:Formality
+iirds:Fragment
+iirds:FragmentSelector
+iirds:FunctionalMetadata
+iirds:Functionality
+iirds:Identity
+iirds:IdentityDomain
+iirds:IdentityType
+iirds:InformationObject
+iirds:InformationSubject
+iirds:InformationType
+iirds:InformationUnit
+iirds:Learning
+iirds:MaintenanceInterval
+iirds:Package
+iirds:Party
+iirds:PartyRole
+iirds:PlanningTime
+iirds:Process
+iirds:ProductFeature
+iirds:ProductFunction
+iirds:ProductLifeCyclePhase
+iirds:ProductMetadata
+iirds:ProductProperty
+iirds:ProductVariant
+iirds:PuttingToUse
+iirds:Qualification
+iirds:RangeSelector
+iirds:Reference
+iirds:Rendition
+iirds:Role
+iirds:Safety
+iirds:Selector
+iirds:SkillLevel
+iirds:Supply
+iirds:Task
+iirds:TechnicalData
+iirds:TechnicalOverview
+iirds:Topic
+iirds:TopicType
+iirds:Troubleshooting
+iirds:Use
+iirds:WarningMessage
+iirds:WorkingTime
+iirds:iirdsDomainEntity
+iirds:nil

examples/iirds-class-eg.txt

@@ -0,0 +1,20 @@
+iirds:ClassificationDomain
+iirds:Component
+iirds:ContentLifeCycleStatus
+iirds:DirectoryNode
+iirds:Document
+iirds:ExternalClassification
+iirds:Fragment
+iirds:FragmentSelector
+iirds:Identity
+iirds:IdentityDomain
+iirds:InformationObject
+iirds:Package
+iirds:Party
+iirds:ProductFunction
+iirds:ProductProperty
+iirds:ProductVariant
+iirds:RangeSelector
+iirds:Rendition
+iirds:Role
+iirds:Topic

examples/iirds-obj-def.txt

@@ -0,0 +1,118 @@
+iirds:Acquisition
+iirds:AdministratorGuide
+iirds:ApplicableStandards
+iirds:Approved
+iirds:ArticleCode
+iirds:AssemblyInstructions
+iirds:Author
+iirds:BillOfMaterials
+iirds:CDD
+iirds:CEDeclarationOfConformity
+iirds:Caution
+iirds:Certificate
+iirds:Configuration
+iirds:ContactInformation
+iirds:ContractualDocument
+iirds:Contributor
+iirds:Creator
+iirds:Customer
+iirds:Danger
+iirds:DeclarationOfConformity
+iirds:Decommissioning
+iirds:Deleted
+iirds:Design
+iirds:Development
+iirds:Diagnostics
+iirds:Disposal
+iirds:EclassCodedName
+iirds:EclassIRDI
+iirds:ElectronicIdentificationPlate
+iirds:EmergencyOperation
+iirds:EuropeanArticleNumber
+iirds:Fault
+iirds:ForeseeableMisuse
+iirds:GenericAction
+iirds:GenericAfterUse
+iirds:GenericCollection
+iirds:GenericConcept
+iirds:GenericConformity
+iirds:GenericDesignAndRealization
+iirds:GenericDownTime
+iirds:GenericEvent
+iirds:GenericForm
+iirds:GenericFormality
+iirds:GenericFunctionality
+iirds:GenericLearning
+iirds:GenericMaintenanceInterval
+iirds:GenericPlanningTime
+iirds:GenericProcess
+iirds:GenericProductFeature
+iirds:GenericProductFunction
+iirds:GenericProductProperty
+iirds:GenericPuttingToUse
+iirds:GenericReference
+iirds:GenericRole
+iirds:GenericSafety
+iirds:GenericSkillLevel
+iirds:GenericSupply
+iirds:GenericTask
+iirds:GenericTechnicalData
+iirds:GenericTechnicalOverview
+iirds:GenericTroubleshooting
+iirds:GenericUse
+iirds:GenericWarningMessage
+iirds:GenericWorkingTime
+iirds:GlobalTradeItemNumber
+iirds:IdentificationDocument
+iirds:InPreparation
+iirds:InReview
+iirds:Index
+iirds:Inspector
+iirds:Installation
+iirds:InstallationInstructions
+iirds:IntendedUse
+iirds:LegalInformation
+iirds:LicenceTerm
+iirds:ListOfFigures
+iirds:ListOfListings
+iirds:ListOfTables
+iirds:Maintenance
+iirds:MaintenanceInstructions
+iirds:Manufacturer
+iirds:ManufacturerInformation
+iirds:Notice
+iirds:ObjectInstanceURI
+iirds:OperatingElement
+iirds:OperatingInstructions
+iirds:Operation
+iirds:OrderCode
+iirds:PartsCatalog
+iirds:PerformedBy
+iirds:Plan
+iirds:ProductIdentification
+iirds:ProductName
+iirds:ProductType
+iirds:Production
+iirds:QuickGuide
+iirds:Released
+iirds:Repair
+iirds:RepairInstructions
+iirds:RequirementsAnalysis
+iirds:RestrictionOnUse
+iirds:Reviewed
+iirds:RiskAssessment
+iirds:SafetyInstruction
+iirds:SafetyInstructions
+iirds:SalesCatalog
+iirds:ScopeOfDelivery
+iirds:SerialNumber
+iirds:Specification
+iirds:Supplier
+iirds:Symbol
+iirds:TableOfContents
+iirds:TechnicalDrawingDiagram
+iirds:TechnicalReport
+iirds:TransportInstructions
+iirds:Warning
+iirds:WarrantyConditions
+iirds:Withdrawn