This repository has been archived by the owner on Jan 25, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
303 lines (303 loc) · 16.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
<!DOCTYPE html>
<html lang='en-GB'>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Vernacular — HTML Made Special</title>
<link rel="stylesheet" href="vernacular.css">
</head>
<body>
<header>
<h1>Vernacular</h1>
<p class="subtitle">
HTML Made Special
</p>
</header>
<nav>
<ul>
<li><a href="#what">What?</a></li>
<li><a href="#why">Why?</a></li>
<li><a href="#how">How?</a></li>
<li><a href="#where">Where?</a></li>
<li><a href="#huh">Huh?</a></li>
</ul>
</nav>
<section id="what">
<h2>What is Vernacular HTML?</h2>
<p>
HTML is one of the most widespread and interoperable data formats available. It is extremely
versatile and flexible, and if you have access to a computer, you have a access to a browser
with which to run it. Combined with JavaScript, CSS, SVG, and the rest of the Web platform,
it can be used as a very powerful format for all aspects of digital publishing.
</p>
<p>
This generality comes at a cost, however. When your goal is the interchange of specialised
information within a given domain, the full generality of HTML can get in the way. Your
applications should not have to sift through some vague information soup in order to extract
the data that they require, and equally they need an obvious way of encoding their data in
such a way that other applications will reliably understand it.
</p>
<p>
That is the traditional purview of domain-specific data formats. These are often relatively
simple (at least compared to the fullness of HTML) data formats, typically encoded in XML or
JSON, with predictable rules that (one hopes) enable the interoperable interchange of
information.
</p>
<p>
Domain-specific data formats are, however, not a panacea. They require conversion to an
output format (usually HTML, sometimes PDF) in order to be consumed, which is often a lossy
operation. This can make it harder to users to interact with them; it also means that
round-tripping them to and from user-friendly formats is an error-prone process. Not being
directly published on the Web, their content tends to be less discoverable.
</p>
<p>
“<dfn id="vernacular-html">Vernacular HTML</dfn>” is the growing practice of creating
domain-specific data formats using the HTML platform. Its goal is to enable interoperable,
specialised data interchange while retaining as much of HTML’s full power as is sensible
for the given domain. It is not a technology so much as an incipient body of good practices.
</p>
<!--
- example?
-->
</section>
<section id="why">
<h2>Why bother talking about Vernacular HTML?</h2>
<p>
Bodies of good practices are suspicious things. Why not <em>do and advocate through
example</em> rather than talk about doing? In some cases, though, it is worth sitting down and
writing up a few tips and tricks acquired through experience that might not be immediately
obvious from just looking at what others are doing.
</p>
<p>
HTML already has several extensibility mechanisms, ranging from well-known ones such as
<code>class</code> and <code>data-*</code> to less obvious parts like <code>rel</code>. It
also has (sadly, several) ways of overlaying additional semantics atop its markup:
<a href="https://html.spec.whatwg.org/multipage/microdata.html#microdata">Microdata</a>,
<a href="http://www.w3.org/TR/rdfa-primer/">RDFa</a>, and <a
href="http://microformats.org/">Microformats</a>. Its elements and attributes can at times
have non-obvious meanings, a fact made worse by the occasionally cryptic language in which
they are described in the specification. Additionally, HTML’s processing rules make it
possible to mint your own elements and attributes and expect a reliable DOM to come out at
the other end. With all of these options it is no surprise that people could find creating
their own vernacular daunting.
</p>
<p>
The HTML specification does contain some notes about how to use this or that extensibility
feature, but it is worth noting that standard authors can at times suffer from
self-important notions of right and wrong. Not that their advice should be ignored
wholesale, but it needs to be appraised through the sieve of your detailed knowledge of the
specific problem you are solving.
</p>
<p>
Our approach here is of a decidedly pragmatic bent. We simply wish to exchange good ideas
and good examples; never-ending debates about the significance of semantic meaning are very
much out of scope.
</p>
</section>
<section id="how">
<h2>How do I build a Vernacular?</h2>
<aside class="note">
<p>
This document is at an early stage, and much of the content has been cobbled together with
insufficient overall integrity and care. It is released early in the interest of gathering
feedback, but much work is needed. Several
<a href="https://github.com/scienceai/vernacular.io/issues">issues</a> are open on the
content, and it won’t be at an acceptable level under they are resolved. This is
particularly true of issues
<a href="https://github.com/scienceai/vernacular.io/issues/4">#4</a> and
<a href="https://github.com/scienceai/vernacular.io/issues/9">#9</a>, and to a lesser
extent of issues
<a href="https://github.com/scienceai/vernacular.io/issues/1">#1</a>,
<a href="https://github.com/scienceai/vernacular.io/issues/2">#2</a>, and
<a href="https://github.com/scienceai/vernacular.io/issues/3">#3</a>.
</p>
<p>
If you’re
interested in this project, come join
<a href="https://github.com/scienceai/vernacular.io/">the party on GitHub</a>
or talk to either <a href="https://twitter.com/sciencedotai">@sciencedotai</a> or
<a href="https://twitter.com/robinberjon">@robinberjon</a> in Twitter.
</p>
</aside>
<p>
Much of the time, if you sit down and start typing out examples, you will quickly get a good
feel for the kind of markup you want for your specific use case. Modulo some syntactical
variation, the overall shape of it is likely to be obvious. What may not be so obvious are
the bits that can trip you farther down the line. As a result, many of the practices listed
here are actually <em>bad practices</em>, thing you should <em>probably not</em> be doing.
I say “probably” because the philosophy at play here is that, ultimately, you know what
you’re doing (if not, no amount of advice will save you). You should have no qualms about
ignoring a red flag found here; all we’re saying is that it is likely a good idea to think
about it.
</p>
<p>
The guidelines below commonly make use of examples drawn from XML vocabularies. That is
because the problems one is likely to encounter in the creation XML and HTML languages have
a fair amount of overlap, and the XML examples tend to be more outrageously wrong. Don’t let
that lead you to thinking that using HTML makes you safe from such mistakes — if the problem
is listed here, someone smart has hit that problem before.
</p>
<dl>
<dt>Language Design</dt>
<dd>
<ul>
<li><a href="ignore/index.html">Ignore What You Don’t Need to Enforce</a></li>
<li><a href="errors/index.html">Error Handling</a></li>
<li><a href="data-star/index.html">Using <code>data-*</code> Attributes</a></li>
<li><a href="class/index.html">Using <code>class</code> Attributes</a></li>
<li><a href="text-attributes/index.html">Human-Readable Text in Attributes</a></li>
<li><a href="markup-as-text/index.html">Markup as Text</a></li>
<li><a href="microparsing/index.html">Excessive Microparsing</a></li>
<li><a href="no-versioning/index.html">No Versioning Strategy</a></li>
</ul>
</dd>
<dt>Wishful Thinking and Doe-Eyed Beliefs</dt>
<dd>
<ul>
<li><a href="naive/index.html">Naïve Versioning</a></li>
<li><a href="validation/index.html">Validation Will Save Us</a></li>
</ul>
</dd>
<dt>It’s for Humans</dt>
<dd>
<ul>
<li><a href="default/index.html">Default Values</a></li>
<li><a href="unreadable/index.html">Unreadable Names</a></li>
<li><a href="data-model/index.html">Don’t Dump Your Data Model</a></li>
<li><a href="naming-context/index.html">Naming Without Context</a></li>
<li><a href="consistency/index.html">Inconsistency</a></li>
</ul>
</dd>
<dt>RDFa/Microdata Problems</dt>
<dd>
<ul>
<li><a href="memorise/index.html">Hard to Memorise URLs</a></li>
<li><a href="reinventing/index.html">Reinventing the Wheel</a></li>
<li><a href="too-many/index.html">Too Many Vocabularies</a></li>
</ul>
</dd>
</dl>
</section>
<section id="where">
<h2>Where can I find some Vernacular HTML?</h2>
<p>
Vernacular HTML is a practice that existed long before it was given a name — as well it
should be! Here is a short list of some examples (with varying qualities of documentation).
If you wish to expand it, please simply
<a href="https://github.com/scienceai/vernacular.io/">file a pull request</a>.
</p>
<dl>
<dt><a href="https://www.ampproject.org/">AMP</a></dt>
<dd>
AMP (Accelerated Mobile Pages) is a project that defines a subset of HTML (with a number
of extensions) that enables increased performance in HTML delivery by getting rid of many
of the causes of slowness.
</dd>
<dt><a href="https://github.com/oreillymedia/HTMLBook">HTMLBook</a></dt>
<dd>
A vernacular to write books in HTML, in extensive use at O'Reilly.
</dd>
<dt><a href="http://www.w3.org/2005/07/pubrules?uimode=filter&uri=">W3C Publication
Rules (“pubrules”)</a></dt>
<dd>
Web standards are relatively formal affairs, and as such have their own formalised HTML
vernacular in which they are expressed. It is a fairly old vernacular (created circa 1997)
which, in terms of best practices, can sometimes show. It has nevertheless become
instantly recognisable in the Web technology world, and certainly benefits from great
simplicity (as can be seen in its
<a href="http://www.w3.org/StyleSheets/TR/W3C-WD.css">style sheet</a>).
</dd>
<dt><a href="https://www.w3.org/respec/">ReSpec</a> and
<a href="https://github.com/tabatkins/bikeshed#documentation-sections">Bikeshed</a></dt>
<dd>
Since W3C “pubrules” markup can prove repetitive and at times hard to get right, many
tools have been developed to assist people in producing it — these are the two main ones.
ReSpec documents are essentially valid HTML with some extra configuration that a JS
library turns into the real thing; Bikeshed is a Python preprocessor that can apply to
HTML but is more often used in Markdown mode (and therefore not completely a candidate for
this list).
</dd>
<dt><a href="https://angularjs.org/">AngularJS</a></dt>
<dd>
The AngularJS project sports a wealth of addition to HTML (which can take the form of new
elements, new attributes, <code>data-ng-*</code> attributes, and a few other options) to
add interactivity to HTML.
</dd>
<dt><a href="http://scholarly.vernacular.io/">Scholarly HTML</a></dt>
<dd>
Scholarly HTML is a set of constraints on HTML meant to enable the interchange of
scientific articles. (Disclaimer: it is done by the same people who are doing this.)
</dd>
<dt><a href="https://github.com/substack/html-version-spec">html-version-spec</a></dt>
<dd>
The purpose of html-version, from the ineffable
<a href="http://substack.net/">substack</a>, is “to make the Web more distributed,
permanent, and robust against outages, censorship, and orphaned content”. It does so
through specific application of <code>link</code> and <code>meta</code> values.
</dd>
</dl>
</section>
<section id="huh">
<h2>Any Other Question?</h2>
<dl>
<dt>This is great! How do I contribute or point out a bug?</dt>
<dd>
It’s all on <a href="https://github.com/scienceai/vernacular.io/">GitHub</a>. Feel free to
make a pull request or to <a href="https://github.com/scienceai/vernacular.io/issues">file
an issue</a>! We are completely open to new advice, or to discussing the validity of some
of the practices described here.
</dd>
<dt>Do I need to produce a validator for my vernacular?</dt>
<dd>
As always, it depends on the usage context. In general it should not be considered a
high-priority requirement — describing clear processing rules through which content can
be reliably and robustly extracted from your vernacular is far more important. However, in
a complex production chain, especially one involving multiple parties, validation can be a
life saver. There are no special rules for HTML vernaculars: the same common sense that
applies to other data formats is just as valid here.
</dd>
<dt>How do I create a validator if I need one?</dt>
<dd>
One approach can be to produce a modified version of the
<a href="https://validator.nu/">VNU</a> validator, but it is not a lightweight undertaking
and it involves Java. We are considering working on a validation framework architected
in a manner similar to <a href="https://github.com/w3c/specberus">Specberus</a>, to make
it easier for people to write their own validation tooling with. Let us know if that’s
something you’re interested in!
</dd>
<dt>You sometimes seem to interpret standards in a flexible manner, is that not bad?</dt>
<dd>
No. Standard texts have several levels of conformance. When dealing with normative rules
(the “MUST” ones) it is generally a really good idea not to fool around. Breaking those
leads to interoperability problems, and either you or your users will get bitten for that.
If, however, we are considering advice from specifications (the “SHOULD” bits) then there
is room for context. The idea is that you ought to understand the why behind the statement
and not take it as a strict mandate. Once you understand the reasoning, you should have a
fairly good idea of when to stick to it and when to break it. Unfortunately, this type of
informative recommendation is often just stated, almost as a command, with no explanation
as to the problems it is expected to protect you from. That’s when a little bit of
creative thinking might be necessary.
</dd>
<dt>I have another question, where do I ask it?</dt>
<dd>
You can <a href="https://github.com/scienceai/vernacular.io/issues">file an issue</a>, or
you can ping <a href="https://twitter.com/sciencedotai">@sciencedotai</a> or
<a href="https://twitter.com/robinberjon">@robinberjon</a> on Twitter.
</dd>
</dl>
</section>
<footer>
<p>
<a href="http://creativecommons.org/licenses/by/4.0/">CC-BY</a>
<a href="https://twitter.com/sciencedotai">@sciencedotai</a>
•
Contributors:
<a href="https://twitter.com/robinberjon">@robinberjon</a>
•
Brought to you by the
<a href="http://science.ai/"><img src="sciencedotai.svg" alt="science.ai logo" height="20px"></a>
League of JStice
</p>
</footer>
</body>
</html>