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

Login
About History Code Code Docs Road Map Issues
Overview
Comment:Clean up HTML Snippets scribble doc
Timelines: family | ancestors | descendants | both | doc-expansion
Files: files | file ages | folders
SHA3-256: e2a5ab964bf68e268fe5a4c7063ffbc9b1c37d7599d9485132e899d82861ef29
User & Date: joel on 2020-02-14 22:46:54
Other Links: branch diff | manifest | tags
Context
2020-02-19
03:28
Further reorg code docs check-in: 82481872 user: joel tags: doc-expansion
2020-02-14
22:46
Clean up HTML Snippets scribble doc check-in: e2a5ab96 user: joel tags: doc-expansion
22:25
Reorganize Pollen and cache stuff in scribble docs check-in: dc332aff user: joel tags: doc-expansion
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Modified code-docs/snippets-html.scrbl from [ca2f5449] to [178dfa09].

︙︙
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

                     racket/contract
                     racket/string
                     pollen/template
                     pollen/pagetree
                     txexpr
                     sugar/coerce))

@title{@filepath{snippets-html.rkt}}

@defmodule["snippets-html.rkt" #:packages ()]

Each “snippet” module provides all the document- and article-level blocks of structural markup
necessary for a particular target output format; this one is for HTML. The idea is that any block of
markup that might be reused across more than one template should be a function.

The functions in the snippets modules follow two conventions in this project:

@itemlist[
  @item{Functions that return strings of HTML have the prefix @tt{html$-}.}
  @item{Such functions do not do any parsing or destructuring of complex objects; every separate
  piece that will be inserted into the template is passed in as a separate argument. This makes it








|



|
|
|








12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

                     racket/contract
                     racket/string
                     pollen/template
                     pollen/pagetree
                     txexpr
                     sugar/coerce))

@title{HTML snippets}

@defmodule["snippets-html.rkt" #:packages ()]

Each “snippet” module provides all (well @emph{most of}) the document- and article-level blocks of
structural markup necessary for a particular target output format; this one is for HTML. The idea is
that any block of markup that might be reused across more than one template should be a function.

The functions in the snippets modules follow two conventions in this project:

@itemlist[
  @item{Functions that return strings of HTML have the prefix @tt{html$-}.}
  @item{Such functions do not do any parsing or destructuring of complex objects; every separate
  piece that will be inserted into the template is passed in as a separate argument. This makes it
︙︙
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
137
138


    <p><b>◊|title|</b><p>
    ◊(->html body-tx)
  })
}

@section{HTML Snippet functions}

@defproc[(html$-page-head [title (or/c string? #f) #f] [close-head? boolean? #t]) non-empty-string?]


Returns the @tt{<head>} section of an HTML document. 

If @racket[_title] is a string it will be used inside the @tt{<title>} tag.

If you want to include additional stuff inside the @tt{<head>}, you can set @racket[_close-head?] to
@racket[#f] to prevent it from including the closing @tt{</head>} tag (you’ll have to add it
yourself).


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

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

If @racket[_body-class] is a non-empty string, its contents will be included in the @tt{class}
attribute of the @tt{<body>} tag.








@defproc[(html$-article-open [pagenode pagenode?] 
                             [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.


@defproc[(html$-article-listing-short [pagenode pagenode?] [pubdate string?] [title string?])
non-empty-string?]

Returns a string of HTML for an article as it would appear in a listing context in “short” form
(date and title only, with link).






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

Returns a string containing the page’s @tt{<footer>} and closing tags.


@defproc[(html$-note-contents [disposition-mark string?] [elems (listof xexpr?)]) non-empty-string?]


Returns a string containing the body-elements of a note converted to HTML. If
@racket[_disposition-mark] is not empty, a @tt{<span>} containing it will be inserted as the first
element of the first block-level element.


@defproc[(html$-note-listing-full [pagenode pagenode?]
                                  [note-id string?] 
                                  [title-html-flow string?]
                                  [date string?]
                                  [contents string?] 
                                  [author string? (default-authorname)] 
                                  [author-url string? ""])
          non-empty-string?]

Returns a string containing the complete HTML markup for a @racket[note], including title, permlink,
date, contents and author, suitable for display outside the context of its parent article.


@defproc[(html$-note-in-article [id string?] 
                                [date string?] 
                                [contents string?] 
                                [author string?]
                                [author-url string?]) non-empty-string?]

Like @racket[html$-note-listing-full], but returns HTML for a @racket[note] suitable for display
inside its parent article.


@defproc[(html$-notes-section [note-htmls string?]) non-empty-string?]

Returns the complete HTML for the @italic{Further Notes} section of an article.


@defproc[(html$-paginate-navlinks [current-page exact-positive-integer?] 
                                  [pagecount exact-positive-integer?]
                                  [basename string?]) string?]

On the “blog”, the articles are split across multiple files: @filepath{blog-pg1.html},
@filepath{blog-pg2.html}, etc. This function provides a string containing HTML for a group of links
that can be given within each file, to link to the pages that come before/after it. 

The links are enclosed within @tt{<li>} tags. It’s up to the calling site to provide the enclosing
@tt{<ul>} tag (in case any custom styling or IDs need to be applied).









|
>

|






|
>
|






>
>
>
>
>
>
>





|





|
>
|




|
>

|



|
>
>
>
>
>
|


|
>
|
>




>








|



>





|



|
>
|


>



|







>

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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

    <p><b>◊|title|</b><p>
    ◊(->html body-tx)
  })
}

@section{HTML Snippet functions}

@defproc[(html$-page-head [title (or/c string? #f) #f] [close-head? boolean? #t])
non-empty-string?]{

Returns the @tt{<head>} section of an HTML document.

If @racket[_title] is a string it will be used inside the @tt{<title>} tag.

If you want to include additional stuff inside the @tt{<head>}, you can set @racket[_close-head?] to
@racket[#f] to prevent it from including the closing @tt{</head>} tag (you’ll have to add it
yourself).
}

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

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

If @racket[_body-class] is a non-empty string, its contents will be included in the @tt{class}
attribute of the @tt{<body>} tag.
}

@defproc[(html$-series-list) non-empty-string?]{

Returns an HTML @tt{<section>} containing a list of all series, grouped by their “plural nouns”. The
grouped list will flow into columns on wider displays.
}

@defproc[(html$-article-open [pagenode pagenode?] 
                             [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.
}

@defproc[(html$-article-listing-short [pagenode pagenode?] [pubdate string?] [title string?])
non-empty-string?]{

Returns a string of HTML for an article as it would appear in a listing context in “short” form
(date and title only, with link).
}

@defproc[(html$-page-footer) non-empty-string?]{
Returns an HTML @tt{<footer>} tag for use at the bottom of each page.
}

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

Returns a string containing the page’s @tt{<footer>} and closing tags.
}

@defproc[(html$-note-contents [disposition-mark string?] [elems (listof xexpr?)])
non-empty-string?]{

Returns a string containing the body-elements of a note converted to HTML. If
@racket[_disposition-mark] is not empty, a @tt{<span>} containing it will be inserted as the first
element of the first block-level element.
}

@defproc[(html$-note-listing-full [pagenode pagenode?]
                                  [note-id string?] 
                                  [title-html-flow string?]
                                  [date string?]
                                  [contents string?] 
                                  [author string? (default-authorname)] 
                                  [author-url string? ""])
          non-empty-string?]{

Returns a string containing the complete HTML markup for a @racket[note], including title, permlink,
date, contents and author, suitable for display outside the context of its parent article.
}

@defproc[(html$-note-in-article [id string?] 
                                [date string?] 
                                [contents string?] 
                                [author string?]
                                [author-url string?]) non-empty-string?]{

Like @racket[html$-note-listing-full], but returns HTML for a @racket[note] suitable for display
inside its parent article.
}

@defproc[(html$-notes-section [note-htmls string?]) non-empty-string?]{

Returns the complete HTML for the @italic{Further Notes} section of an article.
}

@defproc[(html$-paginate-navlinks [current-page exact-positive-integer?] 
                                  [pagecount exact-positive-integer?]
                                  [basename string?]) string?]{

On the “blog”, the articles are split across multiple files: @filepath{blog-pg1.html},
@filepath{blog-pg2.html}, etc. This function provides a string containing HTML for a group of links
that can be given within each file, to link to the pages that come before/after it. 

The links are enclosed within @tt{<li>} tags. It’s up to the calling site to provide the enclosing
@tt{<ul>} tag (in case any custom styling or IDs need to be applied).
}

This page was generated in about 0.009s by Fossil 2.19 [318ab802db] 2022-05-27 02:05:21