# Example content # {#introduction}
The text of the document is mostly authored using Markdown syntax. You can use *italicized text*, **bold text**, [hyperlinks](https://example.com) and `inline code blocks`.
There are unordered lists:
* Pollen
* Honey
* Bees
* Work
And there are ordered lists:
1. Aardvark
1. Abacus
1. Academic
1. Subitems work in lists, too
1. The list numbering is automatic
Block formatting can be useful for quotes and excerpts:
> [Lorem ipsum dolor sit amet](https://en.wikipedia.org/wiki/Lorem_ipsum), consectetur adipiscing elit.
> Vivamus tellus dolor, porttitor ut elit sed, vestibulum maximus velit.
> Maecenas at sollicitudin neque. Sed eu risus ullamcorper:
> * porttitor lacus at
> * convallis nunc
> * suspendisse id dolor urna
> * quervos murat
> * curabitur in eros diam
In quote blocks, you can still use all regular formatting. To disable formatting, use code blocks (see below).
There is a special syntax for "key-value" lists:
: key
:: value
: another key
:: another value
## Special formatting of informative examples and notes ## {#notes-examples}
Note: if a paragraph starts with "Note: " it gets special highlighting and block formatting. These paragraphs are considered informative.
Some paragraphs might be marked as informative examples.
## Including code/XML snippets ## {#code}
There is a special syntax for code blocks. This disables markup processing:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Example website</title>
</head>
<body id="home">
<h1>HTML5!</h1>
</body>
</html>
## Including math ## {#math}
When \(a \ne 0\) there are two solutions to \(ax^2 + bx + c = 0\)
and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
## References ## {#document-references}
There is a shortcut syntax for cross references to chapters in the same document: [[#introduction]]
There is a shortcut syntax for referencing well-known documents (RFCs etc) that are published on [SpecRef](https://www.specref.org/). For example, [[rfc2324]] is an important one.
Note: You can also change the reference text and just call it [[rfc2324|the coffee pot RFC]].
There is a slightly different shortcut syntax for normative references [[!DASH-SystemIDs]].
# Some things require HTML # {#html}
Tables are defined as HTML and should be followed by `` and together enclosed by `
`.
Usage
Algorithm
Content Key wrapping
AES256-CBC, PKCS #7 padding
Encrypted key MAC
HMAC-SHA512
Some cryptographic algorithms.
The `data` and `pre` classes enable some default styling for tables. Pick whichever you prefer. The above table uses `data`.
Images are also inserted as HTML.
Just a random static example image.
# Automatic diagram generation # {#diagrams-auto}
Diagrams can be automatically generated from text files. See content of `Diagrams/` subdirectory for diagram source code.
Example for PlantUML component diagram.Example for PlantUML sequence diagram.
# Manual diagrams # {#diagrams-manual}
Diagrams can also be managed manually, treated as static images. Often these are yEd diagrams (.graphml files) that are manually exported to PNG.
Example yEd diagram.
# Defining terms # {#definitions}
The Bikeshed document compiler has a special syntax for various types of term/element definitions. This syntax enables easy cross-refrencing and building of the terminology index.
Terms can be defined either inline (as [=Bikeshed document compiler=] above) or in a key-value list:
: foo
:: bar
: baz
:: woo
Using term reference syntax will link back to the definition of the term: [=foo=] or [=baz=].
Note: every term must be referenced and every reference must point to a valid term. Terms with 0 references will result in a build error, just the same as broken references.
Use a pipe character to specify custom text for the generated link (e.g. for grammatical purposes):
Two [=baz|bazes=] are better than three [=foo|foos=]!
# Defining data structures # {#definitions-datastructures}
If your document defines data structures or languages, you will generally want to use the HTML/XML reference syntax of Bikeshed.
Consider the following XML structure consisting of <{bookstore}> and <{book}> elements:
<bookstore name="Ye Olde Booke Shoppe">
<book title="Machine Learning for Machines" />
<book title="List of letters in the English alphabet, 2nd ed" />
</bookstore>
The data structures in this snippet can be defined as the examples below illustrate. This type of definition allows easy referencing of elements and their children (e.g. <{book/title}>).
Note: the data structure syntax shown here is not ideal but it is the closest we can get to a general-purpose Bikeshed data structure syntax that still enables automatic references. Notably, we cannot easily differentiate between XML element children and attributes.
## bookstore element ## {#schema-bookstore}
The root element of the bookstore document format.
: name (required, xs:string)
:: The human readable name of the bookstore.
: book (0...N, <{book}>)
:: Any number of books made available by the bookstore.
## book element ## {#schema-book}
Defines one book that is published in a bookstore.
: title (required, xs:string)
:: The human readable title of the book.
# Remember, this is Bikeshed not Markdown! # {#bikeshed-is-not-markdown}
Many editors have "Markdown preview" functions that will not be a 100% match to what will really be generated from the source code of this document. Do not be surprised if there are formatting differences.
Revision: 1.0
Title: Example Document
Status: LD
Shortname: example
URL: https://example.com/where/is/this/document/published/
Issue Tracking: GitHub https://github.com/Dash-Industry-Forum/DocumentAuthoringExample/issues
Repository: https://github.com/Dash-Industry-Forum/DocumentAuthoringExample GitHub
Editor: DASH Industry Forum
Default Highlight: text
Line Numbers: off
Markup Shorthands: markdown yes
Boilerplate: copyright off, abstract off
Abstract: None
{
"DASH-SystemIDs": {
"href": "https://dashif.org/identifiers/protection/",
"title": "DASH-IF registry of DRM System IDs.",
"publisher": "DASH Industry Forum"
}
}
