Skip to content

publishing_process.md

Latest commit

 

History

History
44 lines (32 loc) · 5.62 KB

publishing_process.md

File metadata and controls

44 lines (32 loc) · 5.62 KB

Repo organization and the publishing process

The working directories are on the 'top level', like /syntax (this one will be used as an example in what follows). The index.html file in those directories are the respec sources, plus the possible other accompanying files. The respec config typically says something like

specStatus: "ED",
// publishDate: "",
previousPublishDate: "2014-03-04"

the /publishing-snapshot directory contains specific milestone publications, e.g., FPWD-syntax or, later, WD-syntax-2014-XX-XX for a copy of what is officially published at W3C. This means all the relevant data files from /syntax, plus a generated Overview.html file as a pure HTML5 file (i.e., not a respec source).

The publication process

(Obviously, many of these steps are typically done in your local repo and then committed to github when appropriate.)

  1. Update the /local-biblio.js and change the URL-s in the conversions array to reflect the right URI for the /TR document. This step will ensure that the right cross references will be generated in the final document (by the /replace-ed-uris.js script). (Note that this step is very specific to this repository, and may not be relevant for others.)
  2. Create a new subdirectory in /publishing-snapshot, say, publishing-snapshot/WD-syntax-2014-12-12.
  3. Copy all the auxiliary files (e.g., data files, BNF files, images, etc.) from the main repo area. Note that not all the files may be necessary for final publications; e.g., the diagrams may have a .key and/or .pdf versions that are used in the process of creating the diagrams, but only the .svg and .png files are used in the final document.
  4. (Before you forget:-) add an entry to the new directory in /index.html on the top of the repository
  5. Generate the pure HTML file:
    1. Finalize/change the index.html file in /syntax
    2. Commit all the files to github
    3. From your Web browser, use the following URI: http://w3c.github.io/csvw/syntax/index.html?specStatus=WD;publishDate=2014-12-12 (note the URI parameters to set the specStatus and publishDate values!). You should see the final format on your screen.
    4. Check whether respec signals a possible problem (a red or orange button should appear on the upper right hand corner for errors or warnings, respectively).
    5. Push the button called respec on the upper right hand corner, choose Save Snapshot, then Save as HTML. You should either see the HTML source in your screen (e.g., in Safari or IE) or asked to download the HTML file on your disk.
    6. Create/update a file called Overview.html file in the snapshot directory, and commit it to github
      1. If you are in the main (i.e., gh-pages) branch, http://w3c.github.io/csvw/publishing-snapshots/WD-syntax-2014-12-12/Overview.html is a copy of the publication-to-be in pure HTML.
      • If you're working in an alternative branch, the content will not be available at http://w3c.github.io/[...]. Instead, use the service at https://rawgit.com/—paste the URL of the raw file into the RawGit page, and you can use the content at the "development" URL https://rawgit.com/w3c/csvw/my-branch/publishing-snapshots/WD-syntax-2014-12-12/Overview.html.
    7. Use the W3C pub rules checker with this URI to check the validity of the document. If there are problems, go back to the first step.
    8. Use the W3C link checker with this URI to check the links in the document (there is a link to the checker from the result generated by the pub rules checker). If there are problems, go back to the first step.
  6. Generate diff from previous version:
    1. Push the button called respec on the upper right hand corner, choose Save Snapshot then Diff,
    2. Save diff to publication directory using path set in otherLinks/Changes/Diff to previous version/href.
  7. Update working version of file, preferably when the publication is done:
    1. Set otherLinks/Changes/Diff previous version/href based on last publication date (in case the choice is to include a date in the diff file’s name)
    2. Update previousPublishDate, previousSpecStatus and previousURI based on the publication snapshot.
  8. Once all pubrules issues are solved, you are ready. The next step is for the staff contact to make a copy of the snapshot and push it on the W3C server at http://www.w3.org/TR/2014/...

The process may become slightly simpler if you run a local Web server on your machine that has an access to the local github repository. Indeed, in that case, step 5.2. can be omitted, i.e., the Overview.html file can be generated locally. Alternatively, you may choose to make a local copy of index.html and open the file from your browser locally. The danger, in this case, is to loose sync with the "master" copy, but if you are sure you have that under control, then this is probably the simplest approach. (Note, however, that you still have to push the new version to github to let the W3C rule checkers do their work…)

This process is based on the assumption that index.html (i.e., respec format) differs from the final document only in terms of the specification status and date (or other configuration option that can be set in the URI). If that is not the case, then a local copy of the file has to be added to the snapshot and be manipulated in that directory; of course, in that case the simplest is to set the specStatus and other options in that copy. Again, the danger of course is to loose sync with the "master" copy.