Editor's guide

Guide for editors of RDF-star specs

• We use ReSpec as the format for all documents, and locate them in the /spec directory of each repository, along with related files (images, grammars, etc.)

Common configuration options

Include the following scripts:

  <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
  <script src="./common/local-biblio.js" class="remove"></script>
  <script src="./common/fixup.js" class="remove"></script>

Do not defer loading of respecc-w3c, as fixup.js needs access to some of the things it loads.

Common files are contained in the rdf-common repository and should be copied to /spec/common directory. There is a step in a GitHub Action that can check to verify that these files are consistent.

Generally, common/local-biblio.js should contain common bibliographic references. if they are widely used, they can be added permanently to specRef.

Entries are in local-biblio for the 1.2 specs, but shouldn't be necessary after FPWD, when they'll automatically be added to specRef.

common/fixup.js includes an end-all event to correct entries such as <a data-cite="RDF12-CONCEPTS#triple">...</a> such that, when used in a document with the same short-name, it will un-anchor it and add (this document). Used for localizing common/related.html.

respecConfig

• Add localBiblio: localBibliograph, which is defined in common/local-biblio.js.
• Remember that edDraftURI should end in /spec/, so that referencing the editors draft doesn't take you to the repository, but to the rendered draft.
• previosPublishDate, previousMaturity, and prefRecShortname should be set up for the 1.1 recommendations.
• Use formerEditors to recognize previous editors.

We might consider creating a common CSS file to help maintain consistency between the different specs.

sotd

The sotd section (which automatically gets a heading) should have something that includes common/related.html using data-include. We need to decide if each document should list all related RDF and SPARQL documents, or we create subsets for RDF and SPARQL.

Definitions

• Define terms using <dfn>, which can take some modifiers. Note that data-lt can be used to define aliases for that term, but also affects which is actually exported from the spec. (see the "index" section). Use class="export" or class="noexport" to control its visibility.
• If changing a previous definition (e.g., because it was errantly exported as plural, or duplicately defined), add a span element with an id attribute so that any dangling references go someplace. For example: <dfn data-lt="inconsistent">Inconsistency</dfn><span id="dfn-inconsistency"><!-- obsolete term --></span>.

Citing other documents and definitions.

ReSpec provides a number of different ways to reference definitions from different documents.

• Bare anchors will automatically be filled in if there is a match with a local (or cross-referenced) definition. E.g., <a>triple</a> would be styled and updated to <a href="#dfn-triple">triple</a>.
  • This automatically handles most plural forms, but can be made explicit using data-lt.
  • To include definitions from select other documents or document sets, use xref in respecConfig. Some document use xref: ["RDF11-CONCEPTS"], which can change to "RDF12-CONCEPTS" after FPWD.
• Anchors can use data-cite to explicitly get a term (or other fragment) from another document, which has the added attribute of adding a citation to that document. E.g., <a data-cite="RDF12-CONCEPTS#dfn-triple">triple</a>. (Note that they've marked this as obsolete, and there's a guide for xref, but I've resisted doing this).
• Normal [[]] references can add citations (e.g., [[RDF12-CONCEPTS]]), and the form with three brackets [[[RDF12-CONCEPTS]]] will expand the document name.

Examples

Use either <pre class="example"> or <aside class="example"> for example blocks. Examples can have titles, and we should consider a policy on using this.

Blocks within an example do not need to be left justified, as ReSpec does this automatically now.

Consider using data-transform="updateExample" with <!-- .. --> comments to avoid entity escapes. This also allows for adding comments (####) and highlighting (****) for those examples with some CSS styling. See common/fixup.js. Automatic example highllighting may mess this up, in which case class="nohiglight" may be necessary.

  <pre class="example nquads" data-transform="updateExample">
    <!--
    <http://one.example/subject1> <http://one.example/predicate1> <http://one.example/object1> <http://example.org/graph3> . # comments here
    # or on a line by themselves
    _:subject1 <http://an.example/predicate1> "object1" <http://example.org/graph1> .
    _:subject2 <http://an.example/predicate2> "object2" <http://example.org/graph5> .
    -->
  </pre>

Contributors

Configuration fields

Direct contributors to the specification can be classified as editors, formerEditors, or authors.

Entries can use fields from a Person entry.

All editors MUST have a w3cid field, other uses may include it as well.

The use of url field for personal URLs discouraged.

Consider using the note field to describe a particular type of contribution (e.g., "Chair", "Contributor", etc.)

Acknowledgements

Respec has special treatment for an element with id gh-contributors, which is automatically loaded and formatted with the names of people committing to the repository (excluding editors). For example:

<section id="section-Acknowledgments" class="informative appendix">
  <h2>Acknowledgments</h2>

  <p>The following people have contributed to this specification:
    <span id="gh-contributors"></span>
  </p>

  <p>In addition to the <a href="https://www.w3.org/groups/wg/rdf-star/participants">members of the RDF-star Working Group</a>.</p>
</section>

Other

• Include a definition index to show all locally defined and imported definitions.
• Include an issue summary to show issues from the repo.
• Use data-number to reference a specific issue.
• Consider hiding details in <details>.