◊(Local Yarn Code "Changes To Ideas Scratchpad")

Changes to "Ideas Scratchpad" between 2021-11-28 16:01:13 and 2021-12-31 04:23:46

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


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

-
+

-
+

-
+

-
+
+
+
+
+
+
+

+
-
+
+

-
+

-
+
-
-

-
+

-
+

-
-
-
-
-
-
+
+
+
+
+

-
+

-
+

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

-
+
# Ideas for rebooting the project
# Cross-references

I’m a little better at this than I was when I started the project, and I have some ideas that will make the site simpler, quicker, and more elegant.
A cross-reference has a _source_ (the article and particular place in that article where the reference appears) and a _destination_ (the place to which the reference directs you). The destination is always a particular place within an article.

The SQLite cache would be removed.
## Index entries

Articles would keep all the values needed to render themselves and their notes in their metas, rather than reparsing the doc at render time.
Entries in the index have these properties:

Articles and notes would compile to an AST rather than directly to HTML or LaTeX or MP3 or whatever (no “poly tags” required). 
* A name, which is what the reader sees, and which preserves information such as case and formatting.
* An entry and subentry
* A key, which by default is a normalization of the name according to these steps:
    1. Strip formatting if present, and convert to lowercase
    2. If the name originally contained no formatting, replace the first comma-space with an exclamation mark (which marks the entry/subentry boundary)
    3. If the name originally contained no formatting, in the entry portion replace a trailing “ies” with “y” and remove a trailing “s”
    4. In both the entry and subentry portions, delete all non-alphanumeric characters

Index entries are collected together when they have the same *name*, not when they have the same key.  (?)
At compile time, an article would serialize each of its notes, in the form of a listing prefab struct, to a separate .rktd file in a subfolder. The filename would be formatted as YYYYMMDDHHMMSS_id to allow for easy sorting by datetime.

## Pins

After all updated articles are compiled, an indexer (`yarn/system` below) would collect these sort tables and serialize them to .rktd files:
A *pin* creates a cross-reference whose source is an entry in the index and whose destination is the place where the pin appears.

  * Dictionary of main index entries → subentry  + list of link targets
A pin specifies the *name* of the index entry that should tie back to it:
  * Hash table of series → articles
  * Ordered lists of all articles and notes by date

## Cross-references
> Below is a ◊pin["Doors, colors of"]{doors in our house and their colors}…

There would be a clear cross-referencing model:
The above adds a link to that passage in the text from an index subentry “Doors, colors of”, which appears under the entry “doors“. The name of the index entry is "Doors, colors of" and its key is “door!colorsof”.

* A *pin* is an index entry. In a body of text, it links to the index entry.
* A *def* is also a pin that can be cross-referenced directly in another text. 
    * In a body of text, it is italicized, prefixed with a manicule, and links to the index entry. 
    * Every title of an article becomes its own def. 
* A *ref* simply links directly to a *def* (not to the index).
    * Ref links get resolved at template render time.
To create a pin for a titled work:

> My favorite book is ◊pin{◊cite{Jonathan Strange and Mr Norrell}}.

For the index entry that will link to the above passage, the name is ◊cite{Jonathan Strange and Mr Norrell} and the key is “jonathanstrangeandmrnorrell”.

Rendered articles will be able to include previous/next links for other articles in their series
### Defs

## Organization
A *def* is a kind of pin that, in addition to creating a cross-reference from an index entry, can be linked directly from another article. Like pins, defs specify the names of the index entries that point back to them, but they modify the names provided.

* thelocalyarn
    * articles
    * series
    * templates
    * img
    * web  (CSS, JS, fonts, etc)
    * yarn-lib
        * markup  (anything needed by articles at compile time)
        * struct     (AST)
        * system  (for gathering info from/referring to other files)
        * render
            * base
            * html
            * latex
            * mp3
    * yarn-doc
    * pollen.rkt
    * blog.rkt
    * feed.rkt
    * index.rkt
    * crossref.rkt
    * makefile
> A ◊def["Doors"]{door} is an articulating barrier.

The above adds a link to that place in the text from an index subentry “Doors, definition of” — the subentry is added automatically. The key of the entry is “door!definitionof”.

**Formatting:** in a body of text, a def is italicized, and links back to its index entry.

### Titles

A title in an article works like a def, but it does not automatically tack on the “definition of” subentry and it surrounds its contents with a ◊cite tag.

> ◊title{Writing books, explained}

The above adds a link to its article from an index subentry with the name “◊cite{Writing books}” and the key “writingbooksexplained”.

**Formatting:** A title links back to its index entry.

## Refs

A *ref* links directly to a *def* (not to the index). However, it also adds a cross-reference from an index entry back to itself.

> Install the ◊ref{doors} so that they can be opened from the inside.

The above creates a direct link (resolved at template render time) to the def tag for the key “door” in whichever article it appears. At the same time, a link to the ref tag is added from an index entry that has the *key* (?) of “door”.


Templates will `(require yarn/html)` or whichever module is needed for the output format.