Merged branch improve-respec-magic into gh-pages

w3c · Sep 10, 2016 · bd568c1 · bd568c1
2 parents 3c73f32 + d648159
commit bd568c1
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 67 deletions.
diff --git a/index.html b/index.html
@@ -8,7 +8,7 @@
     <link rel="stylesheet" href="extras.css">
     <script class='remove'>
       var respecConfig = {
-          preProcess : [collectreqs, fullreqref, listreq],
+          // preProcess : [ fullreqref],
           specStatus: "ED",
           shortName:  "pwp-ucr",
           editors: [

diff --git a/scripts/reqscollect.js b/scripts/reqscollect.js
@@ -1,20 +1,65 @@
 /**
 * Collect and display data on requirements, ie, the data provided by respec for each element with class "req".
 *
-* For each requirement, the collected data include:
-*	number: the number of the requirement (generated in document order)
-*   content: the HTML content of the original element
-*   title: the title provided by respec for this requirement (e.g., "Req. 1: ")
-*   id: the @id value of the element, to be used to generate hyperlinks.
+* Handling 'requirements'. This is slightly different than respec's own "req" class, which did not cut it for my needs.
 *
-* If the respec file is used with a URI ending with "#saveReqs", a popup will come at the end
-* offering to store the requirement data in a (js) file.
-* That can be reused in the receiving end.
+* For the users, the following are available
 *
-* The code for the popup was shameless borrowed (with his permission:-) from Shane McCarron
+* 1. A requirement can be set via
+*
+*   <element class=req" id="rid">Some requirement</element>
+*
+* Where 'element' can be a <p>, a <span>...
+*
+* Effect: the element will be prepended by "Req. X", where X is the number of the requirement, assigning a number
+* in document order. (This is an undocumented respec feature.)
+*
+* 2. A simple reference to a requirement looks as follows:
+*
+*   <a class="reqRef" href='#rid'></a>
+*
+* Effect: the <a> element becomes <a href='#rid'>Req. X</a> where 'X' is refers to the number of the requirement.
+* (This is also an undocumented respect feature)
+*
+* 3. A full reference to requirement looks as follows:
+*
+*   <a class="fullReqRef" href="#rid"></a>
+*
+* Effect: the <a> element becomes a <a href='#rid'>Req.X: Some requirement</a>.
+* (Minor note: if the original requirement text finishes with a full stop, that character is removed.
+* This makes it easier to include the reference within a paragraph)
+*
+* 4. A table of the form:
+*
+* <table id="reqtable">
+* </table>
+*
+* Will be expanded with rows; each row has two cells, the first being <a href='#rid'>Req. X</a>, the second the description
+* (ie, the "Some requirement" text in this example).
+*
+* 5. If the URI of the respec includes the "#saveReqs" fragment ID, a popup dialogue will offer to store the list of
+* requirements in a separate js file. The file is of the form:
+*
+* var reqInfo = [
+*	{
+*		"number": 1,
+*		"content": "The publication should be readable in a browser",
+*		"title": "Req. 1",
+*		"id": "r_browser"
+*	},
+*	{
+*		"number": 2,
+*		"content": "PWPs should be able to make use of all facilities offered by the OWP",
+*		"title": "Req. 2",
+*		"id": "r_owp"
+*	},
+*
+* this can be used by other documents to refer to the requirements' list
+*
+*
+* The code for the popup was shamelessly stolen (with his permission:-) from Shane McCarron
 *
 * To use it
-*   - add the preProcess : [collectreqs] to the respec config.
 *   - add <script src="scripts/reqscollect.js" class="remove"></script> after the reference to respec
 *   - make sure that the reference to respec does not have the 'async' attribute (it does not seem to work if that is the case:-(
 *
@@ -23,73 +68,61 @@
 /* jshint shadow: true, unused: false, laxbreak:true, laxcomma:true, asi: true, eqeqeq: false, strict: implied, jquery: true */
 /* global $, require */
 
-
 var reqInfo =  [
 ];
 
-// Collect the requirements' data
-function collectreqs() {
-	$(".req").each(function (i) {
-		i++;
-		var $req = $(this)
-		,   title = "Req. " + i
-		,   content = $req.html()
-		;
-		if( content.charAt(content.length-1) === '.' ) {
-			content = content.slice(0,-1);
-		}
-		reqInfo.push({
-			number: i,
-			content: content,
-			title: title,
-			id: $req.attr("id")
+require(["core/pubsubhub"], function(respecEvents) {
+	respecEvents.sub("start-all", function() {
+		// Collect the necessary information on the various requirement entries right at the start...
+		$(".req").each(function (i) {
+			i++;
+			var $req = $(this)
+			,   title = "Req. " + i
+			,   content = $req.html()
+			;
+			if( content.charAt(content.length-1) === '.' ) {
+				content = content.slice(0,-1);
+			}
+			reqInfo.push({
+				number: i,
+				content: content,
+				title: title,
+				id: $req.attr("id")
+			});
 		});
-	});
-}
 
-// This is alternative to respec's very own manipulation of the "a" element for a requirement; while
-// that only display the 'title', ie, "Req. 3", this version, relying on the "fullReqRef" class, displays
-// the full requirement instead.
-function fullreqref() {
-	// alert(JSON.stringify(reqInfo, null, '\t'))
-	$("a.fullReqRef").each(function(i) {
-		var id = $(this).attr("href");
-		var $ref = $(this);
-		reqInfo.forEach( function(element, index, array) {
-			if( ('#' + element.id) === id ) {
-				// alert("Bingo " + id)
-				// alert(element.title + ": " + element.content)
-				$ref.text(element.title + ": " + element.content);
-			}
+		$("a.fullReqRef").each(function(i) {
+			var id = $(this).attr("href");
+			var $ref = $(this);
+			reqInfo.forEach( function(element, index, array) {
+				if( ('#' + element.id) === id ) {
+					$ref.text(element.title + ": " + element.content);
+				}
+			});
 		});
-	});
-}
 
-// List of all requirements, one per table row
-function listreq() {
-	$("#reqtable").each( function(i) {
-		var $table = $(this);
-		reqInfo.forEach( function(element, index, array) {
-			// Add a new table row to the table itself
-			var $row = $("<tr></tr>");
-			$table.append($row);
+		// Generate the table of requirements
+		$("#reqtable").each( function(i) {
+			var $table = $(this);
+			reqInfo.forEach( function(element, index, array) {
+				// Add a new table row to the table itself
+				var $row = $("<tr></tr>");
+				$table.append($row);
 
-			cellref = $("<td></td>");
-			$row.append(cellref)
-			reqref = $("<a></a>");
-			cellref.append(reqref);
-			reqref.attr("href","#" + element.id);
-			reqref.text(element.title)
+				cellref = $("<td></td>");
+				$row.append(cellref)
+				reqref = $("<a></a>");
+				cellref.append(reqref);
+				reqref.attr("href","#" + element.id);
+				reqref.text(element.title)
 
-			celltitle = $("<td></td>");
-			$row.append(celltitle);
-			celltitle.text(element.content);
+				celltitle = $("<td></td>");
+				$row.append(celltitle);
+				celltitle.text(element.content);
+			})
 		})
-	})
-}
-
+	});
 
-require(["core/pubsubhub"], function(respecEvents) {
 	respecEvents.sub("end-all", function() {
 		//alert("asdfas")
         var m = document.URL;