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

Overview
Comment:Clean up small errors in code docs. Fixes [3510585b]
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 1787e5b05348fb47558c57a27e3a6e31405fb1f25c2de12502cf8e6b43449dc7
User & Date: joel on 2019-03-20 00:41:23
Other Links: manifest | tags
References
2019-03-20
00:42 Closed ticket [3510585b]: Some function signatures are out of date plus 4 other changes artifact: d18b8af1 user: joel
Context
2019-03-20
01:04
Fix missing cross-ref links [d8b9f6f7] check-in: d439b95f user: joel tags: trunk
00:41
Clean up small errors in code docs. Fixes [3510585b] check-in: 1787e5b0 user: joel tags: trunk
2019-03-19
03:31
Use a tag instead of metas for title. Use default-title consistently. Refine first-words to be smarter about punctutation. Closes [c055cacb] and fixes [b3ade0b7] check-in: e81b4199 user: joel tags: trunk
Changes

Modified code-docs/crystalize.scrbl from [e3f76dfe] to [c3a0a528].

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
article.

I could have made it so the function is called automatically every time Pollen is run. But that
would mean it gets run even when the target is not HTML, which is unnecessary.

@defproc[(crystalize-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]

Returns a string containing the HTML of doc. @margin-note{This is one function that breaks my
convention of using a prefix of @tt{html$-} for functions that return strings of HTML.} Privately,
however, it does a lot of other work. The article is saved to the SQLite cache. 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 in the doc, they are parsed and saved
individually to the SQLite cache. 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[(article-plain-title [pagenode pagenode?]) non-empty-string?]








|
|
|







42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
article.

I could have made it so the function is called automatically every time Pollen is run. But that
would mean it gets run even when the target is not HTML, which is unnecessary.

@defproc[(crystalize-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]

Returns a string containing the HTML of @racket[_doc]. @margin-note{This is one function that breaks
my convention of using a prefix of @tt{html$-} for functions that return strings of HTML.}
Privately, it does a lot of other work. The article is saved to the SQLite cache. 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 in the doc, they are parsed and saved
individually to the SQLite cache. 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[(article-plain-title [pagenode pagenode?]) non-empty-string?]

Modified code-docs/dust.scrbl from [71bc13f3] to [d396f326].

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
..
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

@deftogether[(@defthing[articles-path path-string? #:value "articles"]
              @defthing[series-path   path-string? #:value "series"])]

The path of the folder that contains the Pollen source documents for Articles and Series
respectively, relative to the project’s document root.

@deftogether[(@defthing[articles-pagetree pagetree?]
              @defthing[series-pagetree pagetree?])]

These are project-wide pagetrees: @racket[articles-pagetree] contains a pagenode for every Pollen
document contained in @racket[articles-path], and @racket[series-pagetree] contains a pagenode for
every Pollen document in @racket[series-path]. The pagenodes themselves point to the rendered
@tt{.html} targets of the source documents.

@section{Metas and @code{txexpr}s}
................................................................................
(is-aside? '(q "I am not mad, Sir Topas. I say to you this house is dark."))
(is-aside? '(aside "How smart a lash that speech doth give my Conscience?"))]

@defproc[(first-words [txprs (listof txexpr?)] [n exact-nonnegative-integer?]) string?]

Given a list of tagged X-expressions, returns a string containing the first @racket[_n] words found
in the string elements of @racket[_txprs], or all of the words if there are less than @racket[_n]
words available. Used by @racket[default_title].

This function aims to be smart about punctuation, and equally fast no matter how large the list of
elements that you send it.

@examples[#:eval dust-eval
(define txs-decimals
  '((p "Four score and 7.8 years ago — our fathers etc etc")))







|
|







 







|







41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
..
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

@deftogether[(@defthing[articles-path path-string? #:value "articles"]
              @defthing[series-path   path-string? #:value "series"])]

The path of the folder that contains the Pollen source documents for Articles and Series
respectively, relative to the project’s document root.

@deftogether[(@defproc[(articles-pagetree) pagetree?]
              @defproc[(series-pagetree) pagetree?])]

These are project-wide pagetrees: @racket[articles-pagetree] contains a pagenode for every Pollen
document contained in @racket[articles-path], and @racket[series-pagetree] contains a pagenode for
every Pollen document in @racket[series-path]. The pagenodes themselves point to the rendered
@tt{.html} targets of the source documents.

@section{Metas and @code{txexpr}s}
................................................................................
(is-aside? '(q "I am not mad, Sir Topas. I say to you this house is dark."))
(is-aside? '(aside "How smart a lash that speech doth give my Conscience?"))]

@defproc[(first-words [txprs (listof txexpr?)] [n exact-nonnegative-integer?]) string?]

Given a list of tagged X-expressions, returns a string containing the first @racket[_n] words found
in the string elements of @racket[_txprs], or all of the words if there are less than @racket[_n]
words available. Used by @racket[default-title].

This function aims to be smart about punctuation, and equally fast no matter how large the list of
elements that you send it.

@examples[#:eval dust-eval
(define txs-decimals
  '((p "Four score and 7.8 years ago — our fathers etc etc")))

Modified code-docs/pollen.scrbl from [a5d17272] to [ea32843d].

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
..
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
I use a couple of macros to define tag functions that automatically branch into other functions
depending on the current output target format. This allows me to put the format-specific tag
functions in separate files that have separate places in the dependency chain. So if only the HTML
tag functions have changed and not those for PDF, the makefile can ensure only the HTML files are
rebuilt.

@defproc[#:kind "syntax"
 (poly-branch-tag (tag symbol?))
 (-> txexpr?)]

Defines a new function @racket[_tag] which will automatically pass all of its arguments to a
function whose name is the value returned by @racket[current-poly-target], followed by a hyphen,
followed by @racket[_tag]. So whenever the current output format is @racket['html], the function
defined by @racket[(poly-branch-tag _p)] will branch to a function named @racket[html-p]; when the
current format is @racket['pdf], it will branch to @racket[pdf-p], and so forth.

You @emph{must} define these branch functions separately, and you must define one for @emph{every}
output format included in the definition of @racket[poly-targets] in this file’s @racket[setup]
................................................................................
arguments, see @racket[poly-branch-kwargs-tag].

@margin-note{The thought behind having two macros so similar is that, by cutting out handling for keyword
arguments, @racket[poly-branch-tag] could produce simpler and faster code. I have not verified if
this intuition is meaningful or correct.}

@defproc[#:kind "syntax"
         (poly-branch-kwargs-tag (id symbol?))
         (-> txexpr?)]

Works just like @racket[poly-branch-tag], but uses Pollen’s @racket[define-tag-function] so that
keyword arguments will automatically be parsed as X-expression attributes.

Additionally, the branch functions called from the new function must accept exactly two arguments:
a list of attributes and a list of elements.







|


|







 







|







35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
..
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
I use a couple of macros to define tag functions that automatically branch into other functions
depending on the current output target format. This allows me to put the format-specific tag
functions in separate files that have separate places in the dependency chain. So if only the HTML
tag functions have changed and not those for PDF, the makefile can ensure only the HTML files are
rebuilt.

@defproc[#:kind "syntax"
 (poly-branch-tag (tag-id symbol?))
 (-> txexpr?)]

Defines a new function @racket[_tag-id] which will automatically pass all of its arguments to a
function whose name is the value returned by @racket[current-poly-target], followed by a hyphen,
followed by @racket[_tag]. So whenever the current output format is @racket['html], the function
defined by @racket[(poly-branch-tag _p)] will branch to a function named @racket[html-p]; when the
current format is @racket['pdf], it will branch to @racket[pdf-p], and so forth.

You @emph{must} define these branch functions separately, and you must define one for @emph{every}
output format included in the definition of @racket[poly-targets] in this file’s @racket[setup]
................................................................................
arguments, see @racket[poly-branch-kwargs-tag].

@margin-note{The thought behind having two macros so similar is that, by cutting out handling for keyword
arguments, @racket[poly-branch-tag] could produce simpler and faster code. I have not verified if
this intuition is meaningful or correct.}

@defproc[#:kind "syntax"
         (poly-branch-kwargs-tag (tag-id symbol?))
         (-> txexpr?)]

Works just like @racket[poly-branch-tag], but uses Pollen’s @racket[define-tag-function] so that
keyword arguments will automatically be parsed as X-expression attributes.

Additionally, the branch functions called from the new function must accept exactly two arguments:
a list of attributes and a list of elements.

Modified code-docs/snippets-html.scrbl from [a2ab701d] to [d3b4b700].

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
Returns the @tt{<head>} section of an HTML document.

@defproc[(html$-page-body-open) non-empty-string?]

Returns the opening @tt{<body>} and @tt{<main>} tags and elements that immediately follow, such as
site header, logo and navigation.

@defproc[(html$-article-open [title? boolean?] [title-html-flow string?] [pubdate string?])
non-empty-string?]

Returns the opening @tt{<article>} tag and elements that immediately follow: permlink, publish date,
and opening @tt{<section>} tag.

This function could be smarter, but for now @racket[_title?] determines which HTML markup structure
to use for the article regardless of whether @racket[_title-html-flow] is empty or not.

@defproc[(html$-article-close [footertext string?]) non-empty-string?]

Returns a string containing a closing @tt{<section>} tag, a @tt{<footer>} element containing
@racket[_footertext], and a closing @tt{<article>} tag. If @racket[_footertext] is empty, the
@tt{<footer>} element will be omitted.








|





|
<







58
59
60
61
62
63
64
65
66
67
68
69
70
71

72
73
74
75
76
77
78
Returns the @tt{<head>} section of an HTML document.

@defproc[(html$-page-body-open) non-empty-string?]

Returns the opening @tt{<body>} and @tt{<main>} tags and elements that immediately follow, such as
site header, logo and navigation.

@defproc[(html$-article-open [title-specified-in-doc? boolean?] [title txexpr?] [pubdate string?])
non-empty-string?]

Returns the opening @tt{<article>} tag and elements that immediately follow: permlink, publish date,
and opening @tt{<section>} tag.

The @racket[_title-specified-in-doc?] form changes the HTML markup structure used.


@defproc[(html$-article-close [footertext string?]) non-empty-string?]

Returns a string containing a closing @tt{<section>} tag, a @tt{<footer>} element containing
@racket[_footertext], and a closing @tt{<article>} tag. If @racket[_footertext] is empty, the
@tt{<footer>} element will be omitted.

Modified code-docs/sqlite-tools.scrbl from [de7cfd61] to [4c85eb42].

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@; notice and this notice are preserved.  This file is offered as-is,
@; without any warranty.

@(require "scribble-helpers.rkt"
          scribble/example)

@(require (for-label "../pollen.rkt"
                     "../dust.rkt"
                     racket/base
                     racket/contract
                     db
                     sugar/coerce))

@(define my-eval (make-base-eval))
@(my-eval '(require "sqlite-tools.rkt"))

@title{@filepath{sqlite-tools.rkt}}

@defmodule["sqlite-tools.rkt" #:packages ()]

Provides a very light set of utility functions for managing a single SQLite database. These
functions are completely agnostic as to the database schema. 







<






|







7
8
9
10
11
12
13

14
15
16
17
18
19
20
21
22
23
24
25
26
27
@; notice and this notice are preserved.  This file is offered as-is,
@; without any warranty.

@(require "scribble-helpers.rkt"
          scribble/example)

@(require (for-label "../pollen.rkt"

                     racket/base
                     racket/contract
                     db
                     sugar/coerce))

@(define my-eval (make-base-eval))
@(my-eval '(local-require "sqlite-tools.rkt"))

@title{@filepath{sqlite-tools.rkt}}

@defmodule["sqlite-tools.rkt" #:packages ()]

Provides a very light set of utility functions for managing a single SQLite database. These
functions are completely agnostic as to the database schema.