Makefile updates for 1.2-DRAFT

Makefile

@@ -17,7 +17,7 @@ all: dependencies release
 dependencies: node_modules/.bin/rochtml
 	scripts/schema-context.py --version
 	node_modules/.bin/rochtml --help
-	pip --exists-action=s install 'panflute<2'
+	pip --exists-action=s install 'panflute==2.1.3'
 	pandoc --version
 	xelatex --version
 
@@ -89,32 +89,41 @@ release/ro-crate-${TAG}.md: dependencies release/ docs/_specification/${RELEASE}
 	pandoc --from=markdown+gfm_auto_identifiers --to=markdown+gfm_auto_identifiers \
 	   docs/_specification/${RELEASE}/.metadata.md \
 	   `grep ^nav_order: docs/_specification/${RELEASE}/*.md | sort -n -k 2 | grep -v index.md| grep -v about.md | sed s/:.*//` \
-	   docs/_specification/${RELEASE}/appendix/*.md docs/_includes/references.liquid docs/_specification/${RELEASE}/.references.md |\
-	   grep -v '{%' > release/ro-crate-${TAG}.md
+	   `grep ^nav_order: docs/_specification/${RELEASE}/appendix/*.md | sort -n -k 2 | sed s/:.*//` \
+	   docs/_includes/references.liquid docs/_specification/${RELEASE}/.references.md \
+	   > release/ro-crate-${TAG}.md
 	# Our own rendering of Note/Warning/Tip
-	sed -i -E 's/\{: ?\.note ?\} \\>/**Note**:/g' release/ro-crate-${TAG}.md
-	sed -i -E 's/\{: ?\.warning ?\} \\>/**Warning**:/g' release/ro-crate-${TAG}.md
-	sed -i -E 's/\{: ?\.tip ?\} \\>/**Tip**:/g' release/ro-crate-${TAG}.md
+	sed -i -E 's/\{% include callout.html //g' release/ro-crate-${TAG}.md
+	sed -i -E 's/\" %}//g' release/ro-crate-${TAG}.md
+	sed -i -E 's/type=\"note\" content=\"/**Note**: /g' release/ro-crate-${TAG}.md
+	sed -i -E 's/type=\"warning\" content=\"/**Warning** :/g' release/ro-crate-${TAG}.md
+	sed -i -E 's/type=\"tip\" content=\"/**Tip**: /g' release/ro-crate-${TAG}.md
+	sed -i -E 's/type=\"important\" content=\"/**Important**: /g' release/ro-crate-${TAG}.md
+	# remove any remaining lines beginning with {%
+	sed -i -E 's/\{%.*//g' release/ro-crate-${TAG}.md
 	# Skip intermediate table-of-contents
 	sed -i -E 's/1..*\{:toc\}//g' release/ro-crate-${TAG}.md
 	sed -i -E 's/## Table of contents//g' release/ro-crate-${TAG}.md
 	sed -i -E 's/\{:[^}]*\}//g' release/ro-crate-${TAG}.md
 	# Fix internal links to work in single-page
-	sed -i -E 's,]\(([^:)]*/)*([^:)]*)\.md\),](#\2),g' release/ro-crate-${TAG}.md
-	sed -i -E 's,]\([^):]*\.md#([^)]*)\),](#\1),g' release/ro-crate-${TAG}.md
-
+	# first change links to website pages outside the spec, e.g. ../../tools -> https://www.researchobject.org/ro-crate/tools
+	sed -r -i -E 's,]\(\.\./\.\./([^:)]*)\),](https://www.researchobject.org/ro-crate/\1),g' release/ro-crate-${TAG}.md
+	sed -r -i -E 's,]\((\.\./)?([^:)]*\.(json|html))\),](https://www.researchobject.org/ro-crate/specification/${RELEASE}/\2),g' release/ro-crate-${TAG}.md
+	# change links without a #, e.g. appendix/jsonld to #jsonld
+	sed -r -i -E 's,]\(([^:)]*/)*([^:)]*)(\.md)?\),](#\2),g' release/ro-crate-${TAG}.md
+	# change links with a #, e.g. contextual-entities#people to #people
+	sed -r -i -E 's,]\([^):]*(\.md)?#([^)]*)\),](#\2),g' release/ro-crate-${TAG}.md
 
 release/ro-crate-${TAG}.html: dependencies release/ release/ro-crate-${TAG}.md
 	egrep -v '^{:(\.no_)?toc}' release/ro-crate-${TAG}.md | \
 	pandoc --standalone --number-sections --toc --section-divs \
-	  --filter scripts/pandoc-admonition.py \
 	  --metadata pagetitle="RO-Crate Metadata Specification ${RELEASE}" \
 	  --from=markdown+gfm_auto_identifiers -o release/ro-crate-${TAG}.html
 
 release/ro-crate-${TAG}.pdf: dependencies release/ release/ro-crate-${TAG}.md
 	egrep -v '^{:(\.no_)?toc}' release/ro-crate-${TAG}.md | \
 	pandoc --pdf-engine xelatex --variable=hyperrefoptions:colorlinks=true,allcolors=blue \
-	  --variable papersize=a4 --filter scripts/pandoc-admonition.py \
+	  --variable papersize=a4 \
 	  --number-sections --toc  --metadata pagetitle="RO-Crate Metadata Specification ${RELEASE}" \
 	  --from=markdown+gfm_auto_identifiers -o release/ro-crate-${TAG}.pdf
 

docs/_specification/1.2-DRAFT/appendix/changelog.md

@@ -26,33 +26,33 @@ excerpt: List of changes in releases of this specifications
 -->
 
 
-# APPENDIX: Changelog
+# APPENDIX: Changelog {#changelog}
 
 * RO-Crate 1.2.0
   * Clarified that the [RO-Crate Metadata Descriptor MUST have `@id` of `ro-crate-metadata.json`](../root-data-entity#ro-crate-metadata-descriptor) by removing conflicting statements elsewhere in the specification [#365](https://github.com/ResearchObject/ro-crate/pull/365)
   * Updated the Bioschemas namespace for properties from `https://bioschemas.org/ComputationalWorkflow#` to `https://bioschemas.org/properties/`. This change affects only the `input` and `output` properties in the [JSON-LD context](../ro-crate-metadata.json).
-  * **Change**: Replaced [name-based algorithm for finding root](../root-data-entity.html#finding-the-root-data-entity)  [#198](https://github.com/ResearchObject/ro-crate/issues/198) [#365](https://github.com/ResearchObject/ro-crate/pull/365)
-  * Updated [algorithm to always use string filter to find root](../appendix/relative-uris.html#finding-ro-crate-root-in-rdf-triple-stores)  [#189](https://github.com/ResearchObject/ro-crate/issues/189)
- (see [algorithm](../root-data-entity.html#finding-the-root-data-entity))
-  * **Change**: [Files on the web](../data-entities.html#embedded-data-entities-that-are-also-on-the-web) should now use `contentUrl` for direct download [#259](https://github.com/ResearchObject/ro-crate/issues/259)  
+  * **Change**: Replaced [name-based algorithm for finding root](../root-data-entity#finding-the-root-data-entity)  [#198](https://github.com/ResearchObject/ro-crate/issues/198) [#365](https://github.com/ResearchObject/ro-crate/pull/365)
+  * Updated [algorithm to always use string filter to find root](../appendix/relative-uris#finding-ro-crate-root-in-rdf-triple-stores)  [#189](https://github.com/ResearchObject/ro-crate/issues/189)
+ (see [algorithm](../root-data-entity#finding-the-root-data-entity))
+  * **Change**: [Files on the web](../data-entities#embedded-data-entities-that-are-also-on-the-web) should now use `contentUrl` for direct download [#259](https://github.com/ResearchObject/ro-crate/issues/259)  
   * [Clarify entity terminology](../contextual-entities#contextual-vs-data-entities)  [#204](https://github.com/ResearchObject/ro-crate/issues/204)
   * Update [JSON-LD context](../ro-crate-metadata.json) to [schema.org 22.0](https://github.com/schemaorg/schemaorg/tree/main/data/releases/22.0/). Note that upstream adds >230 terms, and removed terms `AuthenticContent` `MissingContext`, `constrainingProperty` (now `constraintProperty`), `measuredValue`, `observedNode` . [#263](https://github.com/ResearchObject/ro-crate/issues/263) [#274](https://github.com/ResearchObject/ro-crate/issues/274)
   * Remove custom mapping of `funding` for Bioschemas (now officially <http://schema.org/funding>)
   * Updated for [ComputationalWorkflow 1.0 profile](../workflows#complying-with-bioschemas-computational-workflow-profile)   [#185](https://github.com/ResearchObject/ro-crate/issues/185)
-  * Clarified [Directories on the web format](../data-entities.html#directories-on-the-web-dataset-distributions) is a media type, not extension [#205](https://github.com/ResearchObject/ro-crate/issues/235)  
-  * **New**: Extended [introduction](../introduction.html) with a running example [#227](https://github.com/ResearchObject/ro-crate/issues/227) [#215](https://github.com/ResearchObject/ro-crate/issues/215) [#219](https://github.com/ResearchObject/ro-crate/issues/219) -- see also [RO-Crate tutorials](https://www.researchobject.org/ro-crate/tutorials.html).
+  * Clarified [Directories on the web format](../data-entities#directories-on-the-web-dataset-distributions) is a media type, not extension [#205](https://github.com/ResearchObject/ro-crate/issues/235)  
+  * **New**: Extended [introduction](../introduction) with a running example [#227](https://github.com/ResearchObject/ro-crate/issues/227) [#215](https://github.com/ResearchObject/ro-crate/issues/215) [#219](https://github.com/ResearchObject/ro-crate/issues/219) -- see also [RO-Crate tutorials](https://www.researchobject.org/ro-crate/tutorials.html).
   * **New**:  Added section [Profiles](../profiles) and the concept _Profile Crate_  [#250](https://github.com/ResearchObject/ro-crate/issues/250) [#251](https://github.com/ResearchObject/ro-crate/issues/251) [#255](https://github.com/ResearchObject/ro-crate/issues/255) [#256](https://github.com/ResearchObject/ro-crate/issues/256)
-  * Define [terms for Profiles](../metadata.html#additional-metadata-standards)  [#248](https://github.com/ResearchObject/ro-crate/issues/248)
-  * Added subsection for [grouping extensions in a profile](../appendix/jsonld.html#grouping-extensions-as-an-ro-crate-profile)   [#233](https://github.com/ResearchObject/ro-crate/issues/233) [#233](https://github.com/ResearchObject/ro-crate/issues/252)
-  * [Allow more types on root](../root-data-entity.html#ro-crate-metadata-descriptor)  [#182](https://github.com/ResearchObject/ro-crate/issues/182) [#223](https://github.com/ResearchObject/ro-crate/issues/223)
-  * Added subsection on [root data entity identifier](../root-data-entity.html#root-data-entity-identifier)   [#183](https://github.com/ResearchObject/ro-crate/issues/183)
+  * Define [terms for Profiles](../metadata#additional-metadata-standards)  [#248](https://github.com/ResearchObject/ro-crate/issues/248)
+  * Added subsection for [grouping extensions in a profile](../appendix/jsonld#grouping-extensions-as-an-ro-crate-profile)   [#233](https://github.com/ResearchObject/ro-crate/issues/233) [#233](https://github.com/ResearchObject/ro-crate/issues/252)
+  * [Allow more types on root](../root-data-entity#ro-crate-metadata-descriptor)  [#182](https://github.com/ResearchObject/ro-crate/issues/182) [#223](https://github.com/ResearchObject/ro-crate/issues/223)
+  * Added subsection on [root data entity identifier](../root-data-entity#root-data-entity-identifier)   [#183](https://github.com/ResearchObject/ro-crate/issues/183)
   * **New**: Introduces distinction of [Attached/Detached RO-Crate](../structure) [#248](https://github.com/ResearchObject/ro-crate/issues/248) [#189](https://github.com/ResearchObject/ro-crate/issues/189) [#183](https://github.com/ResearchObject/ro-crate/issues/183)
   * Included Attached/Detached RO-Crate [in terminology](../terminology)  [#248](https://github.com/ResearchObject/ro-crate/issues/248)
   * Rephrased description of [payload files](../structure#payload-files-and-directories-attached-ro-crates)   [#183](https://github.com/ResearchObject/ro-crate/issues/183)  [#189](https://github.com/ResearchObject/ro-crate/issues/189)
   * Describes [ro-crate-preview.html as entity](../structure#ro-crate-website-ro-crate-previewhtml-and-ro-crate-preview_files)  [#106](https://github.com/ResearchObject/ro-crate/issues/106) [#210](https://github.com/ResearchObject/ro-crate/issues/210)
   * Added usage [of DefinedTerm; rdfs:label and comment optional; replaced example](jsonld#adding-new-or-ad-hoc-vocabulary-terms)  [#232](https://github.com/ResearchObject/ro-crate/issues/232) [#208](https://github.com/ResearchObject/ro-crate/issues/208) [#106](https://github.com/ResearchObject/ro-crate/issues/106)
-  * Added section on  [converting Attached/Detached RO-Crates](../appendix/relative-uris.html#converting-from-attached-to-detached-ro-crate)  [#189](https://github.com/ResearchObject/ro-crate/issues/189)
-  * Added [Common principles for RO-Crate entities](../metadata.html#common-principles-for-ro-crate-entities) [#225](https://github.com/ResearchObject/ro-crate/issues/225) [#260](https://github.com/ResearchObject/ro-crate/issues/260) 
+  * Added section on  [converting Attached/Detached RO-Crates](../appendix/relative-uris#converting-from-attached-to-detached-ro-crate)  [#189](https://github.com/ResearchObject/ro-crate/issues/189)
+  * Added [Common principles for RO-Crate entities](../metadata#common-principles-for-ro-crate-entities) [#225](https://github.com/ResearchObject/ro-crate/issues/225) [#260](https://github.com/ResearchObject/ro-crate/issues/260) 
 * [RO-Crate 1.1.2](https://github.com/ResearchObject/ro-crate/releases/tag/1.1.2) 
   * Typo fixes in [data entity section](../data-entities) [#177](https://github.com/ResearchObject/ro-crate/issues/177), [workflow section](../workflows) [#180](https://github.com/ResearchObject/ro-crate/issues/180), [metadata section](../metadata) [#181](https://github.com/ResearchObject/ro-crate/issues/181) 
   * Correct namespace for `rdfs:comment` on [ad-hoc terms](jsonld#add-local-definitions-of-ad-hoc-terms) [#164](https://github.com/ResearchObject/ro-crate/issues/164)

docs/_specification/1.2-DRAFT/appendix/implementation-notes.md

@@ -24,7 +24,7 @@ nav_order: 21
    limitations under the License.
 -->
 
-# APPENDIX: Implementation notes
+# APPENDIX: Implementation notes {#implementation-notes}
 {: .no_toc }
 
 ## Table of contents
@@ -96,8 +96,7 @@ e1105ed0…5e13  data/chipseq_20200910.json
 37fd3a02…bb95  data/results/pipeline_info/design_reads.csv
 ```
 
-{: .note }
-> The SHA-512 checksums have been shortened in the above example.
+{% include callout.html type="note" content="The SHA-512 checksums have been shortened in the above example." %}
 
 Creating the manifest file without using BagIt tools/libraries can be done using the equivalent of:
 
@@ -128,10 +127,9 @@ b0556450…8802  bag-info.txt
 000b27e3…c52e  manifest-sha512.txt
 ```
 
-{: .warning }
-The BagIt manifest is intended to detect "bit rot" and accidental damage,
+{% include callout.html type="warning" content='The BagIt manifest is intended to detect "bit rot" and accidental damage,
 it does not provide proof the RO-Crate has not been deliberately
-tampered with, as a malicious actor can also update the checksums.
+tampered with, as a malicious actor can also update the checksums.' %}
 
 Guarding against such scenarious would require additional cryptographic
 measures, e.g.  

docs/_specification/1.2-DRAFT/appendix/index.md

@@ -24,4 +24,10 @@ has_children: true
    limitations under the License.
 -->
 
-# Appendixes
+# Appendixes {#appendix}
+
+## Contents
+* [Changelog](changelog)
+* [Handling relative URI references](relative-uris)
+* [Implementation Notes](implementation-notes)
+* [RO-Crate JSON-LD](jsonld)

docs/_specification/1.2-DRAFT/appendix/jsonld.md

@@ -24,9 +24,7 @@ nav_order: 22
    limitations under the License.
 -->
 
-<div id="jsonld"></div>
-
-# APPENDIX: RO-Crate JSON-LD
+# APPENDIX: RO-Crate JSON-LD {#jsonld}
 {: .no_toc }
 
 ## Table of contents
@@ -175,8 +173,7 @@ To check which RO-Crate version is used (in terms of properties and types expect
 
 RO-Crate consumers SHOULD NOT do the opposite substitution from an embedded context, but MAY use the [JSON-LD flattening] algorithm with _compaction_ to a referenced _RO-Crate JSON-LD context_ (see also notes on [handling relative URI references](relative-uris) below).
 
-{: .tip }
-> The [JSON-LD flattening & compaction](https://www.w3.org/TR/json-ld-api/#flattening-algorithm) algorithms can be used to rewrite to a different `@context`, e.g. to `https://schema.org/docs/jsonldcontext.jsonld` or a different version of the _RO-Crate JSON-LD Context_.
+{% include callout.html type="tip" content="The [JSON-LD flattening & compaction](https://www.w3.org/TR/json-ld-api/#flattening-algorithm) algorithms can be used to rewrite to a different `@context`, e.g. to `https://schema.org/docs/jsonldcontext.jsonld` or a different version of the _RO-Crate JSON-LD Context_." %}
 
 ## RO-Crate JSON-LD Media type
 
@@ -277,8 +274,7 @@ For projects that have their own web-presence, URIs MAY be defined there and SHO
 </section>
 ```
 
-{: .tip }
-> Ensure you have a consistent use of `http` or `https` (preferring https) as well as consistent path `/vocab` vs `/vocab/` vs `/vocab/index.html` (preferring the shortest that is also visible in browser).
+{% include callout.html type="tip" content="Ensure you have a consistent use of `http` or `https` (preferring https) as well as consistent path `/vocab` vs `/vocab/` vs `/vocab/index.html` (preferring the shortest that is also visible in browser)." %}
 
 For ad hoc terms where the crate author does not have the resources to create and maintain an HTML page, authors may use the RO-Crate public namespace (`https://w3id.org/ro/terms/`) to reserve their terms. For example, an ad-hoc URI MAY be used in the form `https://w3id.org/ro/terms/some-project#myProperty` where `some-project` is acting as a _namespace_ for one or more related terms like `education`. Ad-hoc namespaces under `https://w3id.org/ro/terms/` are available on first-come-first-serve basis; to avoid clashes, namespaces SHOULD be registered by [submitting terms and definitions][ro-terms] to the RO-Crate terms project. 
 
@@ -314,8 +310,7 @@ Following the conventions used by Schema.org, ad-hoc terms SHOULD also include d
 ```
 
 
-{: .tip }
-> It is **not** a requirement to use English for the terms, labels or comments.
+{% include callout.html type="tip" content="It is **not** a requirement to use English for the terms, labels or comments." %}
 
 More information about the relationship of this term to other terms MAY be provided using [domainIncludes], [rangeIncludes], [rdfs:subClassOf], [rdfs:subPropertyOf], [sameAs] following the conventions used in the [Schema.org schema] -- *"Schema.org style schemas"*. For compatibility with RDFS/OWL tools, `name` and `description` SHOULD be duplicated using the RDFS properties `rdfs:label` and `rdfs:comment`:
 
@@ -337,11 +332,9 @@ More information about the relationship of this term to other terms MAY be provi
     }
 ```
 
-{: .note }
-> Schema.org also provides the types [Class] and [Property]. These MAY be used as an additional `@type` corresponding to `rdfs:Class` and `rdf:Property`, but as these are (for some reason) not used in Schema.org style schemas, they are also not required by RO-Crate. Likewise, an ontology defining such terms externally may be declaring properties there with more specific types like `owl:ObjectProperty` which do not need to be reflected in the RO-Crate reference.
+{% include callout.html type="note" content="Schema.org also provides the types [Class] and [Property]. These MAY be used as an additional `@type` corresponding to `rdfs:Class` and `rdf:Property`, but as these are (for some reason) not used in Schema.org style schemas, they are also not required by RO-Crate. Likewise, an ontology defining such terms externally may be declaring properties there with more specific types like `owl:ObjectProperty` which do not need to be reflected in the RO-Crate reference." %}
 
-{: .tip }
-> For compatibility with the official schema.org JSON-LD context, make sure any referenced `@id` to schema.org terms starts with `http://` rather than `https://` as shown in the browser.
+{% include callout.html type="tip" content="For compatibility with the official schema.org JSON-LD context, make sure any referenced `@id` to schema.org terms starts with `http://` rather than `https://` as shown in the browser." %}
 
 ## Grouping extensions as an RO-Crate profile