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

Overview
Comment:More work on Scribble docs
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: a4c851a4152449d55495005bc44998f294d6f801922e86d1ccd62b91e8e6a262
User & Date: joel on 2019-02-18 20:05:43
Other Links: manifest | tags
Context
2019-02-23
01:39
Check for existing connection in init-db check-in: bd5c6a94 user: joel tags: trunk
2019-02-18
20:05
More work on Scribble docs check-in: a4c851a4 user: joel tags: trunk
2019-02-17
23:03
Add to scribble documentation check-in: 8f6399e3 user: joel tags: trunk
Changes

Modified code-docs/dust.scrbl from [0653072f] to [785c90f0].

63
64
65
66
67
68
69




70
71
72
73




74
75
76
77
78
79
80
...
118
119
120
121
122
123
124


125
126
127
128
129
130

131
132
133
134
135
136
137
Look up a value in @code{(current-metas)} that may or may not be present, returning the value of
@racket[_missing-expr] if it’s not there.

@defproc[(tx-strs [tx txexpr?]) string?]

Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and concatenates them together.





@defproc[(first-words [str string?] [n exact-nonnegative-integer?]) string?]

Returns a string containing the first @racket[_n] words of @racket[_str], removing any trailing
punctuation.





@section{Article parsers and helpers}

@defproc[(default-title [date string?]) string?]

Titles are not required for articles, but there are contexts where you need something that
serves as a title if one is not present, and that’s what this function supplies.
................................................................................

@defproc[(notes->last-disposition-values [txprs (listof txexpr?)]) any]

Given a list of tagged X-expressions (ideally a list of @code{note}s), returns two values: the value
of the @racket['disposition] attribute for the last note that contains one, and the ID of that note.

@examples[#:eval dust-eval


(define notelist (list '(note [[date "2018-02-19"] [disposition "* problematic"]] "First note")
                       '(note [[date "2018-03-19"]] "Second note")
                       '(note [[date "2018-04-19"] [disposition "† recanted"]] "Third note")))
(notes->last-disposition-values notelist)]

;; Extract the last disposition (if any), and the ID of the disposing note, out of a list of notes


@section{Date formatters}

@defproc[(ymd->english [ymd-string string?]) string?]

Converts a date-string of the form @code{"YYYY-MM-DD"} to a string of the form @code{"Monthname D,
YYYY"}. 







>
>
>
>



|
>
>
>
>







 







>
>
|
|
|
<

<
>







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
...
126
127
128
129
130
131
132
133
134
135
136
137

138

139
140
141
142
143
144
145
146
Look up a value in @code{(current-metas)} that may or may not be present, returning the value of
@racket[_missing-expr] if it’s not there.

@defproc[(tx-strs [tx txexpr?]) string?]

Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and concatenates them together.

@examples[#:eval dust-eval
(tx-strs '(p [[class "intro"]] 
             (em "I’m not opening the safe") ", Wilson remembers thinking."))]

@defproc[(first-words [str string?] [n exact-nonnegative-integer?]) string?]

Returns a string containing the first @racket[_n] words of @racket[_str], removing any trailing
punctuation. It will trip on opening punctuation or punctuation surrounded by spaces.

@examples[#:eval dust-eval
(first-words "Another time, perhaps." 2)
(first-words "‘One problem’ – it don’t always do punctuation right." 3)]

@section{Article parsers and helpers}

@defproc[(default-title [date string?]) string?]

Titles are not required for articles, but there are contexts where you need something that
serves as a title if one is not present, and that’s what this function supplies.
................................................................................

@defproc[(notes->last-disposition-values [txprs (listof txexpr?)]) any]

Given a list of tagged X-expressions (ideally a list of @code{note}s), returns two values: the value
of the @racket['disposition] attribute for the last note that contains one, and the ID of that note.

@examples[#:eval dust-eval
(define notelist 
  (list 
    '(note [[date "2018-02-19"] [disposition "* problematic"]] "First note")
    '(note [[date "2018-03-19"]] "Second note")
    '(note [[date "2018-04-19"] [disposition "† recanted"]] "Third note")))



(notes->last-disposition-values notelist)]

@section{Date formatters}

@defproc[(ymd->english [ymd-string string?]) string?]

Converts a date-string of the form @code{"YYYY-MM-DD"} to a string of the form @code{"Monthname D,
YYYY"}. 

Modified code-docs/pollen.scrbl from [62bb480c] to [85e2b6f4].

5
6
7
8
9
10
11

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
..
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
...
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@; Copying and distribution of this file, with or without modification,
@; are permitted in any medium without royalty provided the copyright
@; notice and this notice are preserved.  This file is offered as-is,
@; without any warranty.

@(require "scribble-helpers.rkt")
@(require (for-label "../pollen.rkt"

                     racket/base
                     txexpr
                     pollen/tag
                     pollen/setup
                     pollen/core
                     sugar/coerce))

@title{@filepath{pollen.rkt}}

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

The file @filepath{pollen.rkt} is implicitly @code{require}d in every template and every @code{#lang
pollen} file in the project. It defines the markup for all Pollen documents, and also re-provides
everything provided by @code{crystalize.rkt}.

................................................................................

@defproc[(p [element xexpr?] ...) txexpr?]

Wrap text in a paragraph. You almost never need to use this tag explicitly; 
just separate paragraphs by an empty line.

Single newlines within a paragraph will be replaced by spaces, allowing you to use
@link["https://scott.mn/2014/02/21/semantic_linewrapping/"]{semantic line wrapping}.

@defproc[(newthought [element xexpr?] ...) txexpr?]

An inline style intended for the first few words of the first paragraph in a new section. Applies
a “small caps” style to the text. Any paragraph containing a @code{newthought} tag is given extra
vertical leading.

................................................................................
Add a note to the “Further Notes” section of the article. Notes are like blog comments but are
more rare and powerful; see @wiki{Differences from blogs}.

The @code{#:date} attribute is required and must be of the form @tt{YYYY-MM-DD}.

The @code{#:author} and @code{#:author-url} attributes can be used to credit notes from other
people. If the @code{#:author} attribute is not supplied then the value of @code{default-authorname}
from @filepath{dust.rkt} is used.

The @code{#:disposition} attribute is used for notes that update or alter the whole disposition of
the article. It must be a string of the form @racket[_mark _past-tense-verb], where @racket[_mark]
is a symbol suitable for use as a marker, such as * or †, and @racket[_past-tense-verb] is the word
you want used to describe the article’s current state. An article stating a metaphysical position
might later be marked “recanted”; a prophecy or prediction might be marked “fulfilled”.








>







|







 







|







 







|







5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
...
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@; Copying and distribution of this file, with or without modification,
@; are permitted in any medium without royalty provided the copyright
@; notice and this notice are preserved.  This file is offered as-is,
@; without any warranty.

@(require "scribble-helpers.rkt")
@(require (for-label "../pollen.rkt"
                     "../dust.rkt"
                     racket/base
                     txexpr
                     pollen/tag
                     pollen/setup
                     pollen/core
                     sugar/coerce))

@title[#:tag "pollen-rkt"]{@filepath{pollen.rkt}}

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

The file @filepath{pollen.rkt} is implicitly @code{require}d in every template and every @code{#lang
pollen} file in the project. It defines the markup for all Pollen documents, and also re-provides
everything provided by @code{crystalize.rkt}.

................................................................................

@defproc[(p [element xexpr?] ...) txexpr?]

Wrap text in a paragraph. You almost never need to use this tag explicitly; 
just separate paragraphs by an empty line.

Single newlines within a paragraph will be replaced by spaces, allowing you to use
@ext-link["https://scott.mn/2014/02/21/semantic_linewrapping/"]{semantic line wrapping}.

@defproc[(newthought [element xexpr?] ...) txexpr?]

An inline style intended for the first few words of the first paragraph in a new section. Applies
a “small caps” style to the text. Any paragraph containing a @code{newthought} tag is given extra
vertical leading.

................................................................................
Add a note to the “Further Notes” section of the article. Notes are like blog comments but are
more rare and powerful; see @wiki{Differences from blogs}.

The @code{#:date} attribute is required and must be of the form @tt{YYYY-MM-DD}.

The @code{#:author} and @code{#:author-url} attributes can be used to credit notes from other
people. If the @code{#:author} attribute is not supplied then the value of @code{default-authorname}
is used.

The @code{#:disposition} attribute is used for notes that update or alter the whole disposition of
the article. It must be a string of the form @racket[_mark _past-tense-verb], where @racket[_mark]
is a symbol suitable for use as a marker, such as * or †, and @racket[_past-tense-verb] is the word
you want used to describe the article’s current state. An article stating a metaphysical position
might later be marked “recanted”; a prophecy or prediction might be marked “fulfilled”.

Modified code-docs/scribble-helpers.rkt from [55b6ba42] to [20648ff4].

41
42
43
44
45
46
47
48
49
50
;; Link to a wiki page on the Fossil repository by specifying the title
(define (wiki title)
  (hyperlink (string-append repo-url/ "wiki?name=" (uri-encode title))
             title
             #:style (style #f (list (attributes '((target . "_parent")))))))

(define (ext-link url-str . elems)
  (keyword-apply hyperlink '(#:style) (list (style #f (list (attributes '((target . "_parent")))))) 
         url-str
         elems))







|


41
42
43
44
45
46
47
48
49
50
;; Link to a wiki page on the Fossil repository by specifying the title
(define (wiki title)
  (hyperlink (string-append repo-url/ "wiki?name=" (uri-encode title))
             title
             #:style (style #f (list (attributes '((target . "_parent")))))))

(define (ext-link url-str . elems)
  (keyword-apply hyperlink '(#:style) (list (style #f (list (attributes '((target . "_blank")))))) 
         url-str
         elems))

Modified code-docs/scribble-iframe.html from [6fed1c69] to [5bb7d4b4].

1

2
3

4
5
6
7
8
<div class='fossil-doc' data-title='Code Documentation'>

    <iframe id='scribble' src="index.html" class="embedded-docs">
    </iframe>

</div>

    <script>
        document.getElementById('scribble').src = "index.html?rand=" + new Date()/1;
    </script>
|
>
|
|
>



|

1
2
3
4
5
6
7
8
9
10
<div class='fossil-doc' data-title='Code Documentation' >
    <div class='iframe-surround'>
        <iframe id='scribble' src="index.html" class="embedded-docs">
        </iframe>
    </div>
</div>

    <script>
        document.getElementById('scribble').src = "index.html?n=" + new Date()/1;
    </script>