Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

A proposal to make algorithms easier to read using foldable sections. #132

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

A proposal to make algorithms easier to read using foldable sections. #132

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
caa815e
A proposal to make algotithms easier to read using foldable sections.
pchampin Aug 8, 2019
b21884c
replaced CSS hack by JS solution
pchampin Aug 8, 2019
07f2713
added intro section with buttons to fold/unfold all
pchampin Sep 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 104 additions & 17 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,80 @@
text-decoration: none;
color: #666;
}

.algorithm summary::before {
content: "// ";
}

.algorithm summary {
padding-left: 2em;
font-style: italic;
}
</style>
<script>
// functions related to foldable algorithm parts

(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");
}

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");
}

// using matchMedia
window.matchMedia('print').addListener(function (mql) {
if (mql.matches) {
beforePrint();
} else {
afterPrint();
}
});
// 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>

<body>
Expand Down Expand Up @@ -343,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">
Expand Down Expand Up @@ -1073,7 +1160,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>:
<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>
Expand All @@ -1086,10 +1173,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></details>
</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>
Expand Down Expand Up @@ -1129,14 +1216,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>
Expand All @@ -1146,10 +1233,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>
Expand Down Expand Up @@ -1191,11 +1278,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
Expand All @@ -1210,10 +1297,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
Expand All @@ -1234,10 +1321,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
Expand All @@ -1247,10 +1334,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>
Expand All @@ -1259,7 +1346,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
Expand Down