◊(Local Yarn Code "Changes On Branch c7350de07b52c097")

Changes In Branch doc-expansion Through [c7350de0] Excluding Merge-Ins

This is equivalent to a diff from c06d4f58 to c7350de0

2020-01-19
20:54
Makefile: turn on tidying; ‘all’→‘web’ check-in: c2036411 user: joel tags: trunk
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
03:46
Ignore generated Scribble support files check-in: 2c745dc9 user: joel tags: doc-expansion
2020-01-15
03:20
Start rearranging code docs check-in: 15507b62 user: joel tags: doc-expansion
2020-01-13
19:38
Merge deta refactor branch check-in: c06d4f58 user: joel tags: trunk
01:04
Fix cache db filename, index page Leaf check-in: e90a714a user: joel tags: deta-refactor
2019-08-19
21:36
Add RSS feed. Closes [5cca77420922765f] check-in: f06db447 user: joel tags: trunk

Modified .fossil-settings/ignore-glob from [76dda5be] to [cd6321cb].

1
2
3
4
5
6
7


8
9
10
11
12
13
14
15
16
17
18
19
20
*compiled/*
*.poly.pm
*.woff*
x-*/*
*.*~
web-extra/martin.css
scribbled/*


*/images/*
*.db
*.sqlite
*.pdf
*.ltx
*.html
*.out
*.ltx
*.aux
*.log
*.xml
*.toc
*.mark







>
>













1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
*compiled/*
*.poly.pm
*.woff*
x-*/*
*.*~
web-extra/martin.css
scribbled/*
code-docs/*.css
code-docs/*.js
*/images/*
*.db
*.sqlite
*.pdf
*.ltx
*.html
*.out
*.ltx
*.aux
*.log
*.xml
*.toc
*.mark

Added code-docs/custom.css version [471eaf45].

























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
.fileblock .SCodeFlow {
    padding-top: 0.7em;
    margin-top: 0;
}

.fileblock {
    width: 90%;
}

.fileblock_filetitle{
    background: #eee;
    text-align:right;
    padding: 0.15em;
    border: 1px dotted black;
    border-bottom: none;
}

.terminal, .browser {
    margin-bottom: 1em;
    padding: 0.5em;
    width: 88%;
    background: #fcfcfc;
    color: rgb(150, 35, 105);
}

.terminal .SIntrapara, .browser .SIntrapara, .fileblock .SIntrapara {
    margin: 0 0 0 0;
}

Added code-docs/design.scrbl version [3cfd26b5].













































































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

@(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}
}

Modified code-docs/main.scrbl from [6cbd40b5] to [40a6e0fc].

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

@author{Joel Dueck}

These are my notes about the internals of the Local Yarn source code. In other words, a personal
reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
wiki for info about deployment, etc.


You’ll get the most out of these notes if you have read @other-doc['(lib
"pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.

If you’re viewing these notes on the Fossil repository, note that these pages are heavily
interlinked with the central Racket documentation at @tt{docs.racket-lang.org}, which are written
and maintained by others. Links on those pages that lead outside of that domain will not work within

this repo’s “Code Docs” frame, due to the repository’s
@ext-link["https://content-security-policy.com"]{content security policy}. To follow such links,
right-click and open the link in a new tab or window.





































@local-table-of-contents[]



@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"]








<



|
|
|
>
|
|
|
>

>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


>
>





<
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


@author{Joel Dueck}

These are my notes about the internals of the Local Yarn source code. In other words, a personal
reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
wiki for info about deployment, etc.


You’ll get the most out of these notes if you have read @other-doc['(lib
"pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.

@margin-note{Note that these pages are heavily interlinked with the central Racket documentation at
@tt{docs.racket-lang.org}, which are written and maintained by others. 

If you’re browsing these docs from within @italic{The Local Yarn}’s main website, and if you follow
links to other Racket documentation, you’ll find that to @emph{other} sites on those pages will not
work (due to the  @ext-link["https://content-security-policy.com"]{content security policy} in
effect when inside a frame). To follow such links, right-click and open the link in a new tab or
window.

You may also wish to @ext-link["#"]{open this page in its own tab.}}

@section{Yarnian @italic{telos}}

The Local Yarn is my garden: a garden of thinking and code. It’s tailored to my needs as a guy who
likes thinking, writing and publishing, isn’t an expert on anything, misses enchantment, and who
likes things to look nice. It’s a place to experiment and solve problems and be creative on several
levels at once. (You’re looking at one of the lower levels right now.)

Whatever gets done here, the idea is to:

@itemlist[
  @item{Invite and reward exploration; entice the visitor to go @italic{further up and further in}}
  
  @item{Make lush, prolific and expert use of language and typography, even obscure or gratuitous
  variants, purely for their own sake}

  @item{Grow and connect new ideas, and maintain older growth}
  ]

Like a garden, @italic{The Local Yarn} has a particular layout, which is described at all levels of
detail in Design and Layout.

@section{Yarnian @italic{cræft}}

New areas are always being designed and added. I try to do some cyclical planning, but most of it
comes from iterative, deeply lazy, center-building iteration. 

Let’s build on the garden metaphor: this place is groomed like a garden. All the lofty notions above
— creative processes, design principles — are, in the end, underpinned by a stable of imperfect old
tools and machines. Anyone who works on the garden must learn and practice their use, understand how
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"]

Modified code-docs/scribble-helpers.rkt from [95058fad] to [d6d57bb0].

1
2
3
4
5
6
7
8
9
10



11
12


13
14
15
16
17
18
19
#lang racket/base

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

;; Convenience/helper functions for this project’s Scribble documentation

(require scribble/core
         scribble/manual/lang
         scribble/html-properties



         (only-in net/uri-codec uri-encode))
(provide (all-defined-out))



(define repo-url/ "https://thelocalyarn.com/cgi-bin/yarncode/")

;; Link to a ticket on the Fossil repository by specifying the ticket ID.
;; The "_parent" target breaks out of the iframe used by the Fossil repo web UI.
(define (ticket id-str)
  (hyperlink (string-append repo-url/ "tktview?name=" id-str)










>
>
>


>
>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#lang racket/base

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

;; Convenience/helper functions for this project’s Scribble documentation

(require scribble/core
         scribble/manual/lang
         scribble/html-properties
         scribble/private/manual-sprop
         scribble/decode
         racket/runtime-path
         (only-in net/uri-codec uri-encode))
(provide (all-defined-out))

(define-runtime-path custom-css "custom.css")

(define repo-url/ "https://thelocalyarn.com/cgi-bin/yarncode/")

;; Link to a ticket on the Fossil repository by specifying the ticket ID.
;; The "_parent" target breaks out of the iframe used by the Fossil repo web UI.
(define (ticket id-str)
  (hyperlink (string-append repo-url/ "tktview?name=" id-str)
41
42
43
44
45
46
47



























             #:style (style #f (list (attributes '((target . "_parent")))))))

(define (responsive-retina-image img-path)
  (image img-path 
         #:scale 0.5
         #:style (style #f (list (attributes '((style . "max-width:100%;height:auto;")))))))



































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
             #:style (style #f (list (attributes '((target . "_parent")))))))

(define (responsive-retina-image img-path)
  (image img-path 
         #:scale 0.5
         #:style (style #f (list (attributes '((style . "max-width:100%;height:auto;")))))))

;;
;; From https://github.com/mbutterick/pollen/blob/master/pollen/scribblings/mb-tools.rkt
;;

(define (terminal . args)
  (compound-paragraph (style "terminal" (list (css-style-addition custom-css) (alt-tag "div")))
                      (list (apply verbatim args))))

(define (cmd . args)
  (elem #:style (style #f (list (color-property "black"))) (tt args)))

(define (fileblock filename . inside)
  (compound-paragraph 
   (style "fileblock" (list* (alt-tag "div") 'multicommand
                             (box-mode "RfileboxBoxT" "RfileboxBoxC" "RfileboxBoxB") 
                             scheme-properties))
   (list
    (paragraph (style "fileblock_filetitle" (list* (alt-tag "div") (box-mode* "RfiletitleBox") scheme-properties))
               (list (make-element
                      (style "fileblock_filename" (list (css-style-addition custom-css)))
                      (if (string? filename)
                          (filepath filename)
                          filename))))
    (compound-paragraph 
     (style "fileblock_filecontent" (list* (alt-tag "div") (box-mode* "RfilecontentBox") scheme-properties))
     (decode-flow inside)))))

Added code-docs/tour.scrbl version [957f21f4].



























>
>
>
>
>
>
>
>
>
>
>
>
>
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.