From 0584ea612f24f7efac059b3859546bfdede81dca Mon Sep 17 00:00:00 2001 From: Gregg Kellogg <gregg@greggkellogg.net> Date: Wed, 6 Jul 2022 14:02:31 -0700 Subject: [PATCH] Apply suggestions from code review of @TallTed Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com> --- spec/index.html | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/spec/index.html b/spec/index.html index 74c842e..a98c556 100644 --- a/spec/index.html +++ b/spec/index.html @@ -449,8 +449,8 @@ <h2>Best Practices</h2> <div class="practice"> <p class="practicedesc"> <span id="use-json-ld-best-practices" class="practicelab">Follow JSON-LD best practices</span> - …in order to achieve a greater level of reusability, performance, and human friendliness of YAML-LD aware - systems. The [[json-ld-bp]] document is relevant to YAML-LD no less than it is to [[JSON-LD]]. + …in order to achieve a greater level of reusability, performance, and human friendliness among YAML-LD aware + systems. The [[json-ld-bp]] document is as relevant to YAML-LD as it is to [[JSON-LD]]. </p> </div> @@ -458,15 +458,15 @@ <h2>Best Practices</h2> <p class="practicedesc"> <span id="prebuilt-contexts" class="practicelab">Do not force users to author contexts</span> - Instead, provide pre-built contexts that the user can reference by URL for majority of common use cases. + Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases. </p> </div> - <p>YAML-LD is intended to simplify authoring of Linked Data for a wide range of domain experts: its target + <p>YAML-LD is intended to simplify the authoring of Linked Data for a wide range of domain experts; its target audience is not comprised solely of IT professionals. YAML is chosen as a medium to minimize syntactic noise, - to keep the authored documents concise and clear. [[JSON-LD]] (and hence YAML-LD) Context comprises a special + and to keep the authored documents concise and clear. [[JSON-LD]] (and hence YAML-LD) Context comprises a special language of its own. A requirement to <i>author</i> such a context would make the domain expert's job much - harder, — which we, as system architects and developers, should try to avoid.</p> + harder — which we, as system architects and developers, should try to avoid.</p> <div class="practice"> <p class="practicedesc"> @@ -488,7 +488,7 @@ <h2>Best Practices</h2> </p> </div> - <p>The `@` character is reserved as per [[YAML]] specification and thus requires quoting, as in the following + <p>The `@` character is reserved in [[YAML]], and thus requires quoting (or escaping), as in the following example:</p> <aside class="example" data-transform="updateExample" @@ -497,8 +497,8 @@ <h2>Best Practices</h2> </aside> <p>The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document - author's life. Besides, on most keyboard layouts typing quotes will require `Shift` — which albeit slightly but - does reduce typing speed.</p> + author's life. Further, on most keyboard layouts, typing quotes will require `Shift`, which reduces typing speed, + albeit slightly.</p> <p>In order to avoid this, the context might introduce custom mappings for the necessary keywords. For instance, [[schema-org]] context redefines `@id` as just `id` — which seems to be much more convenient to type, and @@ -521,8 +521,8 @@ <h2>Best Practices</h2> <pre class="json" data-include="code/context.json" data-include-format="text"></pre> </aside> - <p>The convenience context contains an alias to every JSON-LD keyword which can be aliased as per JSON-LD 1.1 - specification, — which means all the keywords except <code>@context</code>. The reserved `@` character is + <p>The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 + specification permits aliasing — which means all the keywords except <code>@context</code>. The reserved `@` character is replaced by `$`, which is not reserved and therefore does not require quoting. Consider <strong>Example 1</strong> reformatted using the convenience context:</p>