From caa815ef3c1dbab9a8c745569e64fea3791f10e9 Mon Sep 17 00:00:00 2001
From: Pierre-Antoine Champin <pchampin@liris.cnrs.fr>
Date: Thu, 8 Aug 2019 12:51:35 +0200
Subject: [PATCH 1/3] A proposal to make algotithms easier to read using
foldable sections.
---
index.html | 51 +++++++++++++++++++++++++++++++++++----------------
1 file changed, 35 insertions(+), 16 deletions(-)
diff --git a/index.html b/index.html
index 42d3995e..d863db90 100644
--- a/index.html
+++ b/index.html
@@ -264,6 +264,24 @@
text-decoration: none;
color: #666;
}
+
+ .algorithm summary::before {
+ content: "// ";
+ }
+
+ .algorithm summary {
+ padding-left: 2em;
+ font-style: italic;
+ }
+
+ /* required if we chose to put OLs *outside* the details,
+ to force them visible when printing */
+ @media screen {
+ .algorithm details:not([open]) + ol {
+ display: none;
+ }
+ }
+
</style>
</head>
@@ -1073,6 +1091,7 @@ <h3>Algorithm</h3>
For each item <var>context</var> in <var>local context</var>:
<ol>
<li>If <var>context</var> is <code>null</code>:
+ <details><summary>clear context (unless protected)</summary></details>
<ol>
<li class="changed">If <var>override protected</var> is <code>false</code> and <var>active context</var>
contains any <a>protected</a> <a>term definitions</a>,
@@ -1086,10 +1105,10 @@ <h3>Algorithm</h3>
<span class="note">In [[[JSON-LD]]], the <a>base IRI</a> was given
a default value here; this is now described conditionally
in <a href="#the-application-programming-interface" class="sectionRef"></a>.</span></li>
- </ol>
+ </ol>
</li>
- <li>If <var>context</var> is a <a>string</a>,
- <ol>
+ <li>If <var>context</var> is a <a>string</a>:
+ <details><summary>dereference and process</summary><ol>
<li>Set <var>context</var> to the result of resolving <var>value</var> against
the base IRI which is established as specified in
<a data-cite="RFC3986#section-5.1">section 5.1 Establishing a Base URI</a>
@@ -1129,14 +1148,14 @@ <h3>Algorithm</h3>
passing <var>result</var> for <var>active context</var>,
<var>context</var> for <var>local context</var>, and <span class="changed">a copy of</span> <var>remote contexts</var>.</li>
<li>Continue with the next <var>context</var>.</li>
- </ol>
+ </ol></details>
</li>
<li>If <var>context</var> is not a <a class="changed">map</a>, an
<a data-link-for="JsonLdErrorCode">invalid local context</a>
error has been detected and processing is aborted.</li>
<li>Otherwise, <var>context</var> is a <a data-cite="JSON-LD11#dfn-context-definition">context definition</a>.</li>
<li class="changed">If <var>context</var> has an <code>@version</code> <a>entry</a>:
- <ol>
+ <details><summary>set processing mode</summary><ol>
<li>If the associated value is not <code>1.1</code>,
an <a data-link-for="JsonLdErrorCode">invalid @version value</a>
has been detected, and processing is aborted.</li>
@@ -1146,10 +1165,10 @@ <h3>Algorithm</h3>
error has been detected and processing is aborted.</li>
<li>Set <a>processing mode</a>,
to <code>json-ld-1.1</code>, if not already set.</li>
- </ol>
+ </ol></details>
</li>
<li class="changed">If <var>context</var> has an <code>@import</code> <a>entry</a>:
- <ol>
+ <details><summary>merge imported context</summary><ol>
<li>If <a>processing mode</a> is <code>json-ld-1.0</code>,
an <a data-link-for="JsonLdErrorCode">invalid context entry</a>
error has been detected and processing is aborted.</li>
@@ -1191,11 +1210,11 @@ <h3>Algorithm</h3>
<li>Set <var>context</var> to the result of merging <var>context</var>
into <var>import context</var>, replacing common entries
with those from <var>context</var>.</li>
- </ol>
+ </ol></details>
</li>
<li>If <var>context</var> has an <code>@base</code> <a>entry</a> and <var>remote contexts</var> is empty, i.e., the currently
being processed context is not a remote context:
- <ol>
+ <details><summary>reset <a>base IRI</a></summary><ol>
<li>Initialize <var>value</var> to the value associated with the
<code>@base</code> <a>entry</a>.</li>
<li>If <var>value</var> is <code>null</code>, remove the
@@ -1210,10 +1229,10 @@ <h3>Algorithm</h3>
<li>Otherwise, an
<a data-link-for="JsonLdErrorCode">invalid base IRI</a>
error has been detected and processing is aborted.</li>
- </ol>
+ </ol></details>
</li>
<li>If <var>context</var> has an <code>@vocab</code> <a>entry</a>:
- <ol>
+ <details><summary>reset <a>vocabulary mapping</a></summary><ol>
<li>Initialize <var>value</var> to the value associated with the
<code>@vocab</code> <a>entry</a>.</li>
<li>If <var>value</var> is <a>null</a>, remove
@@ -1234,10 +1253,10 @@ <h3>Algorithm</h3>
error has been detected and processing is aborted.
<div class="note">The use of <a>blank node identifiers</a> to value for <code>@vocab</code> is obsolete,
and may be removed in a future version of JSON-LD.</div></li>
- </ol>
+ </ol></details>
</li>
<li>If <var>context</var> has an <code>@language</code> <a>entry</a>:
- <ol>
+ <details><summary>reset <a>default language</a></summary><ol>
<li>Initialize <var>value</var> to the value associated with the
<code>@language</code> <a>entry</a>.</li>
<li>If <var>value</var> is <code>null</code>, remove
@@ -1247,10 +1266,10 @@ <h3>Algorithm</h3>
lowercased <var>value</var>. If it is not a <a>string</a>, an
<a data-link-for="JsonLdErrorCode">invalid default language</a>
error has been detected and processing is aborted.</li>
- </ol>
+ </ol></details>
</li>
<li class="changed">If <var>context</var> has an <code>@propagate</code> <a>entry</a>:
- <ol>
+ <details><summary>check its validity</summary><ol>
<li>If <a>processing mode</a> is <code>json-ld-1.0</code>,
an <a data-link-for="JsonLdErrorCode">invalid context entry</a>
error has been detected and processing is aborted.</li>
@@ -1259,7 +1278,7 @@ <h3>Algorithm</h3>
error has been detected and processing is aborted.</li>
<li>Otherwise, <a>previous context</a> was determined before,
and no further processing is necessary.</li>
- </ol>
+ </ol></details>
</li>
<li>Create a <a class="changed">map</a> <var>defined</var> to keep
track of whether or not a <a>term</a> has already been defined
From b21884ccea68d1485995552740e2d2c0c3e4a316 Mon Sep 17 00:00:00 2001
From: Pierre-Antoine Champin <pchampin@liris.cnrs.fr>
Date: Thu, 8 Aug 2019 16:06:01 +0200
Subject: [PATCH 2/3] replaced CSS hack by JS solution
I tested it with Firefox 68.0.1 and Chromium 76.0.3809.87 on Linux.
---
index.html | 54 ++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 44 insertions(+), 10 deletions(-)
diff --git a/index.html b/index.html
index d863db90..c0af24f5 100644
--- a/index.html
+++ b/index.html
@@ -273,16 +273,51 @@
padding-left: 2em;
font-style: italic;
}
+</style>
+<script>
+ (function() {
+ function beforePrint() {
+ console.debug("opening details before printing");
+ var algoDetails = document.querySelectorAll('.algorithm details');
+ var c = 0;
+ for (var dt of algoDetails) {
+
+ if (!dt.open) {
+ dt.setAttribute("data-was-closed", "");
+ dt.open = true;
+ c += 1;
+ }
+ }
+ console.debug(c, "details opended before printing");
+ }
- /* required if we chose to put OLs *outside* the details,
- to force them visible when printing */
- @media screen {
- .algorithm details:not([open]) + ol {
- display: none;
+ function afterPrint() {
+ console.debug("closing details after printing");
+ var algoDetails = document.querySelectorAll('.algorithm details');
+ var c = 0;
+ for (var dt of algoDetails) {
+ if (dt.hasAttribute("data-was-closed")) {
+ dt.removeAttribute("data-was-closed");
+ dt.open = false;
+ c += 1;
+ }
+ }
+ console.debug(c, "details closed after printing");
}
- }
-</style>
+ // using matchMedia
+ window.matchMedia('print').addListener(function (mql) {
+ if (mql.matches) {
+ beforePrint();
+ } else {
+ afterPrint();
+ }
+ });
+ // using events
+ window.addEventListener('beforeprint', beforePrint);
+ window.addEventListener('afterprint', afterPrint);
+ })();
+</script>
</head>
<body>
@@ -1091,8 +1126,7 @@ <h3>Algorithm</h3>
For each item <var>context</var> in <var>local context</var>:
<ol>
<li>If <var>context</var> is <code>null</code>:
- <details><summary>clear context (unless protected)</summary></details>
- <ol>
+ <details><summary>clear context (unless protected)</summary><ol>
<li class="changed">If <var>override protected</var> is <code>false</code> and <var>active context</var>
contains any <a>protected</a> <a>term definitions</a>,
an <a data-link-for="JsonLdErrorCode">invalid context nullification</a>
@@ -1105,7 +1139,7 @@ <h3>Algorithm</h3>
<span class="note">In [[[JSON-LD]]], the <a>base IRI</a> was given
a default value here; this is now described conditionally
in <a href="#the-application-programming-interface" class="sectionRef"></a>.</span></li>
- </ol>
+ </ol></details>
</li>
<li>If <var>context</var> is a <a>string</a>:
<details><summary>dereference and process</summary><ol>
From 07f27133b9b8b5f0f6385c05f5b10c6890ff2276 Mon Sep 17 00:00:00 2001
From: Pierre-Antoine Champin <pchampin@liris.cnrs.fr>
Date: Mon, 2 Sep 2019 15:07:25 +0200
Subject: [PATCH 3/3] added intro section with buttons to fold/unfold all
---
index.html | 34 ++++++++++++++++++++++++++++++++++
1 file changed, 34 insertions(+)
diff --git a/index.html b/index.html
index c0af24f5..2de8e37e 100644
--- a/index.html
+++ b/index.html
@@ -275,6 +275,8 @@
}
</style>
<script>
+ // functions related to foldable algorithm parts
+
(function() {
function beforePrint() {
console.debug("opening details before printing");
@@ -316,6 +318,24 @@
// using events
window.addEventListener('beforeprint', beforePrint);
window.addEventListener('afterprint', afterPrint);
+ window.addEventListener('load', function() {
+ console.debug("coucou");
+ document.getElementById('fold-all-algorithms').addEventListener('click', function() {
+ var algoDetails = document.querySelectorAll('.algorithm details');
+ for (var dt of algoDetails) {
+ dt.open = false;
+ }
+ console.debug("fold");
+ });
+ document.getElementById('unfold-all-algorithms').addEventListener('click', function() {
+ var algoDetails = document.querySelectorAll('.algorithm details');
+ for (var dt of algoDetails) {
+ dt.open = true;
+ }
+ console.debug("unfold");
+ });
+ console.debug("coucou");
+ });
})();
</script>
</head>
@@ -396,6 +416,20 @@ <h2>Contributing</h2>
<section class="informative">
<h2>Typographical conventions</h2>
<div data-include="common/typographical-conventions.html"></div>
+
+ <section>
+ <h3>Summarized algorithm sections</h3>
+ <p>In order to make the algorithms easier to read,
+ some parts of them are initially hidden and replaced by a short summary.
+ Clicking on that summary will toggle between detailed and summarised view.
+ Using the buttons below, you can display or hide the details in all algorithms at once.
+ Note that, when printing, all details are always shown.
+ </p>
+ <p>
+ <button id="unfold-all-algorithms">Show all details in all algorithms</button>
+ <button id="fold-all-algorithms">Hide all details in all algorithms</button>
+ </p>
+ </section>
</section>
<section class="normative">