[TITLE]

Stack:
	Or: 1
		T: --
		Seq:
			Opt: skip
				T: -
			Or:
				N: a-z A-Z _ or non-ASCII
				N: escape
	Star:
		Or:
			N: a-z A-Z 0-9 _ - or non-ASCII
			N: escape

` element - it'll get replaced by an appropriate <{svg}> element.

The Diagram Language {#railroad-lang}
--------------------

Diagrams are described by a custom DSL that somewhat resembles Python.

A railroad diagram consists of a number of nested elements, each of which may contain multiple children.  Each element is specified as a command followed by a colon, possibly followed by additional data (the prelude), and the element's children indented on following lines, like:

```
T: /*
ZeroOrMore:
	N: anything but * followed by /
T: */
```

This draws the following diagram:

T: /*
ZeroOrMore:
	N: anything but * followed by /
T: */


The top-level elements are assumed to be a sequence of elements in the diagram.
Inside of a diagram, any of the elements may be used.
Elements are split into two groups: containers and text.

The containers hold other elements, and modify their semantics:


	* Sequence (And, Seq) - used for sequences of elements which must all be selected in order.  Like concatenation in regexes. Takes 1 or more children.
	* Stack - A sequence that arranges its children vertically. Useful for preventing diagrams from becoming excessively wide. Takes 1 or more children.
	* Choice (Or) - used for a choice between elements.  Like the `|` character in regexes.  Takes 1 or more children.  Optionally, the "default" index may be provided in the prelude (defaulting to 0).
	* Optional (Opt)- used for an element that's optional.  Like the `?` character in regexes.  Takes 1 child.  Optionally, the word `skip` may be provided in the prelude to indicate that this term is skipped by default.
	* OneOrMore (Plus)- used for an element that can be chosen one or more times.  Like the `+` character in regexes.
		Takes 1 or 2 children: the first child is the element being repeated, and the optional second child is an element repeated between repetitions.
	* ZeroOrMore (Star) - same as OneOrMore, but allows the element to be chosen zero times as well (skipped entirely).  Like the `*` character in regexes.
		Like [=railroad/Optional=], the keyword `skip` may be provided in the prelude to indicate that the "default option" is to skip it (repeat 0 times).

	The text elements only contain text, not other elements.  Their values are given in their preludes.

	* Terminal (T) - represents a "terminal" in the grammar, something that can't be expanded any more.  Generally represents literal text.
	* NonTerminal (N) - represents a "non-terminal" in the grammar, something that can be expanded further.
	* Comment (C) - represents a comment in the railroad diagram, to aid in reading or provide additional information.  This is often used as the repetition value of a OneOrMore or ZeroOrMore to provide information about the repetitions, like how many are allowed.
	* Skip (S) - represents nothing, an empty option.  This is rarely necessary to use explicitly, as containers like [=railroad/Optional=] use it automatically, but it's occasionally useful when writing out a Choice element where one option is to do nothing.




Source-File Processing: `bikeshed source` {#source}
======================

Sometimes it's the *source* file you want to preprocess,
if there is some feature you want literally in your source
that is hard or annoying to type in yourself.
Bikeshed has some options for doing this as well.

All of these commands are accessed from the `source` sub-command,
like `bikeshed source`.
You can run individual commands by specifying their relevant flag
(see `bikeshed source -h` for a list),
or run all of them by not passing any flags.

Big Text {#big-text}
--------

When editing a large spec,
it's easy to get lost in its length,
and have to spend some time scrolling back and forth to find particular sections.

The Sublime Text editor has a special feature,
the minimap,
which shows an extremely-zoomed out version of your document while you scroll,
so you can recognize where you are in the file by the shape of your code.
This can be made even easier by putting extra-large "ASCII art" text in your source
to label major sections,
so they show up visibly in the minimap as section markers.

Bikeshed can auto-generate this "ASCII art" text for you
with its `--big-text` command.
Just add an HTML comment to your document on its own line that looks like:

<!-- Big Text: Your Text -->


If you run `bikeshed source --big-text`,
Bikeshed will replace it with a comment that looks like:

	
	<!-- Big Text: Your Text

	█   ▐▌  ███▌  █▌  █▌ ████▌      █████▌ █████▌ █     █ █████▌
	▐▌  █  █▌  █▌ █▌  █▌ █▌  █▌       █▌   █▌      █   █    █▌
	 █ ▐▌  █▌  █▌ █▌  █▌ █▌  █▌       █▌   █▌       █ █     █▌
	 ▐▌█   █▌  █▌ █▌  █▌ ████▌        █▌   ████      █      █▌
	  █▌   █▌  █▌ █▌  █▌ █▌▐█         █▌   █▌       █ █     █▌
	  █▌   █▌  █▌ █▌  █▌ █▌ ▐█        █▌   █▌      █   █    █▌
	  █▌    ███▌   ███▌  █▌  █▌       █▌   █████▌ █     █   █▌
	-->
	

Which is clearly visible from Sublime's minimap!

You can also edit the first line to change the text,
re-run `bikeshed source --big-text`,
and it'll swap out the text art with your new text.



Appendix A: Bikeshed’s "InfoTree" Format {#infotree}
====================================================

Bikeshed's custom text formats attempt to be fairly regular;
most of them involve specifying key/value pairs,
and are line-based.
For example, Bikeshed's metadata format is one key/value pair per line,
with a colon between the key and the value.

The InfoTree format,
used by several things in Bikeshed,
is similar.
It's used when you need to specify data consisting of multiple key/value pairs,
where it's common that multiple entries share some of that data.
The InfoTree format makes this easy to read, write, and maintain.

Specifying Information on a Single Line {#infotree-one-line}
---------------------------------------

The simplest way to provide a piece of information is by putting all the key/value pairs on a single line.
In the InfoTree format, this is done by putting a colon between the key and value,
and separating the pairs with semicolons.
For example, here is an example of two "anchor" entries:

```
urlPrefix: https://encoding.spec.whatwg.org/; type: dfn; text: ascii whitespace
urlPrefix: https://encoding.spec.whatwg.org/; type: dfn; text: utf-8
```

This specifies two entries, each with three keys: urlPrefix, type, and text.

Nesting Information to Share Pieces {#infotree-nesting}
-----------------------------------

When multiple pieces of information share some key/value pairs,
you can use nesting to indicate this,
so you don't have to repeat yourself.
Here's the same two entries as before,
but using nesting to share their common information:

```
urlPrefix: https://encoding.spec.whatwg.org/; type: dfn
	text: ascii whitespace
	text: utf-8
```

Just like the previous, this defines two entries, each with three key/value pairs.
Now it's clearer, though, that the two entries share their `urlPrefix` and `type` data,
and you only have to maintain the common data in one place.

Comments {#infotree-comments}
-----------------------------

A line that starts with a `#` character
(with any amount of preceding whitespace)
is a comment;
it will be completely ignored for the purpose of parsing.

Additional Details {#infotree-details}
------------------

The order that keys are specified in is irrelevant.
Feel free to rearrange them for readability or more effective nesting.

You can specify the same key multiple times;
the values will be collected into an array for later processing.
(Each user of InfoTree will define whether multiple values for a key is valid or not, and what it means.)
The order that the values appear in *is* preserved,
as it might be important.
(For example, in the anchor format, multiple urlPrefix values are concatenated together, to help specify urls in multipage specs.)

Additional semicolons are silently ignored;
in other words, empty entries get dropped, so you can put a final semicolon at the end of the line or not, as you prefer.