◊(Local Yarn Code "Diff")

Differences From Artifact [85920e85]:

To Artifact [aadc5678]:


1
2
3
4
5
6

7
8
9
10
11
12
13
#lang scribble/manual

@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.

@(require "scribble-helpers.rkt"

          (for-label "../pollen.rkt"))

@(require (for-label racket/base))

@title{Basic Notions}

@section[#:tag "design-goals"]{Design Goals}






>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
#lang scribble/manual

@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.

@(require "scribble-helpers.rkt"
          racket/runtime-path
          (for-label "../pollen.rkt"))

@(require (for-label racket/base))

@title{Basic Notions}

@section[#:tag "design-goals"]{Design Goals}
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
 @item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
 written before. Views change, new ideas come along. In a typical blog the focus is always at
 whatever’s happening at the head of the time stream; an addendum to an older post is, for all
 practical purposes, invisible and nearly useless. I want every published edit to an article to be
 findable and linkable. I want addenda to be extremely visible. These addenda should also be able to
 mark major shifts in the author’s own perspective on what they originally wrote.}

 @item{@bold{Experimentation must be accomodated gracefully.} I should be able to write fiction,
 poetry, opinion pieces, minor observations or collections, or anything else, and have or create
 a good home for it here. Where dissimilar writings appear together, there should be signals that
 help the reader understand what they are looking at, switch contexts, and find more if they wish.}
 
 @item{@bold{Everything produced here should look good.}}

 @item{@bold{Reward exploration without disorienting the reader.}}



 
 @item{@bold{Everything produced here should be the result of an automatable process.} No clicking
 around to publish web pages and books.}
 
 ]

@section{Names for things and how they fit together}

The Local Yarn is mostly comprised of @tech{articles} (individual writings) which may contain
@tech{notes} (addenda by the author or others) and may also be grouped into @tech{series}. These are







|
|
|
<



|
>
>
>

|
|







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
 @item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
 written before. Views change, new ideas come along. In a typical blog the focus is always at
 whatever’s happening at the head of the time stream; an addendum to an older post is, for all
 practical purposes, invisible and nearly useless. I want every published edit to an article to be
 findable and linkable. I want addenda to be extremely visible. These addenda should also be able to
 mark major shifts in the author’s own perspective on what they originally wrote.}

 @item{@bold{The system will gracefully accomodate experimentation.} I should be able to write
 fiction, poetry, opinion pieces, minor observations or collections, or anything else, and have or
 create a good home for it here.}

 
 @item{@bold{Everything produced here should look good.}}

 @item{@bold{Reward exploration without disorienting the reader.} Draw connections between related
 thoughts using typographic conventions and organizational devices that would be familiar to
 a reader of books. Where dissimilar writings appear together, place signals that help the reader
 understand what they are looking at, switch contexts, and find more if they wish.}
 
 @item{@bold{Everything is produced, and reproducible, by an automatable process.} No clicking or
 tapping around in GUI apps to publish web pages and books.}
 
 ]

@section{Names for things and how they fit together}

The Local Yarn is mostly comprised of @tech{articles} (individual writings) which may contain
@tech{notes} (addenda by the author or others) and may also be grouped into @tech{series}. These are
64
65
66
67
68
69
70



71
72
73
74
75
76
77
78
79
80
started.

@subsection{Notes}

A @deftech{note} is a comment or addendum to an @tech{article} using the @racket[note] tag. It may
be written by the same person who wrote the article, or submitted by a reader.




A note appears at the bottom of the article to which it is attached, but it also appears in the blog
and in the RSS feed as a separate piece of content, and is given the same visual weight as actual
articles.

A note may optionally have a @deftech{disposition} which reflects a change in attitude towards its
parent article. A disposition consists of a @italic{disposition mark} such as an asterisk or dagger,
and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and
add a note describing how their opinion has changed; the tag for this note might include
@racket[#:disposition "* recanted"] as an attribute. This would cause the @tt{*} to be added to the
article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to







>
>
>
|
|
|







67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
started.

@subsection{Notes}

A @deftech{note} is a comment or addendum to an @tech{article} using the @racket[note] tag. It may
be written by the same person who wrote the article, or submitted by a reader.

@(define-runtime-path diagram-notes "diagram-notes.png")
@centered{@responsive-retina-image[diagram-notes]}

As shown above, a note appears at the bottom of the article to which it is attached, but it also
appears in the blog and in the RSS feed as a separate piece of content, and is given the same visual
weight as actual articles.

A note may optionally have a @deftech{disposition} which reflects a change in attitude towards its
parent article. A disposition consists of a @italic{disposition mark} such as an asterisk or dagger,
and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and
add a note describing how their opinion has changed; the tag for this note might include
@racket[#:disposition "* recanted"] as an attribute. This would cause the @tt{*} to be added to the
article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to