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

Overview
Comment:Add makefile and beginnings of code docs
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: e4d9446c5698a2fc3739719dd9db823cbaa292b2c58599e7cee7f40043bace03
User & Date: joel on 2019-02-11 05:15:49
Other Links: manifest | tags
Context
2019-02-17
23:01
Add trailing slash to series-path/ and provide check-in: 63614f2e user: joel tags: trunk
2019-02-11
05:15
Add makefile and beginnings of code docs check-in: e4d9446c user: joel tags: trunk
2019-02-10
20:50
Correct fetching of metadata from 'series' metas check-in: d0e6644b user: joel tags: trunk
Changes

Added code-docs/main.scrbl version [07ec7580].









































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#lang scribble/manual

@; Copyright (c) 2019 Joel Dueck
@;
@; 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.

@title{Local Yarn Codebase}

@author{Joel Dueck}

These are my notes about the internals of the Local Yarn source code. I wrote them mainly so I can quickly bring myself back up to speed after long absences from the code.

This is a @racketmodlink[pollen]{Pollen} project, and it is a bit complicated. At the very least you should have read the @racketmodlink[pollen]{Pollen documentation}, and worked through the tutorials by hand, before delving into this code.

@local-table-of-contents[]

@include-section["pollen.scrbl"]

Added code-docs/pollen.scrbl version [d45c85be].





















































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
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
#lang scribble/manual

@; Copyright (c) 2019 Joel Dueck
@;
@; 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 (for-label "../pollen.rkt"
                     txexpr
                     pollen/tag
                     pollen/setup))

@title{@filepath{pollen.rkt}}

@author{Joel Dueck}

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

The @code{setup} module towards the top of the file is used as described in @racketmodname[pollen/setup].

@section{Defining new tags}

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?)]

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

Added code-docs/scribble-iframe.html version [6fed1c69].

















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

Added makefile version [18748a63].































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Copyright 2019 Joel Dueck
# This file is part of The Local Yarn
# 
# 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.
#


spritz: ## Clear Pollen and Scribble cache
	rm -rf compiled code-docs/compiled articles/compiled series/compiled
	fossil clean code-docs/

scribble: ## Rebuild code documentation and update Fossil repo
	scribble --htmls +m --redirect-main https://docs.racket-lang.org/ code-docs/main.scrbl
	fossil uv rm scribbled/*
	rm -rf scribbled/*
	mv main/* scribbled/
	cp code-docs/scribble-iframe.html scribbled/scribble.html
	rm -rf main
	fossil uv add scribbled/*
	fossil uv sync

# Self-documenting makefile (http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html)
help: ## Displays this help screen
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'

.PHONY: scribble help spritz

.DEFAULT_GOAL := help