How does a document fit into the space?

This is what we’re going for.

The left side is reserved. Presumably—everything else being equal—whatever was there before will still be there. So being able to see it will amount to “preserving context,” which is useful for staying oriented.

The right margin is reserved for sidenotes, or blocks (such as figures and code) that may benefit from a greater width than the main text column.

The document view is centered around a column of text, which should be a comfortable reading width, though not quite as wide as a “normal” book.

@require typesetting
@require centering
$flowRems = $readingRems * 2/3
$flowMargin = 2em
centered-block(width: $flowRems)

This establishes what 100% means within the document.

padding $flowMargin
box-sizing border-box
position relative                       // support layering

So with that you can define a “wide” element as occupying half of the viewport’s width, plus and additional half of the document flow’s width.

.wide
	margin-left -2em  // match document padding
	margin-right calc(50% - 50vw)

Special case for the source container.

.org-src-container
	width calc(50vw + 50%)
	box-sizing border-box

// From Tufte
$documentColor = #FFFFF8 // off white towards yellow

The document is a material thing.

@require document_colors
background $documentColor
box-shadow 0 0 .5em

The shadow extends out on all sides, so that the document appears to float above any material below it, regardless of what edge you happen to be looking at.

Now, as the viewport gets smaller, the margins on either side of the main flow will get smaller. When the viewport is narrower than the preferred width, then the flow itself will shrink, and there will be no margins at all.

// Create compositing layer in Chrome
transform translateZ(0)

margin-bottom 2em

But if we’re going “out of the box,” why not go all the way?

.full
	margin 1em calc(50% - 50vw)

With that, you can do the “edge-to-edge” imagery that’s so hot now, without giving up the context.

But for that to look good, it’ll take a little cleaning up.

@require fonts
@require colors
@require document-map-colors
.wide
.full
	box-sizing border-box
	box-shadow 0 0 1em #111
	background $documentMapDarkColor
	background blend($resourcesColor, $documentMapDarkColor, .25)
	border-radius 1em
	overflow hidden
	background-clip border-box

	img
		box-shadow 0 0 1em #111

	p:first-child
		margin-top 0

	// Probably a caption
	p:last-child:not(:first-child)
		body-font()
		color #FFE

@require responsive
+narrow-screen()
	padding 1em

As another pointer to the presence of more material, let’s add to the about region message:

#mission-statement <append>
<span>You can read our <a href="/about/the_project#top-of-paper">philosophy</a>.</span>
</append>

#about <append>
	<section id="the-program">
		<h2>the program</h2>
		<p>willshake.net is a literate program</p>
		<xslt name="program-links" input="/static/doc/documents.xml" />
	</section>
</append>

That assumes the document index has been copied to the web site.

: $(PUBLISHED)/<documents.xml>  \
|> ^o ship document index ^ \
   cp %<documents.xml> %o \
|> $(SITE_DOCS)/documents.xml

Now for that transform:

<xsl:template match="/">
	<ul><xsl:apply-templates /></ul>
</xsl:template>

<!-- Only match documents with titles.  This skips "included" files. -->
<xsl:template match="document[title]">
	<li>
		<a href="/about/{@key}">
			<xsl:value-of select="title" />
			<xsl:if test="description">
				<xsl:text> </xsl:text>
				<span class="description">
					<xsl:value-of select="description" />
				</span>
			</xsl:if>
		</a>
	</li>
</xsl:template>

Part of the value of literate programming is in cross-referencing. As long as we can address locations in the document, we can do so by using links. During HTML export, Org will render inter-document links with the assumption that each document is exported to an equivalently-named .html file. We are instead placing them under /about, with no extension.

<!-- Links to the about documents themselves -->
<xsl:template
		mode="org-copy"
		match="a/@href[
					 '.html' = substring(., string-length(.) - 4, 5)
					 and not(starts-with(., 'http'))]">

	<!-- The link may include a subsystem path, which is ignored for this
	     purpose. -->
	<xsl:variable name="with-path" select="substring-before(., '.html')" />
	<xsl:variable name="file">
		<xsl:for-each select="strings:tokenize($with-path, '/')">
			<xsl:if test="position() = last()">
				<xsl:value-of select="." />
			</xsl:if>
		</xsl:for-each>
	</xsl:variable>

	<!-- Support included documents -->
	<xsl:variable name="name"
								select="substring-before(concat($file, '__'), '__')" />
	<xsl:attribute name="href">
		<xsl:value-of select="concat('/about/', $name)"/>
	</xsl:attribute>
	<<validate document reference>>
</xsl:template>

We just assume that any link ending with .html and not starting with is a link to a document—as long as it doesn’t also start with http, which would indicate that it’s a link to an external site.

Anything in the org document that points to the site folder can be retargeted trivially to its child directory:

<xsl:template mode="org-copy" match="img/@src[starts-with(., '../site/')]">
	<xsl:param name="attribute" select="'src'" />
	<xsl:attribute name="{$attribute}">
		<xsl:value-of select="substring-after(., '../site')"/>
	</xsl:attribute>
</xsl:template>

This will generally be used for images.

The willshake web site lives at https://willshake.net, of course. But when working on willshake, you’ll usually run a local copy of the site, at an address like localhost:8000. But what if a link uses an absolute path to the real domain, like this:

https://willshake.net/plays/AYL/4.1#This_looks

That will take you to a different site, which is not what you want. So we change it to a relative path here,

/plays/AYL/4.1#This_looks

This way, the link will be treated as internal.

You might ask, why not just use a relative path in the first place? Because we also publish the documents to non-web-based formats, such as PDF, where URI’s need to be absolute. This transformation is only for the web.

But if this is only needed for development, why do it in production, too? Because it yields shorter paths where the full address is unnecessary.

<!-- Rebase link paths. -->
<xsl:template mode="org-copy" match="a/@href[starts-with(., 'https://willshake.net/')]">
	<xsl:attribute name="href">
		<xsl:value-of select="substring-after(., 'https://willshake.net')"/>
	</xsl:attribute>
</xsl:template>

h1, h2
	font-weight normal

Sections headings are links to themselves.

<xsl:template mode="org-copy" match="h2|h3|h4|h5|h6">
	<xsl:variable name="id" select="@id" />
	<xsl:copy>
		<xsl:apply-templates mode="org-copy" select="@*" />
		<a href="#{$id}">
			<xsl:apply-templates mode="org-copy" select="node()" />
		</a>
	</xsl:copy>
</xsl:template>

I think “a thousand words” gets a bad rap in that old saying about pictures. I am happy to have both, and I’m not alone.

Number one, it has to be easy to use images from the document, where “use” means that they show up on the site.

And as long as we’re using Org documents, it’s convenient if the image can also be seen while editing. The simplest way to achieve that is to use image references that are relative to the document. But of course that breaks the first priority, since those references will be no good when the document is in another context such as the web site. By rebasing certain paths, we have it both ways.

Give some indication that links are links, which we don’t by default. This should only apply within narrative text.

p, ul, ol, blockquote
	a
		text-decoration underline

Yeah, this doesn’t play well with descenders, and so on.³

This is kind of a temporary measure. Some code blocks (which don’t wrap) are very long and this bubbles up to affect the computed size of the whole layer.

pre
	overflow-x auto

This is more or less for the same reason as above, but it’s less of a hack.

img, object
	max-width 100%

Figure images in documents should be centered horizontally.

figure
	img, object
		display block
		margin 0 auto
	// why this?
	&:not(.marginal)
		img, object
			border-radius .25em

The link is rendered as plain HTML of course.

Block quotes come from other documents—or at least other sources. Here, we make them look like a separate material from the document in which they are quoted.

The risk is that these sheets won’t look like part of the document “flow.” Unlike asides, block quotes are not flow-interrupting; they are supposed to be read in sequence. That’s a downside to this visual cue, which should keep us from using too dramatic of an effect.

blockquote
	line-height 1.25
	box-shadow 0 0 .5em #111        // make a sheet
	// see source block
	background tint($documentColor, 50%)
	padding .5em 2em
	box-sizing content-box
	border-radius 1em
	border-bottom-right-radius 0

We do occasionally quote some verse around here. Org actually has a special construct for it, which differs from a regular blockquote in that line breaks are preserved as written.

.verse
	line-height 1.25
	margin-left 4em

Do we actually use dl’s anywhere?

dt
	font-style italic

As I look over the blocks I’ve demarked, several categories arise:

tbd

Notes (essentially to myself) about unsatisfactory things that are actionable—or should be soon.

apologias

Explanations about (usually) unsatisfactory things that have no immediate or even forseeable remedy.

The tbd’s can always be marginal, because the expectation is that they’ll be removed soon! So you don’t have to worry about how they negotiate a place with other content.

There is another way to look at all of the remaining notes, including the apologias, which is orthogonal to that grouping, and that is whether they must be in the flow or whether they can be marginal.

Another consideration is how long the note is. Longer passages in the margin just don’t work well. It’s not just the fact that absolutely positioned boxes can end up overlapping one another (which you could avoid by judicious use); the length is an indication that it’s probably not really an aside.

It’s possible that with a better layout strategy, there could be a way to preserve the aside-nature of the blocks that are currently longish aside’s, but as things stand, they clearly go back into the document flow.

Just for fun, let’s use dialogs. It’s kind of a zen teacher/student thing. For the structure itself, no extra code is needed. Just by using a DIALOG block,

#+BEGIN_DIALOG
---Who's there?

---Nay, answer me.  Stand and unfold yourself.

---Long live the king.

---Barnardo?

---He.
#+END_DIALOG

Org export will create a div with class dialog. Everything inside of it will be formatted as elsewhere.

To create the back-and-forth effect, the paragraphs are set alternately to the left and right, much like a typical text messaging app.

speaker(set, side)
	p:nth-child({set})
		float side
		text-align side
		border-bottom-{side}-radius 0

Otherwise, they are the same: little speech bubbles.

@require document-map-colors
.dialog
	> p
		margin .25em 0
		padding .5em 1em
		line-height 1.25
		border-radius 1em
		clear both
		max-width 66%
		background lighten($documentMapColor, 80%)

		// Assume first character is a dash, and hide it
		text-indent -1em
		&:first-letter
			color transparent

	&:not(.flipped)
		speaker(odd, left)
		speaker(even, right)

	&.flipped
		speaker(even, left)
		speaker(odd, right)

	// The old "clearfix" trick
	&:after
		content ''
		display block
		clear both

As of now, the bubbles just have a light gray background. Use any stronger color, and you have to reverse the text, which I think is too “dramatic” for this. So I don’t even use two different shades for the speakers, because there isn’t much of a range that is workable here. The same goes for using a background color on the whole section, and making the speech bubbles white, as we do in the plays. It just creates a break in the document flow that is too abrupt.

For other formats (such as PDF), the contents will be completely unaffected.

Figures are first-class in HTML (as of HTML5). Mozilla Developer Network, my unofficial reference of choice, describes it this way:

The HTML <figure> element represents self-contained content, frequently with a caption (<figcaption>), and is typically referenced as a single unit. While it is related to the main flow, its position is independent of the main flow. Usually this is an image, an illustration, a diagram, a code snippet, or a schema that is referenced in the main text, but that can be moved to another page or to an appendix without affecting the main flow.⁶

At the moment, all images in these documents are automatically considered figures. It’s an open question as to whether I should be able to distinguish between these cases. As the official specification notes,

When a figure is referred to from the main content of the document by identifying it by its caption (e.g. by figure number), it enables such content to be easily moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without affecting the flow of the document.

If a figure element is referenced by its relative position, e.g. “in the photograph above” or “as the next figure shows”, then moving the figure would disrupt the page’s meaning. Authors are encouraged to consider using labels to refer to figures, rather than using such relative references, so that the page can easily be restyled without affecting the page’s meaning.

Although I agree with the general point, I have not reviewed whether I have legitamite cases of the latter kind.

figure
	margin 0                                        // beat figure default
	// already set elsewhere, right? to auto, which is effectively the same
	//img
	//      margin 0

figcaption
	margin .5em 1em
	line-height 1.2
	font-size smaller
	text-align center

.figure-number
	display block
	font-style italic

Marginal figures are floating off of the document sheet, so they need to be their own material.

figure.marginal
	border-radius .25em
	background lighten($documentMapColor, 66%)
	box-shadow -.25em .25em .5em #111

Mostly for internal use, but no harm in publishing.

@require colors
keyword($color)
	color $color
	text-shadow 1px 1px 0 #555

	&:before
		content ''
		position absolute
		right 100%
		margin-right 1em
		width 1em
		height 100%
		background $color
		box-shadow 1px 1px 1px #555

$badColor = desaturate(red, 50%)
.tbd
	@extend .document .aside
	border-left-color $badColor

.outline-2
.outline-3
.outline-4
	position relative               // support section status markers

#table-of-contents li
	.todo:before
		display none

.todo
	font-family sans-serif;

.STUB
	keyword($badColor)

.DRAFT
	keyword(desaturate(yellow, 50%))

.PUBLIC
	keyword(desaturate(green, 50%))

I use epigrams a lot, and it seems that they could do with some special formatting. At the least, they are usually right-aligned.