Skip to content

Commit 73a71bb

Browse files
carlwilsoncarlwilson
authored
Merge pull request #14 from DILCISBoard/rel/v1.0.0
REL: V1.0.0
2 parents 4b8bee9 + 7d6f413 commit 73a71bb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+3181
-1
lines changed

‎.github/workflows/jekyll-gh-pages.yml

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
2+
name: Deploy Jekyll with GitHub Pages dependencies preinstalled
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
release:
7+
types: [published]
8+
workflow_dispatch:
9+
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
# Build job
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v3
30+
with:
31+
submodules: recursive
32+
- if: github.event.release != null
33+
name: set release vars from release event
34+
run: |
35+
echo "LONG_DATE=${{ github.event.release.published_at }}" >> $GITHUB_ENV
36+
echo "LONG_VERSION=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
37+
- if: github.event.release == null
38+
name: Get previous release
39+
id: previousrelease
40+
uses: InsonusK/[email protected]
41+
with:
42+
myToken: ${{ github.token }}
43+
exclude_types: draft|prerelease
44+
view_top: 1
45+
- if: github.event.release == null
46+
name: set release vars from previous release
47+
run: |
48+
echo "LONG_DATE=${{ steps.previousrelease.outputs.created_at }}" >> $GITHUB_ENV
49+
echo "LONG_VERSION=${{ steps.previousrelease.outputs.tag_name }}" >> $GITHUB_ENV
50+
- name: Cut release date
51+
uses: bhowell2/[email protected]
52+
id: cut_release_date
53+
with:
54+
value: ${{ env.LONG_DATE }}
55+
length_from_start: 10
56+
- name: Cut release versopm
57+
uses: bhowell2/[email protected]
58+
id: cut_release_version
59+
with:
60+
value: ${{ env.LONG_VERSION }}
61+
index_of_str: "v"
62+
- name: Substitute env vars in files
63+
uses: chris-peterson/virgo@v1
64+
env:
65+
RELEASE_DATE: ${{ steps.cut_release_date.outputs.substring }}
66+
RELEASE_VERSION: ${{ steps.cut_release_version.outputs.substring }}
67+
with:
68+
templates: "metadata.yaml, guidelines/metadata.yaml"
69+
- name: Build the spec-publisher project & produce site artifacts
70+
run: |
71+
./create_site.sh
72+
- name: Run Docker job for PDF publication
73+
run: |
74+
docker run --rm -v "$PWD:/source" --entrypoint /source/create_pdf.sh eark4all/spec-pdf-publisher
75+
- name: Run Docker job for Guidelines PDF publication
76+
run: |
77+
docker run --rm -v "$PWD:/source" --entrypoint /source/create_guidelines_pdf.sh eark4all/spec-pdf-publisher
78+
- name: Setup Pages
79+
uses: actions/configure-pages@v3
80+
- name: Build with Jekyll docker box
81+
run: |
82+
mkdir _site
83+
docker run --rm -v "$PWD"/site:/usr/src/app -v "$PWD"/_site:/_site starefossen/github-pages jekyll build -d /_site
84+
- name: Upload artifact
85+
uses: actions/upload-pages-artifact@v1
86+
87+
# Deployment job
88+
deploy:
89+
environment:
90+
name: github-pages
91+
url: ${{ steps.deployment.outputs.page_url }}
92+
runs-on: ubuntu-latest
93+
needs: build
94+
steps:
95+
- name: Deploy to GitHub Pages
96+
id: deployment
97+
uses: actions/deploy-pages@v2

‎.gitmodules

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "spec-publisher"]
2+
path = spec-publisher
3+
url = [email protected]:DILCISBoard/spec-publisher.git

‎PUBLICATION.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Record of steps taken to move this CITS to the new publication platform
2+
3+
## Added this `PUBLICATION.md` file
4+
5+
This is simply a record of the steps taken to add this CITS to the new publication platform. The steps are recorded
6+
here so that they can be repeated for other CITS.
7+
8+
```bash
9+
git add PUBLICATION.md
10+
```
11+
12+
## Added `spec-publisher` project as a git submodule
13+
14+
The spec-publisher project is required to:
15+
16+
- generate tables of requirements from the CITS METS profiles; and
17+
- generate preface material, acknowledgements, and appendices.
18+
19+
The spec-publisher project is a git submodule of the CITS project. This means that the spec-publisher project is a
20+
separate git repository that is included in the CITS project as a subdirectory. The spec-publisher project is not
21+
included in the CITS project's git history. Instead, the CITS project includes a reference to the spec-publisher
22+
project's git repository and commit.
23+
24+
```bash
25+
git submodule add [email protected]:DILCISBoard/spec-publisher.git
26+
git commit -m "Add spec-publisher as a submodule"
27+
```
28+
29+
## Modularise the specificataion, breaking at tables
30+
31+
Next we break down the Mardown files so that there is an end of a Markdown file before every table. Follwing this the
32+
`specification` folder looks like this:
33+
34+
![Specification folder following the modularisation of the document](spec-folder.png)
35+
36+
## Create a `specification.yaml` YAML file that describes the final document structure
37+
38+
The `specification.yaml` sequences all of the separate Markdown files, generated tables of requirements and other
39+
material into a coherent document. The document is broken into three sections:
40+
41+
1. preface
42+
2. body
43+
3. appendices
44+
45+
The distinction controls the pagination, insertion of contents and a few other things.
46+
47+
### Preface
48+
49+
This imports the common introduction to all E-ARK specifications, from the `spec-publisher` project sub-module.
50+
51+
```yaml
52+
preface:
53+
- name: introduction # A name for the section, really for readability
54+
type: file # The type of content, controls the handling in spec-publisher
55+
source: spec-publisher/res/md/common-intro.md # The relative path to the common-intro.md file
56+
```
57+
58+
### Body
59+
60+
This sequences the main body of the document in similar fashion to the preface. It also uses the `type: requirements`
61+
to generate tables of requirements from the METS profiles.
62+
63+
```yaml
64+
body:
65+
...
66+
- name: implementation
67+
type: file
68+
source: specification/implementation/implementation.md
69+
70+
- name: requirements.METS.root
71+
type: requirements
72+
heading: "Table 2: Root METS root element (element METS root)"
73+
requirements:
74+
- 3DPM12
75+
- 3DPM13
76+
- 3DPM14
77+
- 3DPM15
78+
```
79+
80+
The second block (`name: requirements.METS.root`) above shows how to describe a table of requirements. There is no `source:` key as the content is generated by the spec-publisher. The `heading:` key is used to provide a heading for the table. The `requirements:` key is a list of requirement identifiers that are used to generate the table.
81+
82+
### Appendices
83+
84+
All of the appenices are automatically generated from the METS profile by the spec-publisher. It is possible to include Markdown files in the appendices as well.
85+
86+
```yaml
87+
88+
appendices:
89+
- name: mets.examples # Generates a list of examples
90+
heading: "CITS3D Information Package METS Examples" # The heading for the Appnedix
91+
label: "A" # The label for the Appendix
92+
type: mets # The type of content, controls the handling in spec-publisher
93+
section: Appendix # The section of the METS file to use for the section
94+
95+
- name: mets.schema # Generates a list of external schema
96+
heading: "External Schema"
97+
label: "B"
98+
type: mets
99+
section: external_schema
100+
101+
- name: mets.vocabs # Generates a list of external vocabularies
102+
heading: "External Vocabularies"
103+
label: "C"
104+
type: mets
105+
section: vocabulary
106+
107+
- name: mets.metadata.requirments # Generates a list of all profile requirements
108+
heading: "E-ARK CITS3D Metadata Requirements"
109+
label: "E"
110+
type: mets
111+
section: requirements
112+
```
113+
114+
These sections simply use the appropriate METS file elements, identified by the `section:` value, to generate the content.

‎README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
# CITS-3DPM
2-
Content Information Type Specification for 3D Product Model (CITS 3D PM)
2+
## Content Information Type Specification for 3D Product Model (CITS 3D PM) ##
3+
The CITS 3D PM is a Content Information Type Specification (CITS) for 3D Product Models as used in the engineering and aerospace industries. The specification is designed to be used for the transfer to archives as well as for records exchange between different 3D Product Model systems. The specification is supported by METS profiles for the Root and Representation METS files, an accompanying Guideline document and package examples. The 3D Product Model content specification limits its scope to the area of 3D digital product data such as computer aided design (CAD) or product data model (PDM) data where there is a current international standard for the long term archiving of this class of data in the LOTAR “Long Term Archiving and Retrieval of digital technical product information” , which is published as the EN and NAS 9300 series. However, although LOTAR extensively references and extends ISO 14721 the “Open reference model for Archiving Information System”, (OAIS) it does not extend into areas detailed in the E-ARK common specification for information packages (CSIP). LOTAR references and builds on ISO 10303, the Standard for the Exchange of Product model data (STEP) and so with this E-ARK 3D PM CITS we have the opportunity to add to an existing layered standards model.

‎create_guidelines_pdf.sh

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/usr/bin/env bash
2+
echo "Generating PDF guidelines from markdown"
3+
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
4+
cd "$SCRIPT_DIR" || exit
5+
6+
cp -rf "$SCRIPT_DIR/spec-publisher/pandoc/img" "$SCRIPT_DIR/guidelines/pdf/"
7+
cp -rf "$SCRIPT_DIR/spec-publisher/res/md/figs" "$SCRIPT_DIR/guidelines/pdf/"
8+
cp -rf "$SCRIPT_DIR/guidelines/markdown/figs" "$SCRIPT_DIR/guidelines/pdf/"
9+
cd guidelines/pdf || exit
10+
11+
echo " - PANDOC: Generating Preface from markdown"
12+
pandoc --from gfm \
13+
--to latex \
14+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
15+
"./preface.md" \
16+
-o "./preface.tex"
17+
sed -i 's%section{%section*{%' ./preface.tex
18+
19+
echo " - PANDOC: Generating Postface from markdown"
20+
pandoc --from markdown \
21+
--to latex \
22+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
23+
"$SCRIPT_DIR/guidelines/markdown/postface/postface.md" \
24+
-o "./postface.tex"
25+
sed -i 's%section{%section*{%' ./postface.tex
26+
27+
command -v markdown-pp >/dev/null 2>&1 || {
28+
tmpdir=$(dirname "$(mktemp -u)")
29+
# shellcheck source=/tmp/.venv-markdown/bin/activate
30+
source "$tmpdir/.venv-markdown/bin/activate"
31+
}
32+
33+
echo " - MARKDOWN-PP: Preparing PDF markdown"
34+
markdown-pp PDF.md -o 3D_Product_Data_Guideline-pdf.md -e tableofcontents
35+
echo " - MARKDOWN-PP: Preparing PDF markdown"
36+
37+
if [ -d "$SCRIPT_DIR/site/guidelines/pdf" ]
38+
then
39+
echo " - Removing old guidelines PDF directory"
40+
rm -rf "$SCRIPT_DIR/site/guidelines/pdf"
41+
fi
42+
mkdir "$SCRIPT_DIR/site/guidelines/pdf"
43+
44+
echo " - PANDOC: Generating Guidelines PDF document from markdown and Tex sources"
45+
pandoc --from markdown \
46+
--template "$SCRIPT_DIR/spec-publisher/pandoc/templates/eisvogel.latex" \
47+
--listings \
48+
--table-of-contents \
49+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
50+
--include-before-body "./preface.tex" \
51+
--include-after-body "./postface.tex" \
52+
--number-sections \
53+
-o "$SCRIPT_DIR/site/guidelines/pdf/3D_Product_Data_Guideline_v1.0.0.pdf" \
54+
3D_Product_Data_Guideline-pdf.md
55+
56+
echo " - Finished"

‎create_pdf.sh

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#!/usr/bin/env bash
2+
echo "Generating PDF document from markdown"
3+
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
4+
cd "$SCRIPT_DIR" || exit
5+
6+
cp -rf "$SCRIPT_DIR/spec-publisher/pandoc/img" "$SCRIPT_DIR/doc/pdf/"
7+
cp -rf "$SCRIPT_DIR/spec-publisher/res/md/figs" "$SCRIPT_DIR/doc/pdf/"
8+
cp -rf "$SCRIPT_DIR/specification/figs" "$SCRIPT_DIR/doc/pdf/"
9+
cd doc/pdf || exit
10+
11+
echo " - PANDOC: Generating Preface from markdown"
12+
pandoc --from gfm \
13+
--to latex \
14+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
15+
"./preface.md" \
16+
-o "./preface.tex"
17+
sed -i 's%section{%section*{%' ./preface.tex
18+
19+
echo " - PANDOC: Generating Postface from markdown"
20+
pandoc --from markdown \
21+
--to latex \
22+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
23+
"$SCRIPT_DIR/specification/postface/postface.md" \
24+
-o "./postface.tex"
25+
sed -i 's%section{%section*{%' ./postface.tex
26+
27+
command -v markdown-pp >/dev/null 2>&1 || {
28+
tmpdir=$(dirname "$(mktemp -u)")
29+
# shellcheck source=/tmp/.venv-markdown/bin/activate
30+
source "$tmpdir/.venv-markdown/bin/activate"
31+
}
32+
33+
echo " - MARKDOWN-PP: Preparing PDF markdown"
34+
markdown-pp PDF.md -o eark-3dpm-pdf.md -e tableofcontents
35+
echo " - MARKDOWN-PP: Preparing PDF markdown"
36+
sed -i 's%@csip:CONTENTINFORMATIONTYPE='\''cits3dpm_v1_0'\''%@csip:CONTENTINFORMATIONTYPE='\''cits3dpm\\_v1\\_0'\''%' ./eark-3dpm-pdf.md
37+
38+
39+
if [ -d "$SCRIPT_DIR/site/pdf" ]
40+
then
41+
echo " - Removing old site PDF directory"
42+
rm -rf "$SCRIPT_DIR/site/pdf"
43+
fi
44+
mkdir "$SCRIPT_DIR/site/pdf"
45+
46+
echo " - PANDOC: Generating PDF document from markdown and Tex sources"
47+
pandoc --from markdown \
48+
--template "$SCRIPT_DIR/spec-publisher/pandoc/templates/eisvogel.latex" \
49+
--listings \
50+
--table-of-contents \
51+
--metadata-file "$SCRIPT_DIR/spec-publisher/pandoc/metadata.yaml" \
52+
--include-before-body "./preface.tex" \
53+
--include-after-body "./postface.tex" \
54+
--number-sections \
55+
eark-3dpm-pdf.md \
56+
-o "$SCRIPT_DIR/site/pdf/eark-cits-3dpm.pdf"
57+
58+
echo " - Finished"

0 commit comments

Comments
 (0)