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

#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 "scribble-helpers.rkt"
          scribble/example)

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

@(define dust-eval (make-base-eval))
@(dust-eval '(require "dust.rkt"))

@title{@filepath{dust.rkt}}

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

This is where I put constants and helper functions that are needed pretty much everywhere in the
project. In a simpler project these would go in @filepath{pollen.rkt} but here I have other modules
sitting “behind” that one in the @tt{require} chain.

@section{Constants}

@defthing[default-authorname string? #:value "Joel Dueck"]

Used as the default author name for @code{note}s, and (possibly in the future) for articles
generally.

@defthing[series-path/ path-string? #:value "series/"]

The path of the folder that contains the Pollen documents defining Series, relative to the project’s
document root.

@section{Metas and @code{txexpr}s}

@defproc[(attr-present? [name symbol?] [attrs (listof pair?)]) boolean?]

Shortsightedly redundant to @code{attrs-have-key?}. Returns @code{#t} if @racket[_name] is one of
the attributes present in @racket[_attrs], otherwise returns @code{#f}. 

@defproc[(maybe-attr [key symbol?] [attrs txexpr-attrs?] [missing-expr any/c ""]) any/c]

Find the value of @racket[_key] in the supplied list of attributes, returning the value of
@racket[_missing-expr] if it’s not there.

I had to write this because @racket[attr-ref] wants a whole tagged X-expression (not just the
attributes); also, by default it raises an exception when @racket[_key] is missing, rather than
returning an empty string.

@defproc[(maybe-meta [key symbolish?] [missing-expr any/c ""]) any/c]

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.

@examples[#:eval dust-eval
(default-title "2018-02-19")]

@defproc[(series-pagenode) pagenode?]

If @code{(current-metas)} has the key @racket['series], converts its value to the pagenode pointing to
that series, otherwise returns @racket['||].

@defproc[(series-noun) string?]

If @code{(current-metas)} has the key @racket['series], and if the corresponding series defines a meta
value for @racket['noun-singular], then return it, otherwise return @racket[""].

@defproc[(series-title) string?]

If @code{(current-metas)} has the key @racket['series], and if the corresponding series defines a meta
value for @racket['title], then return it, otherwise return @racket[""].

@defproc[(disposition-values [str string?]) any]

Given a string @racket[_str], returns two values: the portion of the string coming before the first
space, and the rest of the string.

@examples[#:eval dust-eval
(disposition-values "* thoroughly recanted")]

@defproc[(build-note-id [tx txexpr?]) non-empty-string?]

Given a @code{note} tagged X-expression, returns an identifier string to uniquely identify that note
within an article. This identifier is used as an anchor link in the note’s HTML, and as part of the
note’s primary key in the SQLite cache database.

@examples[#:eval dust-eval
(build-note-id '(note [[date "2018-02-19"]] "This is an example note"))
(build-note-id '(note [[date "2018-03-19"] [author "Dean"]] "Different author!"))
]

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

If the day number is missing from @racket[_ymd-string], the first day of the month is assumed. If
the month number is also missing, January is asssumed. If the string cannot otherwise be parsed as
a date, an exception is raised.

If any spaces are present in @racket[_ymd-string], everything after the first space is ignored.

@defproc[(ymd->dateformat [ymd_string string?] [dateformat string?]) string?]

Converts a date-string of the form @code{"YYYY-MM-DD"} to another string with the same date
formatted according to @racket[_dateformat]. The
@ext-link["http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table"]{pattern syntax
of the date format} comes from the Unicode CLDR.

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

@; Scribble source for the main page of the code documents.

@title{Local Yarn: source code notes}

@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. In other words, a personal
reference, rather than a tutorial. You’ll get the most out of these notes if you have read
@other-doc['(lib "pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.

If viewing these notes on the Fossil repository, links that lead out to sites other than
@tt{docs.racket-lang.org} will not work within the “Code Docs” frame, due to the repository’s
@link["https://content-security-policy.com"]{content security policy}. To follow such links,
right-click and open the link in a new tab or window.


@local-table-of-contents[]

@include-section["pollen.scrbl"]  @; pollen.rkt
@include-section["dust.scrbl"]    @; dust.rkt

#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 "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}.

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

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

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.

Rule of thumb: within an article, use either @code{section}/@code{subsection} or @code{newthought}
to separate sections of text, but not both. Even better, keep it consistent across articles within
a series.

If you just need small caps without affecting the paragraph, use @code{smallcaps}.

@deftogether[(@defproc[(section    [element xexpr?] ...) txexpr?]
              @defproc[(subsection [element xexpr?] ...) txexpr?])]

Create second- and third-level headings, respectively. This is counting the article's title as the
first-level header (even if the current article has no title).

@deftogether[(@defproc[(link [link-id stringish?] [link-text xexpr?]) txexpr?]
              @defproc[(url  [link-id stringish?] [url string?]) void?])]

All hyperlinks are specified reference-style. So, to link some text, use the @code{link} tag with
an identifier, which can be a string, symbol or number. Elsewhere in the text, use @code{url} with
the same identifier to specify the URL:

@codeblock|{
  #lang pollen
  If you need help, ◊link[1]{Google it}.

  ◊url[1]{https://google.com}
}|

The @code{url} tag for a given identifier may be placed anywhere in the document, even before it is
referenced. If you create a @code{link} for an identifier that has no corresponding @code{url},
a @code{"Missing reference: [link-id]"} message will be substituted for the URL. Conversely, 
creating a @code{url} that is never referenced will produce no output and no warnings or errors.

@deftogether[(@defproc[(fn    [fn-id stringish?]) txexpr?]
              @defproc[(fndef [fn-id stringish?] [elements xexpr?] ...) txexpr?])]

As with hyperlinks, footnotes are specified reference-style. In the output, footnotes will be
numbered according to the order in which their identifiers are referenced in the source document.

Example:

@codeblock|{
  #lang pollen
  Shoeless Joe Jackson was one of the best players of all time◊fn[1].

  ◊fndef[1]{But he might have lost the 1919 World Series on purpose.}
}|

You can refer to a given footnote definition more than once.

The @code{fndef} for a given id may be placed anywhere in the source document, even before it is
referenced. If you create a @code{fn} reference without a corresponding @code{fndef},
a @code{"Missing footnote definition!"} message will be substituted for the footnote text.
Conversely, creating a @code{fndef} that is never referenced will produce no output, warning or
error.

@defproc[(note [#:date date-str non-empty-string?]
               [#:author author string? ""]
               [#:author-url author-url string? ""]
               [#:disposition disp-str string? ""]) txexpr?]

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

@codeblock|{
#lang pollen

◊note[#:date "2019-02-19" #:disposition "✓ verified"]{I wasn’t sure, but now I am.}
}|


If more than one note contains a @code{disposition} attribute, the one from the most recent note is
the one used.

Some caveats (for now):

@itemlist[
  @item{Avoid defining new footnotes using @code{fndef} inside a @code{note}; these footnotes will
  be placed into the main footnote section of the article, which is probably not what you want.}
]

@defproc[(verse [#:title title string? ""] [#:italic? italic boolean? #f] [element xexpr?] ...)
         txexpr?]

Typeset contents as poetry, with line breaks preserved and the block centered on the longest line.
To set the whole block in italic, use @code{#:italic? #t} — otherwise, use @code{i} within the
block.

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

Surrounds a block quotation. To cite a source, include a @code{footer} tag at the bottom.

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

Typeset contents as a block of code using a monospace font. Line breaks are preserved.

@deftogether[(@defproc[(i      [element xexpr?] ...) txexpr?]
              @defproc[(em     [element xexpr?] ...) txexpr?]
              @defproc[(b      [element xexpr?] ...) txexpr?]
              @defproc[(strong [element xexpr?] ...) txexpr?]
              @defproc[(strike [element xexpr?] ...) txexpr?]
              @defproc[(ol     [element xexpr?] ...) txexpr?]
              @defproc[(ul     [element xexpr?] ...) txexpr?]
              @defproc[(item   [element xexpr?] ...) txexpr?]
              @defproc[(sup    [element xexpr?] ...) txexpr?]
              @defproc[(smallcaps [element xexpr?] ...) txexpr?]
              @defproc[(code   [element xexpr?] ...) txexpr?])]
Work pretty much how you’d expect.

@section{Convenience macros}

@defform[(for/s thing-id listofthings result-exprs ...)
         #:contracts ([listofthings (listof any/c)])]

A shorthand form for Pollen’s @code{for/splice} that uses far fewer brackets when you’re only
iterating through a single list.

@codeblock|{
#lang pollen

◊for/s[x '(7 8 9)]{Now once for number ◊x}

◊;Above line is shorthand for this one:
◊for/splice[[(x (in-list '(7 8 9)))]]{Now once for number ◊x}
}|

#lang racket/base

;; Copyright (c) 2018 Joel Dueck.
;;
;; Licensed under the Apache License, Version 2.0 (the "License");
;; you may not use this file except in compliance with the License.
;; A copy of the License is included with this source code, in the
;; file "LICENSE.txt".
;; You may also obtain a copy of the License at
;;
;;       http://www.apache.org/licenses/LICENSE-2.0
;;
;; Unless required by applicable law or agreed to in writing, software
;; distributed under the License is distributed on an "AS IS" BASIS,
;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
;; See the License for the specific language governing permissions and
;; limitations under the License.
;;
;; Author contact information:
;;   joel@jdueck.net
;;   https://joeldueck.com
;; -------------------------------------------------------------------------

;; Convenience/helper functions for this project’s Scribble documentation

(require scribble/core
         scribble/manual/lang
         scribble/html-properties
         (only-in net/uri-codec uri-encode))
(provide (all-defined-out))

(define repo-url/ "https://thelocalyarn.com/cgi-bin/yarncode/")

;; Link to a ticket on the Fossil repository by specifying the ticket ID
(define (ticket id-str)
  (hyperlink (string-append repo-url/ "tktview?name=" id-str)
             "ticket "
             (tt id-str)
             #:style (style #f (list (attributes '((target . "_parent")))))))

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