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

Overview
Comment:Update code docs to reflect [47d9eea54]
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: b223c8a52b66243dd98268c73b0bbfad4ddb374f89759ce8822407d707512a80
User & Date: joel on 2020-02-20 08:30:06
Other Links: manifest | tags
Context
2020-02-21
22:43
Build up listing schema, use for RSS feed ([2f082139]) check-in: d3755213 user: joel tags: trunk
2020-02-20
08:30
Update code docs to reflect [47d9eea54] check-in: b223c8a5 user: joel tags: trunk
04:53
Get rid of current-plain-title ([1909139d]) check-in: 47d9eea5 user: joel tags: trunk
Changes

Modified code-docs/crystalize.scrbl from [4df88301] to [ca8a0906].

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

@(require (for-label "../pollen.rkt"
                     "../crystalize.rkt"
                     "../cache.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     txexpr

                     pollen/pagetree))

@title[#:tag "crystalize-rkt"]{Crystalize}

@defmodule["crystalize.rkt" #:packages ()]

“Crystalizing” is an extra layer in between docs and templates that destructures the @tt{doc} and
stores it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to
the cache when their individual pages are rendered. When pulling together listings of articles in
different contexts that need to be filtered and sorted, a SQL query is much faster than trolling
through the Pollen cache for matching docs and regenerating the HTML.

@margin-note{These functions are designed to be used within the template for articles and series,
respectively, so that the cache is updated precisely when the web page is rendered.}

@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]{



Returns a string containing the HTML of @racket[_doc]. 




Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed
and saved to the SQLite cache and saved using @racket[make-cache:article]. If the article specifies
a @racket['series] meta, information about that series is fetched and used in the rendering of the
article. If there are @racket[note]s or @racket[index] tags in the doc, they are parsed and saved
individually to the SQLite cache (using @racket[make-cache:note] and @racket[make-cache:index-entry]
respectively). If any of the notes use the @code{#:disposition} attribute, information about the
disposition is parsed out and used in the rendering of the article.

}

@defproc[(cache-series!) void?]{

Attempts to look up certain values in @racket[current-metas] which we expect to be defined on
a typical series page, and saves them to the cache using @racket[make-cache:series]. If @tt{title}
is not defined in the current metas, you’ll get an error. If any of the others are missing, an empty
string is used.
}








>















|
>

>
|
>
>
>





|
|
|
>








|
>
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
@(require (for-label "../pollen.rkt"
                     "../crystalize.rkt"
                     "../cache.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     txexpr
                     pollen/core
                     pollen/pagetree))

@title[#:tag "crystalize-rkt"]{Crystalize}

@defmodule["crystalize.rkt" #:packages ()]

“Crystalizing” is an extra layer in between docs and templates that destructures the @tt{doc} and
stores it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to
the cache when their individual pages are rendered. When pulling together listings of articles in
different contexts that need to be filtered and sorted, a SQL query is much faster than trolling
through the Pollen cache for matching docs and regenerating the HTML.

@margin-note{These functions are designed to be used within the template for articles and series,
respectively, so that the cache is updated precisely when the web page is rendered.}

@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) 
         (values non-empty-string? non-empty-string?)]{

Returns two values: the “plain” title of the article, and a string containing the full HTML of
@racket[_doc], in that order.

The title is returned separately for use in the HTML @tt{<title>} tag. If the @racket[_doc] doesn’t
specify a title, a provisional title is constructed using @racket[default-title].

Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed
and saved to the SQLite cache and saved using @racket[make-cache:article]. If the article specifies
a @racket['series] meta, information about that series is fetched and used in the rendering of the
article. If there are @racket[note]s or @racket[index] tags in the doc, they are parsed and saved
individually to the SQLite cache (using @racket[make-cache:note] and
@racket[make-cache:index-entry]). If any of the notes use the @code{#:disposition} attribute,
information about the disposition is parsed out and used in the rendering of the article. 

}

@defproc[(cache-series!) void?]{

Attempts to look up certain values in @racket[current-metas] which we expect to be defined on
a typical series page, and saves them to the cache using @racket[make-cache:series]. If @tt{title}
is not defined in the current metas, you’ll get an error. If any of the others are missing, an empty
string is used.

}