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

Login
About History Code Code Docs Road Map Issues
Overview
Comment:Clarify poly-branch macro names (resolves [fbbb5ed9])
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 6b60dccb0940a24f8394073630ad0cbf96e0810f7622a80778c118bf92e815a7
User & Date: joel on 2019-03-16 20:44:29
Other Links: manifest | tags
References
2019-03-16
20:57 • Closed ticket [fbbb5ed9]: Macros in pollen.rkt are redundant plus 4 other changes artifact: 614c1d5e user: joel
Context
2019-03-16
21:22
Fixes for new use of poly-branch macros check-in: 7bb712ef user: joel tags: trunk
20:44
Clarify poly-branch macro names (resolves [fbbb5ed9]) check-in: 6b60dccb user: joel tags: trunk
20:43
Change styles for in-article note headings check-in: fc861d47 user: joel tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Modified code-docs/pollen.scrbl from [dd25189e] to [3dd46911].

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

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 (id symbol?))
 (-> txexpr?)]
Define a new tag function (using @racket[define-tag-function]) for @racket[_id], which will
automatically pass all of its attributes and elements to a tag function whose name is the value
returned by @racket[current-poly-target], followed by a hyphen, followed by @racket[_id]. 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]
submodule. If you do not,  you will get “unbound identifier” errors at expansion time.

The convention in this project is to define and provide these branch functions in separate files:
see, e.g., @filepath{tags-html.rkt}.




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

@margin-note{In writing this documentation it dawned on me that I only need one of these macros. So
at some point the current @code{poly-branch-tag} will be eliminated, and @code{poly-branch-func}
then renamed to @code{poly-branch-tag}. See @ticket{fbbb5ed9}.}



Like @racket[poly-branch-tag], but uses @racket[define] instead of @racket[define-tag-function].


@section{Markup reference}

These are the tags that can be used in any of @italic{The Local Yarn}’s Pollen documents (articles,
etc).

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








|

|
|
|
|
|
|



|




>
>
>

|


<
<
|
>

>
|
>








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


65
66
67
68
69
70
71
72
73
74
75
76
77

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]
submodule. If you do not, you will get “unbound identifier” errors at expansion time.

The convention in this project is to define and provide these branch functions in separate files:
see, e.g., @filepath{tags-html.rkt}.

Functions defined with this macro @emph{do not} accept keyword arguments. If you need keyword
arguments, see @racket[poly-branch-kwargs-tag].

@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.

@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.}

@section{Markup reference}

These are the tags that can be used in any of @italic{The Local Yarn}’s Pollen documents (articles,
etc).

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

Modified pollen.rkt from [b8fa2245] to [c42202f2].

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

    (map resolve-module-path '("tags-html.rkt"
                               "snippets-html.rkt"
                               "dust.rkt"
                               "crystalize.rkt"))))

;; Macro for defining tag functions that automatically branch based on the 
;; current output format and the list of poly-targets in the setup module.

;; 
(define-syntax (poly-branch-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list (setup:poly-targets))])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define-tag-function (TAG attributes elems)
           (define args (cons attributes elems))
           (case (current-poly-target)
             [(POLY-TARGET) (apply POLY-FUNC args)] ... 
             [else (apply DEFAULT-FUNC args)])))]))

;; Like above, but uses define instead of define-tag-function, so arguments
;; are given ‘straight’ rather than being parsed out as attributes.
;;
(define-syntax (poly-branch-func stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list (setup:poly-targets))])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define (TAG . args)








>
|
|












|
|

|








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

    (map resolve-module-path '("tags-html.rkt"
                               "snippets-html.rkt"
                               "dust.rkt"
                               "crystalize.rkt"))))

;; Macro for defining tag functions that automatically branch based on the 
;; current output format and the list of poly-targets in the setup module.
;; Use this macro when you know you will need keyword arguments.
;;
(define-syntax (poly-branch-kwargs-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list (setup:poly-targets))])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define-tag-function (TAG attributes elems)
           (define args (cons attributes elems))
           (case (current-poly-target)
             [(POLY-TARGET) (apply POLY-FUNC args)] ... 
             [else (apply DEFAULT-FUNC args)])))]))

;; Like above, but uses `define` instead of `define-tag-function`.
;; Use this when you know you will not need keyword arguments.
;;
(define-syntax (poly-branch-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list (setup:poly-targets))])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define (TAG . args)
︙︙
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

(poly-branch-tag newthought)
(poly-branch-tag smallcaps)
(poly-branch-tag center)
(poly-branch-tag section)
(poly-branch-tag subsection)
(poly-branch-tag code)
(poly-branch-tag blockcode)
(poly-branch-tag verse)          ; [#:title ""] [#:italic "no"]

(poly-branch-func link)
(poly-branch-func url)
(poly-branch-func fn)
(poly-branch-func fndef)

(poly-branch-tag note)

;; Not yet implemented
; (poly-branch-tag table)         ; #:columns ""
; (poly-branch-tag inline-math)
; (poly-branch-tag margin-note)
; (poly-branch-tag noun)
; (poly-branch-func index-entry entry)








|

|
|
|
|

|








98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

(poly-branch-tag newthought)
(poly-branch-tag smallcaps)
(poly-branch-tag center)
(poly-branch-tag section)
(poly-branch-tag subsection)
(poly-branch-tag code)
(poly-branch-tag blockcode)
(poly-branch-kwargs-tag verse)          ; [#:title ""] [#:italic "no"]

(poly-branch-tag link)
(poly-branch-tag url)
(poly-branch-tag fn)
(poly-branch-tag fndef)

(poly-branch-kwargs-tag note)

;; Not yet implemented
; (poly-branch-tag table)         ; #:columns ""
; (poly-branch-tag inline-math)
; (poly-branch-tag margin-note)
; (poly-branch-tag noun)
; (poly-branch-func index-entry entry)
︙︙

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