Skip to content

Publishing documents

Jump to bottom
Matt Garrish edited this page Jul 11, 2024 · 1 revision

This page details the process for publishing new versions of the eBraille specification and best practices guides. Only the Working Group chairs and editors are allowed to publish new versions.

Note: Publishing a new version requires that you have a local copy of the repository on your computer and a git client. GitHub Desktop provides a fairly easy interface to manage files if you're new to working with GitHub repositories. After installing, you can download a local copy of this repository by going to "Code" tab and clicking on the green "Code" button in the options at the top of the page. Select the "Open with GitHub Desktop" option to begin the process.

Update the Publication Dates

Make sure that the publication dates and URLs in the respec metadata match the last publication and current publication dates. The following fields need to be updated before exporting:

  • thisVersion needs the date in the URL changed to the date you are publishing the document
  • previousVersion needs to be set to the date the vocabulary was last published

Export the documents

The first step in publishing a new draft of the specification is to export a static version of the file from the Respec tool:

  1. If you plan to publish the same day, go to the URL: https://daisy.github.io/ebaille/?daisyStatus=WD
  2. If you intend to publish on a future date, go to the URL: https://daisy.github.io/ebraille/?daisyStatus=WD&publishDate=YYYY-MM-DD (filling in the numeric date for the placeholder letters YYYY-MM-DD)
  3. Check that Respec does not report any errors or warnings (there will be a yellow or red circle with a number in it beside the "Respec" box at the top right of the document). Fix all issues before continuing.
  4. Run the link checker on the document using the following URL: http://validator.w3.org/checklink?uri=https%3A%2F%2Fdaisy.github.io%2Febraille&hide_type=all&depth=&check=Check Fix any broken links before continuing (redirect warnings can be ignored).
  5. From the URL you opened in step 1 or 2, click on the "Respec" box in the top right corner and select the "Export" option from the drop-down menu.
  6. Choose "HTML" from the list of export options.

Depending on your browser settings, the exported HTML may download automatically to a default downloads directory or you may be prompted to save the file manually.

To export a best practices guide, follow the same steps as above but change the URLs to add the path to the best practices guide and use the WG-NOTE status. For example:

When publishing final releases, use the status REC for the specification and WG-NOTE for the best practices guides.

Commit the New Version

  1. Locate the exported HTML file from the previous step on your file system.
  2. Rename the file to index.html
  3. Copy the file to the /published/ebraille/1.0/ directory in your local copy of the ebraille repository.
  4. ... additional steps to be determined for ebraille ...
  5. Update the respec metadata in editor's draft (the index.html file in the repository root) so the previousPublishDate field matches the new release date (this change is used for the next publishing of the vocabulary).
  6. Using your git client, commit the files back to the repository - include a commit message that explains the change.

You can now check that the new version is live by going to the URL: https://daisy.github.io/ebraille/1.0/

Note that changes to the document may not always be reflected immediately. It may also take a hard refresh (ctrl+F5 on Windows or Cmd+Shift+R on Mac) to view the updated file.

If you discover an issue that needs correcting after publication, note that the change of the last publication date in step #5 will need to be overridden before publishing again, otherwise the previous version link will go to the current release.

Clone this wiki locally