◊(Local Yarn Code "Check-in [885574b7]")

Overview
Comment:Diagrams and revisions in code docs
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 885574b74fa6396eba9acee597a7192bcd230d6ff850928196de5782609075ab
User & Date: joel on 2020-03-01 23:29:48
Other Links: manifest | tags
Context
2020-03-07
23:39
Changes to home page. Fixes [fc4c7472aeafe082] check-in: d928b82f user: joel tags: trunk
2020-03-01
23:29
Diagrams and revisions in code docs check-in: 885574b7 user: joel tags: trunk
23:28
Add a little line doodle to the footer check-in: e9be84e2 user: joel tags: trunk
Changes

Modified code-docs/design.scrbl from [85920e85] to [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

Added code-docs/diagram-notes.png version [bf22d3e3].

cannot compute difference between binary files

Modified code-docs/main.scrbl from [ddb962d8] to [d030a01e].

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
implement everything I want in my @secref["design-goals"], @tt{B)} cleanly separate dependencies for
print and web output, and @tt{C)} organize an ever-growing collection of hundreds of individual
notes and articles without noticable loss of speed. 

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

The solid-line connections indicate explicit @racket[require] relationships. Dotted arrows generally
indicate implicit exports in the Pollen environment: docs and metas to templates,
@seclink["pollen-rkt"]{@filepath{pollen.rkt}} to source documents and templates. The orange lines
highlight the provision and use of the functions in
@seclink["crystalize-rkt"]{@filepath{crystalize.rkt}}.

Individual articles, while they are being rendered to HTML pages, save copies of their metadata and
HTML to the SQLite cache. This is done by calling @racket[parse-and-cache-article!] from within
their template. Likewise, series pages cache themselves with a call to @racket[cache-series!] from
within their template.

Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull







|
|
|
<
<







29
30
31
32
33
34
35
36
37
38


39
40
41
42
43
44
45
implement everything I want in my @secref["design-goals"], @tt{B)} cleanly separate dependencies for
print and web output, and @tt{C)} organize an ever-growing collection of hundreds of individual
notes and articles without noticable loss of speed. 

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

The modules are arranged vertically: those on the upper rows provide bindings which are used by
those on the lower rows. The bottom row are the @tt{.poly.pm} files that make up @tech{articles} and
@tech{series}.



Individual articles, while they are being rendered to HTML pages, save copies of their metadata and
HTML to the SQLite cache. This is done by calling @racket[parse-and-cache-article!] from within
their template. Likewise, series pages cache themselves with a call to @racket[cache-series!] from
within their template.

Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull

Modified code-docs/source-diagram.png from [707f47d7] to [bfcd60d8].

cannot compute difference between binary files