Scrolltext Format

This document is an extracted (and modified) section taken from the Scroll Protocol specification on 2024-05-06 from:

gemini://scrollprotocol.us.to/spec.scroll

I agree with the author, Christian Siebold, that Gemtext is more restrictive than I'd like. I do sometimes need level 4 headings, and the inline phrase markup as commonly used for emphasis and strong emphasis is very useful. I am adopting those portions of Scrolltext, along with the thematic break (which I have long been encoding as a line containing a single "⁂" asterism character). The rest of the Scroll protocol is too much like MarkDown and HTML/HTTP/HTTPS: too complex.

This document is currently available at the following addresses:

gemini://jdcard.com/scrolltext.gmi

https://jdcard.com/scrolltext.gmi

spartan://jdcard.com:3300/scrolltext.gmi

Mimetype: text/scroll

File Extension: .scroll

The scrolltext format is a descriptive-presentational markup language inspired by gemtext, markdown, and AsciiDoc. It is designed to be streamable and easy to parse, and contains the most important elements within most textual documents, printed and digital. Scrolltext is therefore line-based, much like gemtext.

Paragraphs

Each line with none of the line prefixes below should be interpreted as paragraphs. Lines are not reflowed, but they may be word-wrapped.

Inline Preformatted

Paragraphs may include *asterisks* for strong, _underscores_ for emphasis, or backticks for monospace or code, which acts as inline preformatted text. Clients may choose not to render these, however.

Torture Tests

These paragraphs, which were not part of the original source document, are here solely to test the client's rendering of inline markup. Note that "inline preformatted" precludes the use of emphasis or strong phrases within the preformatted section; their "_" or "*" markup characters will be displayed just as if they were in a preformatted block. The markup will be presented first in a preformatted block, followed by the same line as regular text.

_Emphasized_ is often rendered as italic text.

Emphasized is often rendered as italic text.

*Strong* is often displayed using a bold typeface.

Strong is often displayed using a bold typeface.

_Emphasized_ *_and_* *strong*.

Emphasized and strong.

_Emphasized_ *_and_* *strong* are not the same as `code or _inline preformatted_` text.

Emphasized and strong are not the same as code or _inline preformatted_ text.

Perhaps we should include some "`sample code`" to verify.

Perhaps we should include some "sample code" to verify.

This line is not in a preformatted block. It begins and ends with a single backtick character. *Asterisks* and _underscores_ should not affect rendering here, they should be displayed inline, as-is. Unlike a preformatted block, this text should be word-wrapped.

Preformatted Blocks

Preformatted blocks should not be word-wrapped or justified, but they can be character-wrapped. Preformatted blocks are toggled with three backticks on the start of a line, with an optional alt-text after the three backticks. This toggle denotes the start or end of a preformatted block.

Preformatted blocks are toggled with three backticks (```) on the start of a line.

Added by Christian Siebold on 2024-05-17, see:

gemini://scrollprotocol.us.to/devlog/20240517.gmi

Code blocks define a block within the scrolltext that should be distinguished from the rest of the document as a textual format. They may be used for code blocks, ASCII Art, plain text, or other textual formats. They are usually presented visually in fixed-width fonts. Audal presentations should distinguish them from the surrounding text and should present the format tag to the listener.

Code blocks' visual presentation should not be word-wrapped or justified, but they may be character-wrapped. Code blocks are toggled with three backticks on the start of a line. This toggles the start or end of a code block.

The starting toggle of a code block may include an optional tag just after the three backticks that describes the format. Mimetypes starting with text/ are permitted, but the text/ prefix should be excluded. Therefore, text/plain should be written plain. [The officially recognized list of text/* media-types from IANA is contained in this CSV file:]

https://www.iana.org/assignments/media-types/media-types.xhtml#text

IANA text/* media-types (CSV)

Name	Template	Reference
1d-interleaved-parityfec	text/1d-interleaved-parityfec	[RFC6015]
cache-manifest	text/cache-manifest	[W3C][Robin_Berjon]
calendar	text/calendar	[RFC5545]
cql	text/cql	[HL7][Bryn_Rhodes]
cql-expression	text/cql-expression	[HL7][Bryn_Rhodes]
cql-identifier	text/cql-identifier	[HL7][Bryn_Rhodes]
css	text/css	[RFC2318]
csv	text/csv	[RFC4180][RFC7111]
csv-schema	text/csv-schema	[National_Archives_UK][David_Underdown]
directory - DEPRECATED by RFC6350	text/directory	[RFC2425][RFC6350]
dns	text/dns	[RFC4027]
ecmascript (OBSOLETED in favor of text/javascript)	text/ecmascript	[RFC9239]
encaprtp	text/encaprtp	[RFC6849]
enriched		[RFC1896]
example	text/example	[RFC4735]
fhirpath	text/fhirpath	[HL7][Bryn_Rhodes]
flexfec	text/flexfec	[RFC8627]
fwdred	text/fwdred	[RFC6354]
gff3	text/gff3	[Sequence_Ontology]
grammar-ref-list	text/grammar-ref-list	[RFC6787]
hl7v2	text/hl7v2	[HL7][Marc_Duteau]
html	text/html	[W3C][Robin_Berjon]
javascript	text/javascript	[RFC9239]
jcr-cnd	text/jcr-cnd	[Peeter_Piegaze]
markdown	text/markdown	[RFC7763]
mizar	text/mizar	[Jesse_Alama]
n3	text/n3	[W3C][Eric_Prudhommeaux]
parameters	text/parameters	[RFC7826]
parityfec	text/parityfec	[RFC3009]
plain		[RFC2046][RFC3676][RFC5147]
provenance-notation	text/provenance-notation	[W3C][Ivan_Herman]
prs.fallenstein.rst	text/prs.fallenstein.rst	[Benja_Fallenstein]
prs.lines.tag	text/prs.lines.tag	[John_Lines]
prs.prop.logic	text/prs.prop.logic	[Hans-Dieter_A._Hiep]
prs.texi	text/prs.texi	[Matin_Bavardi]
raptorfec	text/raptorfec	[RFC6682]
RED	text/RED	[RFC4102]
rfc822-headers	text/rfc822-headers	[RFC6522]
richtext		[RFC2045][RFC2046]
rtf	text/rtf	[Paul_Lindner]
rtp-enc-aescm128	text/rtp-enc-aescm128	[_3GPP]
rtploopback	text/rtploopback	[RFC6849]
rtx	text/rtx	[RFC4588]
SGML	text/SGML	[RFC1874]
shaclc	text/shaclc	[W3C_SHACL_Community_Group][Vladimir_Alexiev]
shex	text/shex	[W3C][Eric_Prudhommeaux]
spdx	text/spdx	[Linux_Foundation][Rose_Judge]
strings	text/strings	[IEEE-ISTO-PWG-PPP]
t140	text/t140	[RFC4103]
tab-separated-values	text/tab-separated-values	[Paul_Lindner]
troff	text/troff	[RFC4263]
turtle	text/turtle	[W3C][Eric_Prudhommeaux]
ulpfec	text/ulpfec	[RFC5109]
uri-list	text/uri-list	[RFC2483]
vcard	text/vcard	[RFC6350]
vnd.a	text/vnd.a	[Regis_Dehoux]
vnd.abc	text/vnd.abc	[Steve_Allen]
vnd.ascii-art	text/vnd.ascii-art	[Kim_Scarborough]
vnd.curl	text/vnd.curl	[Robert_Byrnes]
vnd.debian.copyright	text/vnd.debian.copyright	[Charles_Plessy]
vnd.DMClientScript	text/vnd.DMClientScript	[Dan_Bradley]
vnd.dvb.subtitle	text/vnd.dvb.subtitle	[Peter_Siebert][Michael_Lagally]
vnd.esmertec.theme-descriptor	text/vnd.esmertec.theme-descriptor	[Stefan_Eilemann]
vnd.exchangeable	text/vnd.exchangeable	[Martin_Cizek]
vnd.familysearch.gedcom	text/vnd.familysearch.gedcom	[Gordon_Clarke]
vnd.ficlab.flt	text/vnd.ficlab.flt	[Steve_Gilberd]
vnd.fly	text/vnd.fly	[John-Mark_Gurney]
vnd.fmi.flexstor	text/vnd.fmi.flexstor	[Kari_E._Hurtta]
vnd.gml	text/vnd.gml	[Mi_Tar]
vnd.graphviz	text/vnd.graphviz	[John_Ellson]
vnd.hans	text/vnd.hans	[Hill_Hanxv]
vnd.hgl	text/vnd.hgl	[Heungsub_Lee]
vnd.in3d.3dml	text/vnd.in3d.3dml	[Michael_Powers]
vnd.in3d.spot	text/vnd.in3d.spot	[Michael_Powers]
vnd.IPTC.NewsML	text/vnd.IPTC.NewsML	[IPTC]
vnd.IPTC.NITF	text/vnd.IPTC.NITF	[IPTC]
vnd.latex-z	text/vnd.latex-z	[Mikusiak_Lubos]
vnd.motorola.reflex	text/vnd.motorola.reflex	[Mark_Patton]
vnd.ms-mediapackage	text/vnd.ms-mediapackage	[Jan_Nelson]
vnd.net2phone.commcenter.command	text/vnd.net2phone.commcenter.command	[Feiyu_Xie]
vnd.radisys.msml-basic-layout	text/vnd.radisys.msml-basic-layout	[RFC5707]
vnd.senx.warpscript	text/vnd.senx.warpscript	[Pierre_Papin]
vnd.si.uricatalogue (OBSOLETED by request)	text/vnd.si.uricatalogue	[Nicholas_Parks_Young]
vnd.sun.j2me.app-descriptor	text/vnd.sun.j2me.app-descriptor	[Gary_Adams]
vnd.sosi	text/vnd.sosi	[Petter_Reinholdtsen]
vnd.trolltech.linguist	text/vnd.trolltech.linguist	[David_Lee_Lambert]
vnd.wap.si	text/vnd.wap.si	[WAP-Forum]
vnd.wap.sl	text/vnd.wap.sl	[WAP-Forum]
vnd.wap.wml	text/vnd.wap.wml	[Peter_Stark]
vnd.wap.wmlscript	text/vnd.wap.wmlscript	[Peter_Stark]
vtt	text/vtt	[W3C][Silvia_Pfeiffer]
wgsl	text/wgsl	[W3C][David_Neto]
xml	text/xml	[RFC7303]
xml-external-parsed-entity	text/xml-external-parsed-entity	[RFC7303]

Examples of code block tags include:

ascii-art
plain
a programming language name
`samp` for sample software input/output

Headings

Heading lines are prefixed with #, ##, ###, and an additional fourth-level heading #### and fifth-level heading #####, much like in gemtext and markdown. The first level-1 heading of a scrolltext page should be interpreted as the document's title; there should be no other level-1 heading in the document.

Heading Samples

There are already enough #, ##, and ### headings in this document. Here are samples of the other two types:

#### Level 4 Heading
This paragraph provides some sample "level 4" text.

Level 4 Heading

This paragraph provides some sample "level 4" text.

##### Level 5 Heading
This paragraph provides some sample "level 5" text.

Level 5 Heading

This paragraph provides some sample "level 5" text.

###### Level 6 heading
Oops! What happens here?

Level 6 heading

Oops! What happens here?

Heading Numbers

Clients may give sections heading numbers, like 1, 3.2, and 1.4.3. Dots delimit the level of the heading, where 3.2 refers to the second level-3 heading under the third level-2 heading. Note that the first number always denotes a level-2 heading.

=> #7.1 Link to "Links To Sections"

Link to "Links To Sections" (#7.1)

Level-5 headings do not need to be placed directly under a level-4 heading; they may be placed under any heading levels 1-4. They are always considered textual titles rather than section titles, and therefore should be excluded from outlines and tables of contents (e.g., the titling of a paragraph or set of paragraphs).

Thematic Breaks

Thematic breaks use three hyphens (---) on their own line. They are usually rendered as horizontal rules or three asterisks (which is the common rendering in printed books). They should be interpreted as thematic breaks within the section denoted by a level 1-4 heading. Note that they are never interpreted as being underneath level-5 headings.

Quotes

Quotes are prefixed with >. They may be nested. Quoted lines may be separated from each other by placing a blank line in between them.

> Sam said `something` that he heard from George.
>> Hello, *my* _name_ is George.

Sam said something that he heard from George.

Hello, my name is George.

Lists

Unordered lists (bullets) are prefixed with an asterisk followed by a required whitespace character (* ). It is the only linetype with a prefix that requires one whitespace character (a space or a tab). This is consistent because it is the only exception, an exception that allows one to distinguish between lines that begin with bold text (for clients that choose to render this) and unordered lists. Lists can be separated from each other by placing a blank line in between them.

Unordered bullets may be nested by placing two or more asterisks next to each other, up to a limit of 4, followed by a space, like so: ** nested bullet.

Ordered lists use asterisks like the unordered bullets above, but the text starts with any number of decimal digit unicode codepoints (e.g., Rust's char.is_digit(10) or Golang's unicode.IsDigit(r)), followed by a dot ('.'), or by one character between 'a' and 'Z' followed by a dot. Rendering these differently from unordered lists is optional. Clients that choose to do so should render the number/character that was provided and not try to renumber the items. Ordered lists may be nested just like Unordered lists.

* Unordered list item 1
** 1. Ordered sub-list item 1
** 2. Ordered sub-list item 2
* Unordered list item 2

Unordered list item 1

1. Ordered sub-list item 1

2. Ordered sub-list item 2

Unordered list item 2

Links

Links use the following format:

=>(<whitespace>)URL<whitespace>Link Text

Whitespace may be any number of spaces or tabs above zero. The parentheses denote optionality.

Links To Sections

The URL may be replaced with a #hash identifier to link to another heading/section of the current document. The hash for scrolltext documents should be the heading number described above (e.g., 3.2.4). Hashes on URLs should be interpreted as links to a section/heading within the linked document.

Links As Quote Citations

Links that are placed just under a quote should be interpreted as the citation for that quote. For example:

> This is a quote
=> scroll://example.net/cited_text.pdf Cited Text Name

This is a quote

Cited Text Name (scroll://example.net/cited_text.pdf)

Inline Presentation of Linked Data

Lastly, when a user clicks on a link, clients may choose to inline the data depending on what contenttypes it supports. This is useful for images, audio, video, and even CSV files.

The Public Domain Race by José Domingues e Leonardo Domingues

https://archive.org/details/the_public_domain_race

Fixing A Hole (mp3)

Fixing A Hole (ogg)

https://archive.org/details/TheBeatlesSgt.PeppersLonelyHeartsClubBandInInstrumental

JDC logotype (svg)

JDCARD license

purchases-sample.csv

Category	count	Total	Average
Clothing	2	509.89	33.27
Gas	18	447.71	29.21
Gifts	3	43.96	2.87
Groceries and Household Supplies	5	8915.24	581.70
Household Equipment	7	820.38	53.53
Meals Out	25	1281.32	83.60
Medical Expense	6	1283.91	83.77
Office and Computer	1	12.25	0.80
Personal Care	2	155.50	10.15
Postage	1	30.10	1.96
Vehicle Maintenance	3	675.54	44.08
TOTAL	7	14175.80	924.93