dokieli documentation dokieli 文档
- Identifier标识地址
- https://dokie.li/docs
- Published发布时间
- Modified修改时间
- License许可证
- CC BY 4.0
Abstract 摘要
This documentation is intended to help brave developers and authors. It explains dokieli's principles, architectural and design patterns.
本文档旨在帮助勇敢的开发人员和作者。它解释了dokieli的原则,架构和设计模式。
Document Status 文档状态
Living document.
活文档
Principles原则
Towards improving the write dimension of the read-write Web, dokieli's design subscribes to the following principles: freedom of expression, interoperability, decentralisation, evolvability, universal access, separation of concerns, █ + █ > = █ █
.
为了提高读-写网络的写入 dokieli 的设计提供了以下原则: 表达自由、互操作性、去中心化、可进化、普遍访问、关注分离, █ + █ > = █ █
。
Structure and Semantics结构和语义
This section describes dokieli's practices, and offers some guidelines for developers and authors that would like to maintain uniformity in what they create. Consumers of dokieli should not treat the information here as a profile, or as a yet another super or subset of HTML+RDFa when they author or build new functionality. Creating articles, annotations, and notifications in dokieli is intended to be done through its UI, where it takes care of majority of the semantic content generation. The information here however can be useful for authors that would like to combine hand coding with the functionality that dokieli's UI provides. Takeaway what you find useful, there is no proprietary lock-in here.
本节介绍 dokieli的实践, 并希望为在创建中保持一致性的开发人员和作者提供一些指导。dokieli 的使用者在创作或构建新的功能时不应该将这里的信息作为一个配置文件, 或者作为 HTML + RDFa 的另一个超级或子集。在 dokieli 中创建文章、注释和通知的目的是通过它的 UI 来完成, 它负责处理大部分语义内容生成。但是这里的信息对于希望将手工编码与 dokieli 的 UI 提供的功能结合起来的作者来说是有用的。将您发现有用的拿走,这里没有专利的枷锁锁。
dokieli adopts progressive enhancement strategy for the structural, presentational, and behavioural layers to allow content and base functionality to be accessible through different media and devices. The content in HTML+RDFa that dokieli produces is accessible (readable) without requiring any CSS or JavaScript, ie. text-browser safe. Breaking this "rule" in future development should be considered an anti-pattern (or a bug) in dokieli. dokieli 对结构、表述和行为层采用渐进式增强策略, 允许通过不同的媒体和设备访问内容和基本功能。dokieli 生成的 HTML + RDFa 中的内容是可以访问 (可读的), 而不需要任何 CSS 或 JavaScript。即文本浏览安全。打破这个 "规则" 在未来的dokieli开发中应被认为是反模式 (或错误)。
dokieli can serialise articles, annotations, and notifications in HTML+RDFa, Turtle, and JSON-LD, depending on server content-negotiation. Articles are represented in HTML+RDFa so that information is usable by both humans and machine consumers while maintaining lowest requirements for publishing, eg. a single URL with full payload in HTML+RDFa can be accessible from any HTTP server. No additional requirements necessary from clients (eg. JavaScript support and enabled) or servers (eg. additional RDF based content-negotiation). For annotations and notifications, dokieli first meets interoperability requirements (for protocols and vocabularies), and remains flexible about the serialisation that servers prefer. Similarly for consuming content, it can work with any of the serialisations as mentioned. dokieli 可以用HTML+RDFa、Turtle和 JSON-LD序列化文章、注释和通知, 具体取决于服务器内容协商。文章以 HTML+RDFa 的形式表示, 以便人类和机器消费者都能使用信息, 同时保持发布的最低要求。可以从任何 HTTP 服务器访问 HTML+RDFa 中具有完整有效负载的单个URL。对客户端(例如JavaScript 支持和启用) 或 服务器 (例如, 其他基于 RDF 的内容协商)来说不需要来额外要求。对于注释和通知, dokieli 首先满足互操作性要求 (针于协议和词汇表), 并且对服务器更喜欢的序列化保持灵活性。同样, 对于内容的使用, 它可以与前面提到的任何序列化形式一起使用。
dokieli takes the approach of having all human-visible content in HTML, and all structured statements be made in context of their content in RDFa. This is optimal in avoiding data duplication in the same document which happens to be the case with the other serialisations in RDF. The approach also helps to avoid the creation and usage of multiple data islands, ie. separately for humans and machines. It is efficient in that it has no dependency on JavaScript in order to make the hidden machine-readable content be consumable from a human user interface. One exception to this rule is allowing authors to use the Embed Data feature to include Turtle, JSON-LD, or TriG data blocks for alternative reasons. dokieli 采用HTML中所有人可见内容的方法, 所有结构化的语句都是在 RDFa 的内容的上下文中进行的。这样最好的避免了使用RDF进行序列化时在同一文件中的数据重复。该方法还有助于避免创建和使用多个数据孤岛,即将人和机器分开。因为它不依赖 JavaScript, 所以,为了使隐藏的机器可读的内容在人类用户界面的使用是有效的。此规则的一个例外是,因其它原因允许作者使用 "嵌入数据" 功能将Turtle、JSON-LD 或 TriG数据块包含在其中。
dokieli documentsdokieli 文档
Is there such thing as a "dokieli" document? Must there be?
有这样的“dokieli”文档吗?肯定有吗?
- Article文章
-
An article may contain RDF classes like schema:CreativeWork sioc:Post prov:Entity schema:Article, otherwise, there is no unique data that would indicate that it is a "dokieli" document. If the HTML+RDFa representation includes do.js and the DOM is ready, the
DO
:Object { C: {…}, U: {…} }
will be available. 一篇文章可能包含象 schema:CreativeWork sioc:Post prov:Entity schema:Article这样的类,否则,没有独特的数据表明它是"dokieli" 文档。如果HTML+RDFa 表述包含do.js并且DOM已经准备好,则DO
:Object { C: {…}, U: {…} }
将可用。 - Annotation标注
-
An annotation has the
oa:Annotation
class. It is possible to know that the article was rendered by dokieli:?s oa:renderedVia <https://dokie.li/>
, and we can assume that the annotation was created by it as well. This is not strictly true since that property could have been put there by something else. Annotations represented in HTML+RDFa do not include do.js. 一个标注有一个oa:Annotation
类。有可能知道文章是由 dokieli生成的:?s oa:renderedVia <https://dokie.li/>
, 并可以假设标注是由它创建的。 因为该属性可以被其它别的东西放在那儿,所以严格说也不一定正确。在HTML+RDFa表示的标注不包括do.js. - Notification通知
-
A notification may have one of the following classes:
as:Announce
,as:Like
,as:Dislike
,as:Relationship
. Notifications represented in HTML+RDFa do not include do.js. 一个通知可能是下列类之一:as:Announce
,as:Like
,as:Dislike
,as:Relationship
. 在HTML+RDFa中表示的通知不包括do.js.
HTML patternsHTML 模式
One of the goals of dokieli is not to impose arbitrary restrictions on type of nodes as well as the order they should be in HTML+RDFa. It has its own design patterns. It is an ongoing work to make dokieli as flexible as it can be on what it can consume. Ultimately, well-formed and valid HTML - along with accompanying RDFa, Turtle, JSON-LD, TriG etc - is the only requirement here. Take what you like:
dokieli 的目标之一是不对节点的类型以及在HTML+RDFa中应具有的顺序施加任意限制。它有自己的设计模式。这是正在让dokieli在使用的时候尽可能的灵活,最终, 良好的格式和有效的 HTML——连同RDFa, Turtle,JSON-LD, TriG等——仅在这里是需要的。可以采用你喜欢的形式:
- Markup syntax标记语法
-
HTML5 Polyglot Markup is used to ensure that when content is processed or served as HTML or XHTML (
text/html
,application/xhtml+xml
), they can generally be used in both HTML and XML ecosystems without further intervention. See also getDocument (do.js) for details on DOM normalisation. HTML5 多元标记 用于确保当内容被处理成或用作HTML工XHTML (text/html
,application/xhtml+xml
)时,它们通常可以在HTML和XML生态中使用,而无需进一步干预。对于DOM规范化的详细信息,参见 getDocument (do.js) 。 - Identifiers标识符
-
Unique identifiers (
@id
) may be placed on any element. Identifiers are auto-generated by normalising some input eg.section
s use their heading's text content as input,table
s fromcaption
. Anything of importance should have an identifier, and aimed to be included for common patterns out of the box.@id
values are reused in RDFa. See also generateAttributeId (do.js) and its application in different places. 可以将唯一标识符(@id
) 放在任何元素上。标识符在规范化一些输入时自动生成,例如section
使用它们的标题文本作为输入,table
则取自caption
。任何重要的东西都应该有一个标识符,并且目标是将常用模式包含在里面开箱可用。@id
值在RDFa中重用。参见 generateAttributeId (do.js) 和它在不同地方的应用。 - Outline大纲
-
-
title
is used. 使用title
。 -
main > article
(querySelector) is considered to be the location of the primary content. 我们认为main > article
(querySelector) 是主内容的定位。 -
h1
is typically the first element node aftermain > article
h1
通常是main > article
之后的第一个元素节点。 -
There is a resource type, eg.
schema:Article
that can be found inmain > article
which is about the article.body
may contain broad classes. 有一种资源类型,例如schema:Article
是关于文章,可以在main > article
中找到。body
可能包含更宽的类。
-
- Section分节
-
Sectioning is declared with
section
and typically have a heading, eg.h2
as its first child. Subsections may appear as a child of parentsection
, or as a child ofdiv
(which is a child of parentsection
), ie.section section
orsection div section
. The headings of subsections are enumerated eg.section h2
would have a subsection withsection h3
. Sectionsid
s and heading text are used to dynamically build the table of contents. 分节是用section
声明,通常有一个标题,例如h2
作为它的第一个子元素。子节可以作为父section
的子元素, 或者作为div
(它是父section
的子元素)的子元素)如section section
或section div section
. 子节的标题列举如下section h2
可以有个子分节section h3
。分节id
和标题文本用于动态生成目录。<section>
<h2><div>
<section>
<h3><div>
<div>
<aside>
<section>
<h2><section>
<h3>h2 and h3 are used for section
titles,div
as a typical wrapper (eg. for descriptions), as well as to contain further sub-sectioned content. h2和 h3 用作section
标题,div
作为典型的(eg. 描述)的包装器,以及包含更多的子分节内容。 - Aside侧边栏
-
aside
s can technically appear anywhere, but tend to appear as the last element node insection
, eg. for related content, footnotes. If theaside
is introduced to the DOM via JavaScript for like annotations, they have a similar structure tosection
.aside
在技术上可以出现在任何地方,但往往出现在最后一个section
节点的元素中,例如相关内容,脚注等。如果aside
通过JavaScript作为标注引入到DOM中,它们有一个跟section
相似的结构。 - Division分割
-
div
s withinsection
are used to wrap a block of arbitrary markup and content. See also RDFa below. 在section
中的div
用来包装任意标记和内容。参见下面的RDFa。 - Figure图例
-
figure
s typically havefigcaptions
for things likeaudio
,canvas
,iframe
,img
,object
,pre
,video
,math
. For code scripts,figure class="listing"
is used, andpre
for the code itself withcode
Thelisting
class is intended to have a collection of figures, which could also have a unique presentation, for example with line numbers or have its caption be prefixed withListing
and counter.figure
能常用figcaptions
表示事物,象audio
,canvas
,iframe
,img
,object
,pre
,video
,math
。对于代码脚本,则使用figure class="listing"
,而pre
为代码本身加上code
,listing
类会有一个图例集合,这些数据也可以有一个独立的表示,例如使用行号或带有Listing
和计数器前缀的标题。<section>
<h2><div>
<section>
Snippet of section source code 分节源 代码片段 Comparison of systems系统比较 d1 d2 d3 m1 Foo m o n 1 Bar k e y 2 Baz ! @ # 3 Table columns list the dimensions: d1, d2, d3, and the measure: m1. - Math数学
-
For mathematical equations
figure class="equation"
can be used to hint at an equation display. MathML base equation with<math xmlns="http://www.w3.org/1998/Math/MathML">
root can be included here (see also source). Alternatively, if MathJax JavaScript is available in the document, (La)TeX, eg. \lim_{x \to \infty} \exp(-x) = 0 and ASCIIMath, eg. sum_(i=1)^n i^3=((n(n+1))/2)^2, syntaxes can be input within the authoring mode (via Edit). 对数学等式figure class="equation"
可以用来显示等式。基于MathML 的等式使用<math xmlns="http://www.w3.org/1998/Math/MathML">
根,可以包含在这里(参见源代码).,或者,如果在文档中存在 MathJax JavaScript,则可以使用 (La)TeX, 例如 \lim_{x \to \infty} \exp(-x) = 0 和 ASCIIMath, 例如 sum_(i=1)^n i^3=((n(n+1))/2)^2, 语法可以在创作模式中输入 (通过Edit)。 - Turtle, JSON-LD, and TriG syntaxes are placed within respective
script
blocks inhead
eg.<script id="meta-json-ld" type="application/ld+json" title="JSON-LD"></script>
. Data is enclosed inCDATA
sections. This pattern is detected, visible and editable from Embed Data in dokieli menu. See also showEmbedData (do.js).Embedding Turtle, JSON-LD, and TriG嵌入Turtle, JSON-LD和TriG -
Turtle, JSON-LD和TriG 语法被放置在
head
中相应的script
块里,例如<script id="meta-json-ld" type="application/ld+json" title="JSON-LD"></script>
。数据则由CDATA
节包围。如果探测到此模式,则可以在 dokieli 菜单的Embed Data中查看和编加。参见showEmbedData (do.js). - CSS
-
Multiple stylesheets can be included with
@media
, and when accompanied with@title
, some user-agents can provide options for the user to switch between them, as well as from the dokieli menu, eg. 可以用@media
包含多个样式表,并且当附带@title
时,一些用户代理可以为用户提供它们之间的切换选项,例如在 dokieli 菜单中:<!-- Primary stylesheet -->
See also showViews (do.js). 参见showViews (do.js)。<link href="media/css/basic.css" media="all" rel="stylesheet" title="Basic" />
<!-- Alternate stylesheet --><link href="media/css/acm.css" media="all" rel="stylesheet alternate" title="ACM" />
<!-- Applied by default--><link href="https://dokie.li/media/css/do.css" media="all" rel="stylesheet" />
- RDFa
- dokieli can consume and produce RDFa Core 1.1 syntax. dokieli可以使用和生成 RDFa Core 1.1 语法。
-
To preserve the order of content,
@inlist
is used eg.<section inlist=""
,<dd id="Sarven-Capadisli" inlist="" rel="bibo:authorList" resource="http://csarven.ca/#i">
. 为了保持内容的顺序,使用@inlist
,例如<section inlist=""
,<dd id="Sarven-Capadisli" inlist="" rel="bibo:authorList" resource="http://csarven.ca/#i">
. -
A
section
s@id
value is used as part ofsection
's@resource
as a fragment, eg.<section id="introduction" rel="schema:hasPart" resource="#introduction">
. This allows the same identifier to be used for humans and machines, the value is derived from normalising its heading value as mentioned earlier.section
的@id
值用作section
的@resource
的分片,例如<section id="introduction" rel="schema:hasPart" resource="#introduction">
。这允许相同的标识符用于人和机器,该值是通过如前所述规范化其标题值而得到的。 -
Relating parts is done with
rel="schema:hasPart"
, eg. sections with subsection: 关联部分通过rel="schema:hasPart"
完成,例如在子节中的节:<section id="structure-and-semantics" inlist="" rel="schema:hasPart" resource="#structure-and-semantics">
<section id="html-patterns" inlist="" rel="schema:hasPart" resource="#html-patterns">
-
div
s are used to hold a block of HTML markup and types of content together eg.<div datatype="rdf:HTML" property="schema:description" resource="#introduction" typeof="deo:Introduction">
makes it possible to declare that it contains HTML markup, and describes an introductory text.div
用将HTML标记块和内容保存在一起,例如<div datatype="rdf:HTML" property="schema:description" resource="#introduction" typeof="deo:Introduction">
,这样可以声明它包含 HTML标记,并描述一个介绍性的文本。 -
Some of the prefixes (
@prefix
) on thebody
element are defined in the RDFa Core Initial Context. These prefixes are defined in dokieli for the purpose of being compact, robust, and to minimise potential errors for consumers. 在元素body
上有一些前缀 (@prefix
)定义在RDFa 核心初始上下文中,这些前缀在dokieli中定义,为了更加加紧凑、健壮,并最大限度的减少使用者的潜在错误。
Note注意
There is a work in progress to have a distribution version of dokeli, requiring only do.css and do.js in templates.
我们有一项进行中的工作 ,发行版本的dokeli仅需要在模板中包括do.css 和 do.js 。
Servers should use UTF-8
character encoding in their HTTP responses to articles, annotations, and notifications. <meta charset="utf-8" />
is used in HTML.
服务器在它们对文章、评注和通知的HTTP响应应该使用UTF-8
字符编码,在HTML中使用 <meta charset="utf-8" />
Article文章
See also createNoteDataHTML (do.js)
参见createNoteDataHTML (do.js)
<!DOCTYPE html>
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title></title>
<meta content="width=device-width, initial-scale=1" name="viewport" />
<link href="https://dokie.li/media/css/basic.css" media="all" rel="stylesheet" title="Basic" />
<link href="https://dokie.li/media/css/do.css" media="all" rel="stylesheet" />
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" media="all" rel="stylesheet" />
<script src="https://dokie.li/scripts/simplerdf.js"></script>
<script src="https://dokie.li/scripts/medium-editor.min.js"></script>
<script src="https://dokie.li/scripts/do.js"></script>
</head>
<body about="" prefix="rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# rdfs: http://www.w3.org/2000/01/rdf-schema# owl: http://www.w3.org/2002/07/owl# xsd: http://www.w3.org/2001/XMLSchema# dcterms: http://purl.org/dc/terms/ dctypes: http://purl.org/dc/dcmitype/ foaf: http://xmlns.com/foaf/0.1/ pimspace: http://www.w3.org/ns/pim/space# cc: https://creativecommons.org/ns# skos: http://www.w3.org/2004/02/skos/core# prov: http://www.w3.org/ns/prov# mem: http://mementoweb.org/ns# qb: http://purl.org/linked-data/cube# schema: http://schema.org/ void: http://rdfs.org/ns/void# rsa: http://www.w3.org/ns/auth/rsa# cert: http://www.w3.org/ns/auth/cert# wgs: http://www.w3.org/2003/01/geo/wgs84_pos# bibo: http://purl.org/ontology/bibo/ sioc: http://rdfs.org/sioc/ns# doap: http://usefulinc.com/ns/doap# dbr: http://dbpedia.org/resource/ dbp: http://dbpedia.org/property/ sio: http://semanticscience.org/resource/ opmw: http://www.opmw.org/ontology/ deo: http://purl.org/spar/deo/ doco: http://purl.org/spar/doco/ cito: http://purl.org/spar/cito/ fabio: http://purl.org/spar/fabio/ oa: http://www.w3.org/ns/oa# as: https://www.w3.org/ns/activitystreams# ldp: http://www.w3.org/ns/ldp# solid: http://www.w3.org/ns/solid/terms# acl: http://www.w3.org/ns/auth/acl# dio: https://w3id.org/dio# rel: https://www.w3.org/ns/iana/link-relations/relation#" typeof="schema:CreativeWork sioc:Post prov:Entity">
<main>
<article about="" typeof="schema:Article">
</article>
</main>
</body>
</html>
The subject of the following statements may be anywhere in a document. They tend to give some provenance level information and intended to bring more context and attract reuse of the document in different ways.
以下陈述的主题可以在文档中的任何位置。他们倾向于提供一些源起级别的信息,旨在带来更多的上下文,并以不同的方式促使文档的重用。
<dl id="document-identifier">
<dt>Identifier</dt>
<dd><a href="http://csarven.ca/dokieli-rww" rel="owl:sameAs">http://csarven.ca/dokieli-rww</a></dd>
</dl>
The owl:sameAs
indirectly gives this article, ie. any copy, an identifier. The identifier is typically where an article was originally made accessible from, so having this by default for copy distribution helps to keep its connection to source.
owl:sameAs
间接地给出了这样的文章,即任何副本,一个标识符。标识符通常是最初可以从中访问文章的位置,因此默认情况下将其用于副本分发有助于保持其与源的连接。
<dl id="document-inbox">
<dt>Notifications Inbox</dt>
<dd><a href="https://linkedresearch.org/inbox/csarven.ca/dokieli-rww/" rel="ldp:inbox">inbox/</a></dd>
</dl>
ldp:inbox
relation gives an article its own Inbox where it can receive notifications about eg. annotations or activities relevant to an article. The notifications can be consumed by applications to offer additional content and interactive possibilities. dokieli can both send and consume notifications by way of discovering an article's inbox. Notifications are created for activities like announcements, creating, (dis)liking, and consumed in order to be displayed in context of available content. The protocol to send and consume notifications in dokieli uses Linked Data Notifications.
ldp:inbox
关系(rel)为文章提供了自己的收件箱,它可以接收文章标注或活动相关的通知。应用程序可以使用通知来提供其他内容和交互式可能性。dokieli可以通过发现文章的收件箱来发送和使用通知。为诸如公告,创建,(不)点赞,使用为了在可用内容中显示上下文创建通知。在dokieli中发送和使用通知的协议使用Linked Data Notifications.
<dl id="document-in-reply-to">
<dt>In Reply To</dt>
<dd><a href="https://linkedresearch.org/calls" rel="as:inReplyTo">Call for Linked Research</a></dd>
</dl>
If an article is a reply to objects(s), it can have a property like as:inReplyTo
.
如果文章是客体的回复,它可以具有类似as:inReplyTo
的属性。
<dl id="document-annotation-service">
<dt>Annotation Service</dt>
<dd><a href="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/" rel="oa:annotationService">annotation/</a></dd>
</dl>
An article may refer to an annotation service (oa:annotationService
) that conforms to the Web Annotation Protocol. See also DO.C.AnnotationService in do.js
.
文章可以指代一个(oa:annotationService
) 符合 Web Annotation Protocol的标注服务。 参见 DO.C.AnnotationService in do.js
.
<dl id="document-published">
<dt>Published</dt>
<dd><time content="2017-02-27T00:00:00Z" datatype="xsd:dateTime" datetime="2017-02-27T00:00:00Z" property="schema:datePublished">2017-02-27</time></dd>
</dl>
<dl id="document-modified">
<dt>Modified</dt>
<dd><time content="2017-03-12T00:00:00Z" datatype="xsd:dateTime" datetime="2017-03-12T00:00:00Z" property="schema:dateModified">2017-03-18</time></dd>
</dl>
Dates, you know.. kinda useful. The example above duplicates the ISO date in @content
and @datetime
, but only one needs to be there, given that there parsers for different RDFa versions.
日期,你懂的,有点用的。上面的例子复制了在@content
和@datetime
中的ISO日期,但是因为有不同的RDFa版本的解析器,所以只需要其中一个就可以。
<dl id="document-license">
<dt>License</dt>
<dd><a href="https://creativecommons.org/licenses/by/4.0/" rel="schema:license" title="Creative Commons Attribution 4.0 Unported">CC BY 4.0</a></dd>
</dl>
Nice to declare a license or rights to signal under what conditions the document may be reused, reshared or remixed, eg. via Creative Commons license. Articles and notifications tend to use schema:license
and annotations use dcterms:rights
(given Web Annotation Vocabulary).
很高兴在这里宣布许可和版权信息,在什么条件下可以重复使用、转发或者重混文件。例如通过创作共用许可。文章和通知倾向于使用 schema:license
而标注倾向于使用dcterms:rights
(给定 Web标注词汇).
<dl id="document-derived-from">
<dt>Derived From</dt<
<dd><a href="https://dokie.li/" rel="prov:wasDerivedFrom">https://dokie.li/</a></dd>
</dl>
<dl id="document-derived-on">
<dt>Derived On</dt>
<dd><time datetime="2017-08-06T00:29:45.342Z">2017-08-06T00:29:45.342Z</time></dd>
</dl>
If a document is derived from another using the Save As operation, derived from and derived on information is declared.
如果使用“另存为”操作从另一个文档派生文档,则声明信息派生和被派生的文档。
The markup for an anonymous profile is like:
匿名配置文件的标记如下
<span typeof="schema:Person">Lunatic Scholar</span>
The markup for a WebID profile including their name:
WebID配置文件包含他们名称的配置文件如下:
<span about="http://csarven.ca/#i" property="schema:name">Sarven Capadisli</span>
If they have an image:
如果他们有一张图片
<img alt="" height="48" rel="schema:image" src="http://csarven.ca/media/images/sarven-capadisli.jpg" width="48" />
Progressively described name, image, and URL is useful in templates:
渐进描述的名称,图像和URL在模板中很有用:
<span about="http://csarven.ca/#i" typeof="schema:Person"><img alt="" height="48" rel="schema:image" src="http://csarven.ca/media/images/sarven-capadisli.jpg" width="48" /> <a href="http://csarven.ca/" rel="schema:url"><span about="http://csarven.ca/#i" property="schema:name">Sarven Capadisli</span></a></span>
Alternatively applying the DRY principle:
或者使用 DRY 原则:
<a about="http://csarven.ca/#i" href="http://csarven.ca/" property="schema:name" rel="schema:url" typeof="schema:Person">Sarven Capadisli</a>
If they are one of the authors of a document, the profile can be wrapped like:
如果他们是文档的作者之一,则可以将配置文件包装为:
<dd id="Sarven-Capadisli" inlist="" rel="bibo:authorList" resource="http://csarven.ca/#i"><span about="" rel="schema:creator schema:publisher schema:author"><!-- profile --></span></dd>
See also getUserHTML (do.js)
参见getUserHTML (do.js)
Annotation标注
Annotations have their own URL, fetched, parsed, and then introduced into the DOM. They are normally appended at the bottom of a node (section
) in which the annotation has a reference to. It is not required to introduce all of the annotation content into the DOM, nor all of it has to be human-visible. This is a run-time inclusion and typically included within <aside class="note do"></aside>
. Write operations like Save, Save As, Export will exclude this (class~="do"
) when it normalises the DOM to HTML.
标注具有自己的URL,获取,解析,然后引入DOM。它们通常附加在 (section
)节点底部,标注有一个到这里的引用。不需要将所有标注内容引入DOM,也不必将所有标注内容都引入到人类可视。这是一个运行时包含,通常包含在内<aside class="note do"></aside>
。当将DOM规范化到HTML时,像Save, Save As, Export 这样的写操作会将它(class~="do"
)排除在外。
Currently dokieli uses oa:replying, oa:commenting, oa:describing, oa:assessing, oa:bookmarking for motivations, and oa:describing and oa:tagging for annotation purpose.
当前dokieli使用 oa:replying, oa:commenting, oa:describing, oa:assessing, oa:bookmarking作为动机,而oa:describing 和 oa:tagging作为标注的目的.
See also createNoteDataHTML (do.js)
另请参见 createNoteDataHTML (do.js)
Here is an annotation resource at https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f with all information human-visible and machine-readable (HTML+RDFa):
以下是https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f的标注资源,所有信息均为人类可见且机器可读(HTML+RDFa):
Its source:
它的源为:
<!DOCTYPE html>
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f</title>
</head>
<body>
<main>
<article id="b6738766-3ce5-4054-96a9-ced7f05b439f" about="i:" typeof="oa:Annotation" prefix="rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# schema: http://schema.org/ dcterms: http://purl.org/dc/terms/ oa: http://www.w3.org/ns/oa# as: https://www.w3.org/ns/activitystreams# i: https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f">
<h1 property="schema:name">Sarven Capadisli <span rel="oa:motivatedBy" resource="oa:replying">replies</span></h1>
<dl class="author-name">
<dt>Authors</dt>
<dd><span rel="schema:creator"><span about="http://csarven.ca/#i" typeof="schema:Person"><img alt="" height="48" rel="schema:image" src="http://csarven.ca/media/images/sarven-capadisli.jpg" width="48" /> <a href="http://csarven.ca/" rel="schema:url"><span about="http://csarven.ca/#i" property="schema:name">Sarven Capadisli</span></a></span></span></dd>
</dl>
<dl class="published">
<dt>Published</dt>
<dd><a href="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f"><time datetime="2017-04-15T21:24:58.293Z" datatype="xsd:dateTime" property="schema:datePublished" content="2017-04-15T21:24:58.293Z">2017-04-15 21:24:58</time></a>
</dd>
</dl>
<dl class="rights">
<dt>Rights</dt>
<dd><a href="https://creativecommons.org/licenses/by/4.0/" rel="dcterms:rights" title="Creative Commons Attribution">CC BY 4.0</a></dd>
</dl>
<dl class="canonical">
<dt>Canonical</dt>
<dd about="i:" rel="oa:canonical" resource="urn:uuid:48355bb0-0afd-4f73-9a18-f1e8b6fb415b">48355bb0-0afd-4f73-9a18-f1e8b6fb415b</dd>
</dl>
<dl class="target">
<dt><a href="http://csarven.ca/dokieli-rww#abstract" rel="oa:hasTarget">In reply to</a> (<a about="http://csarven.ca/dokieli-rww#abstract" href="http://csarven.ca/dokieli-rww" rel="oa:hasSource" typeof="oa:SpecificResource">part of</a>)</dt>
<dd>
<blockquote about="http://csarven.ca/dokieli-rww#abstract" cite="http://csarven.ca/dokieli-rww#abstract">
<div rel="oa:hasSelector" resource="i:#fragment-selector" typeof="oa:FragmentSelector">
<dl class="conformsto">
<dt>Fragment selector conforms to</dt>
<dd><a property="rdf:value" content="abstract" xml:lang="" lang="" rel="dcterms:conformsTo" href="https://tools.ietf.org/html/rfc3987">RFC3987</a></dd>
</dl>
<dl class="refinedby" rel="oa:refinedBy" resource="i:#text-quote-selector" typeof="oa:TextQuoteSelector">
<dt>Refined by</dt>
<dd><span property="oa:prefix" xml:lang="en" lang="en">rchitecture and implementation, </span><mark property="oa:exact" xml:lang="en" lang="en">demonstrating advanced document authoring and interaction without a single point of control</mark><span property="oa:suffix" xml:lang="en" lang="en">. Such an environment provides t</span></dd>
</dl>
</div>
</blockquote>
</dd>
</dl>
<dl class="renderedvia">
<dt>Rendered via</dt>
<dd><a about="http://csarven.ca/dokieli-rww#abstract" href="https://dokie.li/" rel="oa:renderedVia">dokieli</a></dd>
</dl>
<section id="note-b6738766-3ce5-4054-96a9-ced7f05b439f" rel="oa:hasBody" resource="i:#note-b6738766-3ce5-4054-96a9-ced7f05b439f">
<h2 property="schema:name">Note</h2>
<dl class="rights">
<dt>Rights</dt>
<dd><a href="https://creativecommons.org/licenses/by/4.0/" rel="dcterms:rights" title="Creative Commons Attribution">CC BY 4.0</a></dd>
</dl>
<div datatype="rdf:HTML" property="rdf:value schema:description" resource="i:#note-b6738766-3ce5-4054-96a9-ced7f05b439f" typeof="oa:TextualBody">What are you trying to tell me? That I can dodge bullets?</div>
</section>
</article>
</main>
</body>
</html>
<dl class="canonical">
<dt>Canonical</dt>
<dd rel="oa:canonical" resource="urn:uuid:48355bb0-0afd-4f73-9a18-f1e8b6fb415b">48355bb0-0afd-4f73-9a18-f1e8b6fb415b</dd>
</dl>
oa:canonical
refers to a canonical IRI that can be used to deduplicate the annotation. If an user chooses to store their annotation at their personal Webspace as well as when an annotation service (if offered), dokieli treats the resource at personal space as the canonical, and the resource at the annotation service as the copy where it refers to the personal space (oa:via
).
oa:canonical
是指可用于对标注进行去重复的正式IRI。如果用户选择将其标注存储在其个人Web空间或者标注服务(如果有提供的话)时,dokieli将个人空间中的资源视为正式,并将标注服务中的资源视为其引用的副本(oa:via
)。
If an annotation resource is introduced to the article's DOM as part of an aside
, they have a structure similar to an article
, and may be displayed in different ways, eg. in marginalia:
如果标注资源作为aside
的一部分引入到文章的DOM,则它们具有类似于article
的结构,并且可以用不同的方式显示,例如在边缘部分:
<aside class="note do">
<blockquote cite="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f">
<article about="i:" id="461819979" prefix="i: https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f" typeof="oa:Annotation">
<!-- Reconstruction of the original annotation (from RDF) -->
</article>
</blockquote>
</aside>
An inline reference to that annotation as aside would have a structure like:
对该标注的内联引用作为边栏会有以下的结构:
<span class="ref do" rel="schema:hasPart" resource="#r-461819979" typeof="dctypes:Text"><mark id="r-461819979" property="schema:description">demonstrating advanced document authoring and interaction without a single point of control</mark><sup class="ref-annotation"><a rel="cito:hasReplyFrom" href="#461819979" resource="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f">💬</a></sup></span>
Note that the human-visible anchor hyperlinks (#461819979) to the annotation aside id="461819979"
.
注意人类可读的到标注aside id="461819979"
的超链接锚(#461819979)。
Notification通知
Notifications are discovered from LDN Inboxes. An article (or a fragment within) may have an inbox relation (ldp:inbox
) which helps dokieli to discover it, and then fetch the notifications.
从 LDN收件箱中发现通知。文章 (或其中的片段) 可能会有一个(ldp:inbox
)收件箱关系,这有助于dokieli发现它,然后获取该通知。
Notifications are intended to be brief, giving sufficient information for consumers to decide if they want use to them. If the notifications are generated by dokieli, eg. via an annotation activity, they typically include some provenance level data like generation date, actor that triggered it, license, where the annotation can be found, what it annotated, and the motivation for it. Notifications will not include the annotation body, but consumers can fetch their URLs (as mentioned in the annotation section).
通知旨在简短,为使用者提供足够的信息,以决定他们是否想要使用它们。如果通知是由dokieli生成的,例如,通过标注活动,它们通常包括一些源起层面的数据,如生成日期,触发它的角色,许可证,从这些地方可以找到标注的位置,标注内容以及动机。通知将不包括标注正文,但是使用者可以获取其URL(如标注部分中所述)。
See also createNoteDataHTML (do.js)
参见createNoteDataHTML (do.js)
Here is a notification resource at https://linkedresearch.org/inbox/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f with all information human-visible and machine-readable (HTML+RDFa):
以下是在https://linkedresearch.org/inbox/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f的通知资源,所有信息均为人类可见且机器可读(HTML + RDFa):
Its source:
它的源为:
<!DOCTYPE html>
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Notification: Announced</title>
</head>
<body prefix="xsd: http://www.w3.org/2001/XMLSchema# rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# as: https://www.w3.org/ns/activitystreams# oa: http://www.w3.org/ns/oa# schema: http://schema.org/">
<main>
<article>
<h1>Notification: Announced</h1>
<section>
<dl about="">
<dt>Types</dt>
<dd><a about="" href="https://www.w3.org/ns/activitystreams#Announce" typeof="as:Announce">Announce</a></dd>
<dt>Object</dt>
<dd><a href="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f" property="as:object">https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f</a></dd>
<dt>Target</dt>
<dd><a href="http://csarven.ca/dokieli-rww#abstract" property="as:target">http://csarven.ca/dokieli-rww#abstract</a></dd>
<dt>Updated</dt>
<dd><time datetime="2017-04-15T21:31:45.711Z" datatype="xsd:dateTime" property="as:updated" content="2017-04-15T21:31:45.711Z">2017-04-15 21:31:45</time></dd>
<dt>Actor</dt>
<dd><a href="http://csarven.ca/#i" property="as:actor">http://csarven.ca/#i</a></dd>
<dt>License</dt>
<dd><a href="https://creativecommons.org/publicdomain/zero/1.0/" property="schema:license">https://creativecommons.org/publicdomain/zero/1.0/</a></dd>
</dl>
<dl about="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f">
<dt>Object type</dt>
<dd><a about="https://linkedresearch.org/annotation/csarven.ca/dokieli-rww/b6738766-3ce5-4054-96a9-ced7f05b439f" typeof="oa:Annotation" href="http://www.w3.org/ns/oa#Annotation">Annotation</a></dd>
<dt>Motivation</dt>
<dd><a href="http://www.w3.org/ns/oa#replying" property="oa:motivation">replying</a></dd>
</dl>
</section>
</article>
</main>
</body>
</html>
User interface 用户界面
Document modes文档模式
There UI adapts to the document mode the user is in: author, review, social. By default the social mode is engaged. The dokieli menu allows the user to engage the author mode through the Edit operation, and the review mode with Review. See also setDocumentMode (do.js).
UI适应用户所处的文档模式 : 创作, 评论, 社交l默认情况下,启用 社交模式。 dokieli 菜单 允许用户通过 编辑 操作启用创作模式,通过 评论启用评论模式。参见setDocumentMode (do.js).
HTTP operationsHTTP操作
dokieli conforms to Linked Data Platform (LDP) protocol for create, update, and delete operations.
dokieli 符合 Linked Data Platform (LDP) 协议的创建,更新和删除操作。
Article operations like New, Save, Save As, Reply use HTTP PUT
, Review and other annotation operations use HTTP POST
.
文章操作象 New, Save, Save As, Reply 使用 HTTP PUT
, Review 和其它评注操作使用 HTTP POST
.
Notifications are sent with HTTP POST
. Save and Save As normalises the HTML before sending.
通知发送使用 HTTP POST
. Save 和 Save As在发送前示范化HTML。
HTTP method(s) | Content-Type |
|
---|---|---|
Article | PUT | text/html |
Annotation | OPTIONS , POST | text/html , application/ld+json , text/turtle |
Notification | OPTIONS , POST | text/html , application/ld+json , text/turtle |
|
Due to Mixed Content implementations in Web browsers, ie. fetching of content over unencrypted or unauthenticated connections in the context of an encrypted and authenticated document
, is subject to being blocked by the Web browser. Hence, an https document (eg article at https) will not be able to use the contents of an http document (eg. an http WebID). As a workaround, dokieli uses a proxy endpoint by default in order to use the contents of an http resource. An https document fetching an https resource will not use the proxy.
由于Web浏览器中的混合内容实现,即,在加密和经过身份验证的文档的上下文中通过未加密或未经身份验证的连接获取内容
,可能会被Web浏览器阻止。因此,https文档(例如,https上的文章)将不能使用http文档的内容(例如,http WebID)。作为一种解决方法,dokieli默认使用代理端点来使用http资源的内容。获取https资源的https文档将不使用该代理。
Authentication认证
Storage存储
- Personal storage个人存储
-
WebID's with
pim:storage
can get to use their personal online data storage with dokieli's read-write operations, eg all annotations, Reply, Review, New, Save As. WebID的pim:storage
可以使用dokieli的读写操作来使用他们的个人在线数据存储,例如所有的评注操作,回复, 评论, 新建, 另存为。 - Local storage本地存储
- There is a Local Storage feature which uses user-agent's window.localStorage, with default 1m autosave. 有一个 本地存储功能,使用用户代理的window.localStorage,默认1m自动保存。
Web ExtensionWeb扩展
The dokieli Web Extension is a minimal package of dokieli which contains the core CSS and JavaScript that works as a browser add-on. When user triggers it from their browser toolbar, it provides the same functionality as a single-page application, ie. initialised and rendered in the browser DOM.
dokieli Web扩展 是dokili的一个最小包,其中包括含用作浏览器插件的核心CSS和JavaScript。当用户从浏览器工具栏触发它时,它提供与单页应用程序相同的功能,即,在浏览器DOM中初始化并渲染。
Currently the extension works with Firefox and Chrome/Chromium browsers. Two ways to do this:
目前,该扩展程序适用于Firefox和Chrome/Chromium浏览器,有两种方法可选:
- Extensions are available from Add-ons for Firefox and Chrome Web Store. 扩展程序可以从 Add-ons for Firefox 和 Chrome Web Store获得。
-
Clone https://github.com/linkeddata/dokieli and import directory:
克隆 https://github.com/linkeddata/dokieli 并导入目录:
-
Firefox:
Load Temporary Add-on
from Add-ons (or go toabout:debugging
from addressbar) and import by selecting a file from the directory (eg manifest.json). See also temporary add-on installation. Firefox: 从加载项加载临时加载项
(或从地址栏转到about:debugging
) 并从目录中选择一个文件(例如 manifest.json)。参见 临时加载项安装. -
Chrome/Chromium: Check the
developer more
option, under Extensions (or go tochrome://extensions/
from addressbar) and import the directory. Chrome/Chromium: 在扩展程序 (或从地址栏chrome://extensions/
)查看更多开发者
选项,并导入目录。
-
Firefox:
Development开发
git clone https://github.com/linkeddata/dokieli
cd dokieli
# Install packages
npm install
# Build stuff eg. scripts/do.js
npm run build
# or automatically rebuild when files change
npm run watch