These are notes taken by the OSLC Core editor that documents the process and changes required to publish a TC work product using ReSpec source from GitHub to the OASIS document repository. These notes could be used to inform future changes to ReSpec HTML snapshot generation to automate some of these manual steps.

OASIS TCs may periodically publish Committee Specification Draft (CSD) documents which can be published into the OASIS document repository. These published documents can be used to capture specific document states or to make the TC's work products available to others for additional reviews and input. When using GitHub and ReSpec, this step is often unnecessary since specific document versions can be accessed from GitHub, and are formatted by ReSpec when the documents are accessed as HTML.

When a TC wishes to submit a work product for public review, it must publish a Committee Specification Draft Public Review (CSPRD) document to the OASIS document repository. ReSpec is used to process the OSLC Domain specification HTML source files into HTML documents that closely, but not completely follow OASIS document publication requirements. There are a few manual steps that have to be performed to create the published HTML and PDF files. This document summarizes those manual steps. Hopefully future updates to ReSpec will reduce or eliminate these manual steps.

OASIS work products must be published in:

1. editable source: this is provided by HTML ReSpec source in GitHub
2. HTML: generated by ReSpec with updates to published URIs from GitHub to OASIS docs
3. PDF: generated from the published HTML using Adobe Firefox plugin

The published files have to follow the OASIS naming directives:

• title: OSLC Core
• partNumber: from the title of the multi-part specifications
• shortName: oslc-domains
• specStatus: CSPRD
• oslcVersion: 3.0
• revision: 01

A complete set of all multi-specification parts are required for CSPRD with the appropriate file names:

1. Sent to OASIS in a zip file
2. The published editable source and HTML in docs.oasis-open.org/oslc-domains-spec cannot be links to the corresponding tagged version in GitHub, they must be cloned and stored the TC document repository in Kavi.
3. Generate the PDF from the ReSpec generated HTML using Adobe Firefox plugin
4. The PDF file will need to have page footers manually created or updated
5. Additional artifacts include all the vocabulary and shape files, but need only reference the containing folder http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/[doc-id].[ext]

The first step is to make and commit specific edits to the ReSpec source documents in preparation for generating the published work products:

• Make sure the respec-oasis-common.js and respecConfig scripts have attribute class='remove'

• Change specStatus to the appropriate status based on the document state: "CSD", "CSPRD" or "CS"

• Set the revision number, e.g., "01", "02"

• Update publishDate to the date specified in the TC vote, e.g., "2017-09-29"

• The shapes .ttl files in GitHub should have @base changed to their stable open-services.net/ns URI.

• Update the Change History to summarize the changes in this revision, e.g., the changes between revision 01 and 02.

• Set thisVersion: to the URL to the published OASIS document URI using OASIS Naming Directives.
  
  For example: http://docs.oasis-open.org/oslc-domains/cm/v3.0/csprd01/part1-change-mgt/cm-v3.0-csprd01-part1-change-mgt.html

• Set latestVersion: to the sym link used when OASIS publishes the specifications, not the link to the document in GitHub. This URL doesn’t change and setting it in the source eliminates the need to edit it when publishing.
  
  For example: http://docs.oasis-open.org/oslc-domains/cm/v3.0/cm-v3.0-part1-change-mgt.html

• Update the preVersion value to refer to the previously published OASIS document if any. Use "" if there was no previously published OASIS document.

• Including references to open-services.net specification documents in a relatedWork element in the respecConfig if needed. Use status: "Work in progress. Current draft" for committee note references that are not yet published.

• The additionalArtifacts: href: property should be the same URI as the thisVersion: URI.

• Remove the edDraftURI: field

For each multi-part document making up the complete specification:

• Run ReSpec on each of the ReSpec source files and capture the resulting generated HTML

1. Open the .html source file with Firefox
2. Click on ReSpec Button and select Save Snapshot
3. The generated file will be stored in your downloads folder using {domain-short-name}.html
4. Move this page to the desired publish folder and rename using the OASIS Naming Directives.

• Specification: [WP-abbrev]-[version-id]-[stage-abbrev][revisionNumber].[ext]
• Multi-part Specification: [WP-abbrev]-[version-id]-[stage-abbrev][revisionNumber]-[partNumber]-[partName].[ext]

For example:

• change-mgt-spec.html —> cm-v3.0-csprd01-part1-change-mgt.html
• change-mgt-vocab.html —> cm-v3.0-csprd01-part2-change-mgt-vocab.html
• requirements-management-spec.html —> rm-v2.1-csprd01-requirements-management.html

Note: Bibliography and additional artifact links use the folder and component stage names since they are other components that go with the specification.

• Copy the source for the oslc-styles.css, table_styles.css and definition-styles from the styles folder in GitHub to the styles folder in your publish folder

• Copy any impages used by the specification document from the source folder to the images folder in your publish folder.

• Verify the results are formatted correctly in a number of browsers to see if there are HTML generation issues, verify all links

Use Adobe Acrobat with the Firefox plugin to generate the PDF files from the completed HTML files. Another potential option is described in https://www.nickvahalik.com/blog/finally-html-pdf-workflow-works.

Use Adobe Acrobat to edit the PDF files to add the page footers that includes the TC vote date and extra page breaks

1. Open HTML file in Firefox and use Adobe Acrobat DC - Create PDF add-on to generate the PDF file
2. Set preferences to NOT place headers and footers on new page - this prevents the generator from creating headers and footers
3. Set preferences for 0.5 in left and right margin
4. Edit the PDF file using Adobe Acrobat and update the footer text as below: L C R

Firefox Adobe Acrobat DC - Create PDF plugin works correctly and opens the PDF in Adobe Acrobat for subsequent footer editing.

oslc-domains-v3.0-csprd01-part1-change-mgt

Standards Track Work Product

Copyright © OASIS Open 2017. All Rights Reserved.

09 September 2017

• Check everything into SCM and tag if desired

• Create new csprd01.zip file and upload it to the Kavi Documents, Working Drafts folder.

• Use Publish a Committee Specification Draft or other appropriate TC Administration Requests for to ask for the document to be published.

[ ] @context and @base properties in example JSONLD files use GitHub URIs. Its not clear where these should go - possibly on OASIS with a consistent sym link to the file, or open-services.net with the namespaces some place. Or we could leave it as it is since the GitHub repository is publicly accessible. This would be the simplest approach. Resolution: these should use their open-services.net namespace path.

[ ] Supporting Documents - Committee Notes, are these being published or just referenced from GitHub? For now, just reference from GitHub. Can a CSD or even OASIS Standard reference a committee note working draft. Use the status field to indicate its Work in progress as described above.

(none at this time)