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.) The ReSpec Editor's Guide and wiki contain useful information about working with ReSpec documents.

Local editing

Because the specs include files, running locally requires using a local web server. One simply way to do this is to run python -m http.server in the repository, or something in the directory tree including the repository clone. Then, the spec page can be opened through localhost on whatever port it runs on. For example, http://localhost:8000/spec/.

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>.
• Significant changes should be recorded in the change log at the bottom.
• Use the ReSpec features for linking to documents and definitions. (class=“sectionRef” useful for internal links).
• Validate HTML before checking in.

Working with GitHub

• Please perform a timely review of PRs for which you share responsibility.
  • The "suggestion" commenting mechanism can help.
• Make effective use of pull requests, and be sure to ask co-editors, and anyone else interested for reviews.
• Consider using squash commits if there are too many little changes along they way; otherwise, consider using Rebase to keep the longs clean.
• Remove branches after merging.
• Make issues and refer to them either/both wihin the doc, or in the PR comments. “Fixes #nnn” or “Relates to #nnn” links the PR to the issue.
• You can run ReSpec locally (with ?specStatus=WD) to pre-flight the GH Action.
• Don’t make changes in spec/common directly, but we should coordinate on changes to the rdf-common repo. If they’re out of sync, the GH Action build may fail.