◊(Local Yarn Code "Check-in [71aa7cd9]")

Overview
Comment:Filling in tour, design
Timelines: family | ancestors | descendants | both | doc-expansion
Files: files | file ages | folders
SHA3-256: 71aa7cd9450071db92551bc82c25c0fdce0c785062eedccc37d1ebb495b28a84
User & Date: joel on 2020-01-19 05:35:13
Other Links: branch diff | manifest | tags
Context
2020-01-19
20:49
scribble edits check-in: ead156b1 user: joel tags: doc-expansion
05:35
Filling in tour, design check-in: 71aa7cd9 user: joel tags: doc-expansion
04:36
Add custom Scribble styles check-in: c7350de0 user: joel tags: doc-expansion
Changes

Modified code-docs/design.scrbl from [3cfd26b5] to [7f7e48a9].

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
@; This file is licensed under the Blue Oak Model License 1.0.0.

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

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

@title{Design and Layout}

The design and implementation of @italic{The Local Yarn} are guided by a few basic requirements that
have evolved since I started the site in 1999.


@itemlist[
  @item{@bold{The writing will live in two places: on a web server, and on bookshelves.} The web

  server, because it’s a fun, fast way to publish writing and code to the whole world (you knew that
  already); but also on bookshelves, because
  @ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
  a projector}, and I want to be able to turn it off someday and still have something to show for
  all my work. Plus, I just like printed books.}

  @item{@bold{Addenda to older writings should be highly visible.} 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 them 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{Finally: everything produced here, both in print and on the web, should look good.}}


]

@nested[#:style 'inset]{
  “Yet modest ornament with use combined @(linebreak)
  Attracts the eye to exercise the mind.” @(linebreak)
  —@ext-link["https://en.wikipedia.org/wiki/Samuel_Rogers"]{Samuel Rogers}
}







|

|
|
>


<
>
|
|




|
|
|
|
|
|

|
>
>







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
@; This file is licensed under the Blue Oak Model License 1.0.0.

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

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

@title{Design Background}

The design and implementation of @italic{The Local Yarn} are guided by requirements that have
evolved since I started the site in 1999. I enumerate them here because they explain why the code is
necessarily more complicated than a typical blog.

@itemlist[

  @item{@bold{The writing will publish to two places from the same source: the web server, and the
  bookshelf.} The web server, because it’s a fun, fast way to publish writing and code to the whole
  world (you knew that already); but also on bookshelves, because
  @ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
  a projector}, and I want to be able to turn it off someday and still have something to show for
  all my work. Plus, I just like printed books.}

  @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{Everything produced here, both in print and on the web, should look good.}
  @item{@bold{All the output should be produced (and reproducible) by automated processes.} No
  clicking on buttons in apps to publish web pages or books.}
]

@nested[#:style 'inset]{
  “Yet modest ornament with use combined @(linebreak)
  Attracts the eye to exercise the mind.” @(linebreak)
  —@ext-link["https://en.wikipedia.org/wiki/Samuel_Rogers"]{Samuel Rogers}
}

Modified code-docs/main.scrbl from [40a6e0fc] to [89482d00].

59
60
61
62
63
64
65
66
67
68
69
70
71
to maintain them, and (eventually) when to replace them. Details of this maintenance are discussed
in Tools and Methods.


@local-table-of-contents[]

@include-section["tour.scrbl"]
@include-section["design.scrbl"]
@include-section["overview.scrbl"]
@include-section["pollen.scrbl"]  @; pollen.rkt
@include-section["dust.scrbl"]    @; dust.rkt
@include-section["snippets-html.scrbl"] @; you get the idea
@include-section["crystalize.scrbl"]







<





59
60
61
62
63
64
65

66
67
68
69
70
to maintain them, and (eventually) when to replace them. Details of this maintenance are discussed
in Tools and Methods.


@local-table-of-contents[]

@include-section["tour.scrbl"]

@include-section["overview.scrbl"]
@include-section["pollen.scrbl"]  @; pollen.rkt
@include-section["dust.scrbl"]    @; dust.rkt
@include-section["snippets-html.scrbl"] @; you get the idea
@include-section["crystalize.scrbl"]

Modified code-docs/tour.scrbl from [957f21f4] to [8852ebdd].

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")

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

@title{A Tour: Publishing on @italic{The Local Yarn}}

It’s pretty simple.



































































































































|

|

|
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
#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")

@(require (for-label racket/base "../pollen.rkt"))

@section{How I Publish: A Quick Tour}

This isn’t a tutorial, since these steps probably won’t all work on your computer. Think of these
narrations like me talking while I drive.

@subsection{Creating an article}

Open a terminal window.

@terminal{@cmd{> cd /path/to/thelocalyarn}}

The @tt{make} command provides a high-level control panel for common tasks. Typing just make from
a terminal window shows a list of options:

@terminal{
@cmd{> make}
article     Start a new article from a template
help        Displays this help screen
publish     Sync all HTML and PDF stuff to the public web server
scribble    Rebuild code documentation and update Fossil repo
web         Rebuild all web content (not PDFs)
zap         Clear Pollen and Scribble cache, and remove all HTML output
}

Following the first option in this list, I type @tt{make article}, and enter a post title when
prompted:

@terminal{
@cmd{> make article}
racket -tm util/newpost.rkt
Enter title: @cmd{My New Post}
}

The script creates a new @filepath{.poly.pm} file using a normalized version of the title for the
filename, and opens it in my editor (this is currently hardcoded to use MacVim). When the file pops
up we see a basic template ready to edit:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta draft #t)
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
Write here!
}|]

At this point I might delete the @tt{◊title} line, since specifying a formal title is optional
(other than the one needed to generate the filename). I might also add a @racket[define-meta] for
@tt{series} or @tt{topics}. 

As long as the @racket[define-meta] for @tt{draft} is @racket[#t], the new article will not appear
in the RSS feed, or in the blog or any series pages.

When satisfied with the post I’ll remove the @racket[define-meta] for @tt{draft}, save it one last
time, then go back to the terminal:

@terminal{
@cmd{> make web}
[lots of output: rebuilds blog pages, keyword index, RSS feed]
@cmd{> make publish}
[lots of output: uploads all web content to the server]
}

The article also needs to be added to the Fossil repository, so revisions to it will be tracked:

@terminal|{
|@cmd{> fossil add article/my-new-post.poly.pm}
ADDED  article/my-new-post.poly.pm

|@cmd{> fossil commit -m "Publish ‘My New Post’"}
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 0  received: 1
Pull done, sent: 892  received: 8720  ip: 162.243.186.132
New_Version: 15507b62416716a3f0be3c444b0fc09aa4364b989140c5788cf679eb0b2463a6
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 2  received: 1
Sync done, sent: 10153  received: 4680  ip: 162.243.186.132
}|

As you can see, Fossil does an automatic pull before the commit, and another automatic push
afterwards. This commit is now visible on the public timeline, and the source code for the article
can now be seen on the public repo at @tt{thelocalyarn.com/code/}.

@subsection{Adding notes to an article}

A few days (or years) after doing the above, I receive an email from Marjorie with commenting on
@italic{My New Post} and I decide to publish her comments.

I open the article in my editor and add some lines to the end:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
It’s a 4⨉4 treated. I got twenty, actually, for the backyard fence.

◊note[#:date "2020-01-23" #:author "Marjorie"]{
 Hope you sank that thing below the frost line.
}
}|]

This looks like a blog-style comment, but the @racket[note] tag function has some special powers
that typical comments don’t have, as we’ll see in a moment.

I save this, go back to the terminal and do @tt{make web} and @tt{make publish} as before.

Now if you open the article’s permlink, you’ll see the note appears in a “Further Notes” section at
the bottom — again, just like a normal blog post comment.

But if you go to the Blog section, you’ll see the note appearing in its own space right alongside
the other articles, as if it were a separate post. It will also appear in a separate entry in the
RSS feed.

@subsection{What’s not here yet}

Eventually there will be facilities for creating PDF files of individual articles, and print-ready
PDFs of books containing collections of articles.