Skip to content

Commit

Permalink
Add line wraps
Browse files Browse the repository at this point in the history
anatoly-scherbakov committed Jul 5, 2022
1 parent 966ecf7 commit c760eea
Showing 1 changed file with 30 additions and 12 deletions.
42 changes: 30 additions & 12 deletions spec/index.html
Original file line number Diff line number Diff line change
@@ -443,12 +443,14 @@ <h3>Examples</h3>
<section id="best-practices" class="informative">
<h2>Best Practices</h2>

<p>Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two useful thoughts.</p>
<p>Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two
useful thoughts.</p>

<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 of YAML-LD aware
systems. The [[json-ld-bp]] document is relevant to YAML-LD no less than it is to [[JSON-LD]].
</p>
</div>

@@ -460,17 +462,23 @@ <h2>Best Practices</h2>
</p>
</div>

<p>YAML-LD is intended to simplify 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 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>
<p>YAML-LD is intended to simplify 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
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>

<div class="practice">
<p class="practicedesc">
<span id="conceal-contexts" class="practicelab">Use a default context</span>
</p>

If most, or all, of a user's documents are based on one particular context, try to make it the default in order to rescue the user from copy-pasting the same technical incantation from one document to another.
If most, or all, of a user's documents are based on one particular context, try to make it the default in order
to rescue the user from copy-pasting the same technical incantation from one document to another.
</div>

<p>For instance, according to [[json-ld-api]], the `expand()` method of a JSON-LD processor accepts an `expandContext` argument which can be used to provide a default system context.</p>
<p>For instance, according to [[json-ld-api]], the `expand()` method of a JSON-LD processor accepts an
`expandContext` argument which can be used to provide a default system context.</p>

<div class="practice">
<p class="practicedesc">
@@ -480,33 +488,43 @@ <h2>Best Practices</h2>
</p>
</div>

<p>The `@` character is reserved as per [[YAML]] specification and thus requires quoting, as in the following example:</p>
<p>The `@` character is reserved as per [[YAML]] specification and thus requires quoting, as in the following
example:</p>

<aside class="example" data-transform="updateExample"
title="Example YAML-LD document without Convenience Context">
<pre class="yaml" data-include="code/without-convenience-context.yaml" data-include-format="text"></pre>
</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>
<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>

<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 no more difficult to remember.</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
no more difficult to remember.</p>

<div class="practice">
<p class="practicedesc">
<span id="convenience-context" class="practicelab">Use YAML-LD Convenience Context</span>
<p>YAML-LD users may use a JSON-LD context provided as part of this specification, henceforth known as the <dfn>convenience
context</dfn>, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`.</p>
<p>YAML-LD users may use a JSON-LD context provided as part of this specification, henceforth known as the
<dfn>convenience
context</dfn>, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`.
</p>
</p>
</div>

<aside class="example" data-transform="updateExample" title="Convenience Context">
<p>Code of the <a>convenience context</a>. Available as: <a href="https://yaml-ld.dev/context">https://yaml-ld.dev/context</a>.
<p>Code of the <a>convenience context</a>. Available as:
<a href="https://yaml-ld.dev/context">https://yaml-ld.dev/context</a>.
</p>
<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 replaced by `$`, which is not reserved and therefore does not require quoting. Consider <strong>Example 1</strong> reformatted using the convenience context:</p>
specification, — 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>

<aside class="example" data-transform="updateExample" title="Example YAML-LD document with Convenience Context">
<pre class="yaml" data-include="code/with-convenience-context.yaml" data-include-format="text"></pre>

0 comments on commit c760eea

Please sign in to comment.