oasis-tcs / tab-respec Goto Github PK

OASIS Technical Advisory Board (TAB): Supporting development and maintenance of extensions to the ReSpec application to enable it to produce OASIS-styled specifications.

License: Other

JavaScript 90.48% CSS 3.67% HTML 5.85%

tab-respec's Introduction

Description

The purpose of this repository is to support development and maintenance of extensions to the ReSpec application to enable it to produce OASIS-styled specifications. The original work was done by Nicholas Crossley of the OSLC Core TC.

The TAB itself is not formally an OASIS Technical Committee, but a working group chartered by the OASIS Board to provide technical assistance to OASIS. The TAB supports this work as part of its mission to improve the standards development process and the quality of OASIS Standards.

Please also refer to the original README.

Getting started

Using the built versions of ReSpec

Once you have set up a spec using a template (from a readily published spec, for example), you should only update the JS bundle URI when a new TAB ReSpec version is released:

<script
  src="https://cdn.jsdelivr.net/gh/oasis-tcs/[email protected]/builds/respec-oasis-common.js"
  async
  class="remove"
></script>

Developing with ReSpec

First, switch your document to use ReSpec from a local development server:

<script src="http://127.0.0.1:9000/respec-oasis-common.js" async class="remove"></script>

Next, start a dev server to serve this file:

http-server -p 9000 builds/

Finally, set up an automatic ReSpec build when any of its files are changed:

cd tools/
fswatch -e '.*' -i '.*\.js$' -i '.*\.html$' --event Updated -x -r ../js/ | while read -r i; do node build-oasis-common.js ; done

Now you can refresh your specification document page and see how your local ReSpec build renders the document.

OASIS Information

Members of the Technical Advisory Board (TAB), in concert with members of the OSLC Open Project, create and manage technical content in this TC GitHub repository ( https://github.com/oasis-tcs/tab-respec) as part of the TAB's chartered work (i.e., the program of work and deliverables described in its charter).

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, are governed by the OASIS TC Process, IPR Policy, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from OASIS TC Open Repositories, which are used for development of open source licensed content.

Contributions

As stated in this repository's CONTRIBUTING file, contributors to this repository are expected to be Members of the OSLC Open Project or of the TAB, for any substantive change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an Project Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License.

Licensing

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the work in this GitHub project. Content in this repository is intended to be part of the TAB's and the OSLC Open Project's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE file.

Contact

Please send questions or comments about OASIS TC GitHub repositories to the OASIS Technical Committee Administrator. For questions about content in this repository, please contact the OSLC Open Project.

tab-respec's People

Contributors

Stargazers

Watchers

Forkers

berezovskyi paul-knight sthagen

tab-respec's Issues

Add a <base> tag to every standards-track doc

Stop updating unversioned release JS file

Spec drafts like https://raw.githack.com/oasis-tcs/oslc-domains/master/qm/quality-management-vocab.html and https://tools.oasis-open.org/version-control/svn/oslc-promcode/shape/trunk/spec.html directly reference https://ndjc.github.io/respec/builds/oasis/respec-oasis-common.js. We should also probably revert that file to pre-OP version.

Respec doesn't work with local bibliography names that include '.' period

We use a period in many of our OSLC citation references. But Respec doesn't work with biblio reference names that include a period. The References section omits them, and the references to them appear as plain text rather than links. There are no Respec errors logged on the web console.

from oslc-op/oslc-specs#304

Get the OASIS Open Projects icon at the top to align with the text

See oasis-open-projects/administration#1 (comment)

Add PDF links back to the PN template

Update Typographical Conventions and Use of RFC Terms

ReSpec should update the "Typographical Conventions and Use of RFC Terms" sections to use the current IETF format, which includes another RFC (8174) and reference to the specific BCP 14, along with the traditional 2119. It also adds "NOT RECOMMENDED" to the terms list.

Text:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Citations:
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, http://www.rfc-editor.org/info/rfc2119.

[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, http://www.rfc-editor.org/info/rfc8174.

New OP template loads logo from GH

If the file is deleted, moved, or anything happens to the repo or GH links, the published specs won't render:

<a href="https://www.oasis-open.org/"><img width="50%" src="https://github.com/oasis-open-projects/documentation/raw/master/img/open-project-logos/open-projects-logo.jpeg.jpg" alt="OASIS Open Projects" border="0" /></a>

ReSpec does not currently support this format of a biblio reference

[XML1]
Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, E. Maler, C. M. Sperberg-McQueen, F. Yergeau, Editors. World Wide Web Consortium, 16 August 2006, edited in place 29 September 2006. This edition of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816/. The latest edition of XML 1.0is available at http://www.w3.org/TR/xml/.

Support can be added in biblio.js:51 provided the config map is extended.

Evaluate backporting data-cite attr

See https://github.com/w3c/respec/wiki/data--cite#example-of-usage-with-a-element

It allows to link to an anchor and cite using a single biblio identifier.

Insert an <hr> tag before every h2 tag

Make sure it adds page-break-before: always
Make sure the hr after the logo does NOT add a page break
Resolve conflict with the border-top: medium solid #666666 on the <section> tag

Raw comment from Paul

The current basic (manual) process is to insert (either in <style> block of HTML or in .css file):
hr {
page-break-before: always;
}
Then insert

tags where needed, as follows:

In :

Change the horizontal rule just below the logo to avoid a page break in PDF: change the

Insert

tags (if not already present) before most of the

tags (i.e., main section headings)

but note: the
tag preceding most
tags generates another line (border-top: medium solid #666666;) thus the
tag should go before the
tag preceding each
tag)

[it may be possible to force the
tags to generate a page break - maybe a later investigation - but note there are also
tags before
, etc.]

"Latest stage:" is not being generated for PNs

Remove "published as Project Specification on 17 September 2020"

OASIS no longer requires previous rev links to be accompanied with the clarifying text such as "published as Project Specification on 17 September 2020".

As per https://issues.oasis-open.org/browse/TCADMIN-3996

ReSpec v2.1.25

ReSpec HTML generation for vocabularies omits enum constants

When generating the HTML for a vocabulary, ReSpec finds all classes, all properties, and all resources. It does this using fixed RDF type values for those three categories. A vocabulary term that is not one of the three fixed types (rdfs:Class, rdf:Property, or rdfs:Resource) will not be rendered.

Enum values are typically defined with a type of the parent enum class, and so will fall into this category of terms not rendered by ReSpec.

Pin last good version pre-OP

The mini-Markdown processing in shape tables is incomplete

The support for {{conformance clause}} and code example in ReSpec shape tables does not include the title - it should.

year and publisher in the list of references

Is your feature request related to a problem? Please describe.
From an academic pov, I think the year and publisher are essential elements of a citation.

Describe the solution you'd like

year key shall be added to the JSON object for each reference
publisher key shall be used in the rendering

Describe alternatives you've considered
We can stuff the status key but I would rather we not do this.

Additional context
Add any other context or screenshots about the feature request here.

"The English version of this specification is the only normative version" -> Status

"The English version of this specification is the only normative version. Non-normative translations may also be available."

The text shall be moved under the Status section as per https://issues.oasis-open.org/browse/TCADMIN-3996

ReSpec v2.1.25

Backport specref fix

Backport #30 on the branch off #33

The 'note' class has no special formatting

With ReSpec 2.1.22, the 'note' class has no special formatting to distinguish it from other text. Since notes are informative and not normative, some distinguishing formatting seems appropriate.

There also appears to be no special spacing added before a note header, nor any different formatting of the note title.

We should ascertain OASIS best practices for notes in specs, and set up an appropriate CSS style.

Can't push

The permission on https://github.com/orgs/oasis-tcs/teams/tab-respec-write/repositories is 'read'.

full OP name should be provided

On front page under "Open Project", the full OP name should be provided.
Instead of "OASIS OSLC OP",
it should be "OASIS Open Services for Lifecycle Collaboration (OSLC) OP".
The same change should be made on the first line of the "Status" section.

Multiple clauses have no separation

Here is the original:

First attempt at fixing it:

Group vocab details by category as well as the synopsis

This is how the vocab looks now:

This is the proposed change:

Build fails on Node 17

Error: Cannot find module 'requirejs'
Require stack:

/Users/ezandbe/git/a/oslc/op/specs/tab-respec/tools/builder.js

/Users/ezandbe/git/a/oslc/op/specs/tab-respec/tools/build-oasis-common.js
at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
at Function.Module._load (node:internal/modules/cjs/loader:778:27)
at Module.require (node:internal/modules/cjs/loader:999:19)
at require (node:internal/modules/cjs/helpers:102:18)
at Object. (/Users/ezandbe/git/a/oslc/op/specs/tab-respec/tools/builder.js:5:12)
at Module._compile (node:internal/modules/cjs/loader:1099:14)
at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
at Module.load (node:internal/modules/cjs/loader:975:32)
at Function.Module._load (node:internal/modules/cjs/loader:822:12)
at Module.require (node:internal/modules/cjs/loader:999:19) {
code: 'MODULE_NOT_FOUND',
requireStack: [
'/Users/ezandbe/git/a/oslc/op/specs/tab-respec/tools/builder.js',
'/Users/ezandbe/git/a/oslc/op/specs/tab-respec/tools/build-oasis-common.js'
]
}

Node.js v17.9.0

Our fork of ReSpec is accruing tech debt that may soon (when Node 16 LTS is EOLed on 2024-04-30) require more effort to fix that we are ready to spend.

Bug in table processing

Code

<section class="appendix informative" id="history">
  <h2>Change History</h2>

  <table border=1 cellspacing=0 cellpadding=0>
    <tr>
      <td width=103 valign=top style='width:77.4pt;border:solid windowtext 1.0pt;
  padding:0in 5.4pt 0in 5.4pt'><b>Revision</b></td>
      <td width=96 valign=top style='width:1.0in;border:solid windowtext 1.0pt;
  border-left:none;padding:0in 5.4pt 0in 5.4pt'><b>Date</b></td>
      <td width=144 valign=top style='width:1.5in;border:solid windowtext 1.0pt;
  border-left:none;padding:0in 5.4pt 0in 5.4pt'><b>Editor</b></td>
      <td width=295 valign=top style='width:221.4pt;border:solid windowtext 1.0pt;
  border-left:none;padding:0in 5.4pt 0in 5.4pt'><b>Changes Made</b></td>
    </tr>
    <tr>
      <td>01</td>
      <td>06/10/2017</td>
      <td>Gray Bachelor</td>
      <td>Initial migration version.</td>
    </tr>
    <tr>
      <td>02</td>
      <td>26/12/2017</td>
      <td>Gray Bachelor</td>
      <td>Next edits towards migration version.</td>
    <tr>
      <td>03</td>
      <td>28/06/2018</td>
      <td>Gray Bachelor</td>
      <td>Align with released CM 3.0.</td>
    </tr>
    <tr>
      <td>04</td>
      <td>27/07/2018</td>
      <td>Gray Bachelor</td>
      <td>Align with RM and Asset 2.1.</td>
      /tr>
    <tr>
      <td>05</td>
      <td>08/08/2018</td>
      <td>Gray Bachelor</td>
      <td>Check and fix some V2.1 labelling</td>
    </tr>
    <tr>
      <td>06</td>
      <td>2019-09-19</td>
      <td>Andrew Berezovskyi</td>
      <td>Prepare the QM 2.0 PSD 02 for publication</td>
    </tr>
  </table>
</section>

Output:

2 HR tags are inserted after the TOC

Originally reported in oslc-op/oslc-specs#296

ReSpec renders publishDate one day earlier than specified

Describe the bug
tracked-resource-set.html specifies publishDate as publishDate: "2021-08-05", but when ReSpec renders the HTMl source, it displays 04 August 2021.

To Reproduce
Steps to reproduce the behavior:

Open tracked-resource-set.html
See the rendered publish date is 04 August 2021
Open the html source.
See publishDate: "2021-08-05",

Expected behavior
Date should display as 05 August 2021 as specified for the publishDate.

ReSpec version
2.1.27

Remove issue templates

I am afraid I fail to see their true value.

URL for latestVersion PDF is the same as the HTML

    latestVersion: oasisBase + "architecture-management-spec.html",

Results in these URLs in the spec:
Latest stage:
https://docs.oasis-open-projects.org/oslc-op/am/v3.0/architecture-management-spec.html (Authoritative)
https://docs.oasis-open-projects.org/oslc-op/am/v3.0/architecture-management-spec.pdf

(the PDF has the same URL as the HTML

dcterms:issued and dt-published do not match

Describe the bug
When the spec snapshot is saved, the dcterms:issued and dt-published are added but they do not match. From https://issues.oasis-open.org/browse/TCADMIN-3996:

<span property="dcterms:issued" datatype="xsd:dateTime" content="2021-05-26T22:00:00.000Z"><time class="dt-published" datetime="2021-05-27">27 May 2021</time></span>

To Reproduce
Steps to reproduce the behavior:

Go to CM OS spec
Save Snapshot
See error in the source code.

Expected behavior
The dates in both properties shall match.

ReSpec version
v2.1.25

A conformance paragraph or table is required for your type of document.

oasis-tcs / tab-respec Goto Github PK

tab-respec's Introduction

Description

Getting started

Using the built versions of ReSpec

Developing with ReSpec

OASIS Information

Contributions

Licensing

Contact

tab-respec's People

Contributors

Stargazers

Watchers

Forkers

tab-respec's Issues

tags generates another line (border-top: medium solid #666666;) thus the tag should go before the tag preceding each tag) [it may be possible to force the tags to generate a page break - maybe a later investigation - but note there are also tags before , etc.]

tag) [it may be possible to force the tags to generate a page break - maybe a later investigation - but note there are also tags before , etc.]

, etc.]

Recommend Projects

Recommend Topics

Recommend Org

tags generates another line (border-top: medium solid #666666;) thus the
tag should go before the
tag preceding each
tag)

[it may be possible to force the
tags to generate a page break - maybe a later investigation - but note there are also
tags before
, etc.]

tag)

[it may be possible to force the
tags to generate a page break - maybe a later investigation - but note there are also
tags before
, etc.]