repo: gemini-site
action: commit
revision: 
path_from: 
revision_from: 685f20d862ec55251d26992f30b92283291e8ce1:
path_to: 
revision_to: 

commit 685f20d862ec55251d26992f30b92283291e8ce1
Author: Solderpunk 
Date:   Sun Mar 1 16:26:52 2020 +0000

    Define non-link line types.

diff --git a/docs/spec-spec.txt b/docs/spec-spec.txt

--- a/docs/spec-spec.txt
+++ b/docs/spec-spec.txt
@@ -1,7 +1,7 @@
 -----------------------------
 Project Gemini
 "Speculative specification"
-v0.10.0, February 3rd 2020
+v0.11.0, March 1st 2020
 -----------------------------

 This is an increasingly less rough sketch of an actual spec for
@@ -238,17 +238,97 @@ inclusion of a MIME type in the response header Gemini can be used to
 serve plain text, rich text, HTML, Markdown, LaTeX, etc.

 Response bodies of type "text/gemini" are a kind of lightweight
-hypertext format inspired by gophermaps.  The format is line-based.
-Any line which begins with the two character prefix "=>" is a link,
-analogous to a gopher menu item with an item type other than "i"
-(full syntax below).  All other lines are just text and should be
-presented as-is (although see 1.3.5.3), analogous to a gopher menu
-item with item type "i", but without the overhead of the dummy item
-type, selector, host and port.
+hypertext format, which takes inspiration from gophermaps and from
+Markdown.  The format permits richer typographic possibilities than
+the plain text of Gopher, but remains extremely easy to parse.  The
+format is line-oriented, and a satisfactory rendering can be achieved
+with a single pass of a document, processing each line independently.
+As per gopher, links can only be displayed one per line, encouraging
+neat, list-like structure.
+
+Similar to how the two-digit Gemini status codes were designed so that
+simple clients can function correctly while ignoring the second digit,
+the text/gemini format has been designed so that simple clients can
+ignore the more advanced features and still remain very usable.
+
+1.3.5.2 Line-orientation
+
+As mentioned, the text/gemini format is line-oriented.  Each line of a
+text/gemini document has a single "line type".  It is possible to
+unambiguously determine a line's type purely by inspecting its first
+three characters.  A line's type determines the manner in which it
+should be presented to the user.  Any details of presentation or
+rendering associated with a particular line type are strictly limited
+in scope to that individual line.
+
+There are 6 different line types in total.  However, a fully
+functional and specification compliant Gemini client need only
+recognise and handle 4 of them - these are the "core line types",
+(see 1.3.5.3).  Advanced clients can also handle the additional
+"advanced line types" (see 1.3.5.4).  Simple clients can treat all
+advanced line types as one of the core line types and still offer an
+adequate user experience.
+
+1.3.5.3 Core line types
+
+The four core line types are:
+
+1.3.5.3.1 Text lines
+
+Text lines are the most fundamenal line type - any line which does
+not match the definition of another line type defined below defaults
+to being a text line.  The majority of lines in a typical text/gemini
+document will be text lines.
+
+Text lines should be presented to the user, after being wrapped to
+the appropriate width for the client's viewport (see below).  Text
+lines may be presented to the user in a visually pleasing manner
+for general reading, the precise meaning of which is at the
+client's discretion.  For example, variable width fonts may be used,
+spacing may be normalised, with spaces between sentences being made
+wider than spacing between words, and other such typographical
+niceties may be applied.  Clients may permit users to customise the
+appearance of text lines by altering the font, font size, text and
+background colour, etc.  Authors should not expect to exercise any
+control over the precise rendering of their text lines, only of their
+actual textual content.  Content such as ASCII art, computer source
+code, etc. which may appear incorrectly when treated as such should
+be enclosed beween preformatting toggle lines (see 1.3.5.3.3).
+
+Blank lines are instances of text lines and have no special meaning.
+They should be rendered individually as vertical blank space each
+time they occur.  In this way  they are analogous to 
 tags in HTML.
+Consecutive blank lines should NOT be collapsed into a fewer blank
+lines.  Note also that consecutive non-blank text lines do not form
+any kind of coherent unit or block such as a "paragraph": all text
+lines are independent entities.
+
+Text lines which are longer than can fit on a client's display device
+SHOULD be "wrapped" to fit, i.e. long lines should be split (ideally
+at whitespace or at hyphens) into multiple consecutive lines of a
+device-appropriate width.  This wrapping is applied to each line of
+text independently.  Multiple consecutive lines which are shorter
+than the client's display device MUST NOT be combined into fewer,
+longer lines.

-1.3.5.2 Link syntax
+In order to take full advantage of this method of text formatting,
+authors of text/gemini content SHOULD avoid hard-wrapping to a
+pecific fixed width, in contrast to the convention in Gopherspace
+where text is typically wrapped at 80 characters or fewer.  Instead,
+text which should be displayed as a contiguous block should be written
+as a single long line.  Most text editors can be configured to
+"soft-wrap", i.e. to write this kind of file while displaying the long
+lines wrapped to fit the author's display device.
+
+Authors who insist on hard-wrapping their content MUST be aware that
+the content will display neatly on clients whose display device is as
+wide as the hard-wrapped length or wider, but will appear with
+irregular line widths on narrower clients.
+
+1.3.5.3.2 Link lines

-Link lines have the following format:
+Lines beginning with the two characters "=>" are link lines, which
+have the following syntax:

 =>[][]

@@ -261,7 +341,7 @@ where:
 *  is a URL, which may be absolute or relative.  If the URL does
   not include a scheme, a scheme of gemini:// is implied.

-All the following examples are valid links:
+All the following examples are valid link lines:

 => gemini://example.org/
 => gemini://example.org/ An example link
@@ -275,44 +355,76 @@ that Gemini documents can simply and elegantly link to documents
 hosted via other protocols, unlike gophermaps which can only link to
 non-gopher content via a non-standard adaptation of the `h` item-type.

-1.3.5.3 Text display
-
-Textual content for Gopher is typically "hard-wrapped", i.e. composed
-of lines no longer than (typically) 80 characters.  Each line of text
-is printed to the screen as-is.  In contrast, in HTML content on the
-web, browsers ignore the length of lines of text and instead "reflow"
-text to a width appropriate for the display device - lines of text in
-a HTML file which are "too long" get split up, while consecutive
-lines which are "too short" get joined together.  Gemini adopts a
-strategy between these two approaches, designed to strike a balance
-between implementation complexity, flexibility of display width, and
-support for common text formatting patterns.
-
-Lines of text in a text/gemini document which are not link lines (i.e.
-do not begin with "=>") which are longer than can fit on a client's
-display device SHOULD be "wrapped" to fit, i.e. long lines should be
-split (ideally at whitespace or at hyphens) into multiple consecutive
-lines of a device-appropriate width.  Recall that text/gemini
-processing is strictly line-based: the above wrapping is applied to
-each line of text independently.  Multiple consecutive lines which
-are shorter than the client's display device MUST NOT be combined.
-
-Blank lines receive no special treatment: they are ordinary text
-lines, with a display length of zero.  Thus, they fit on any
-client's display device and never need to be wrapped.  Each
-individual blank line in a text/gemini document MUST be rendered by
-the client as an individual blank line.
-
-In order to take full advantage of this method of text formatting,
-uthors of text/gemini content SHOULD avoid hard-wrapping to a
-pecific fixed width.  Most text editors can be configured to
-"soft-wrap", i.e. to write this kind of file while displaying the long
-lines wrapped to fit the author's display device.
-
-Authors who insist on hard-wrapping their content MUST be aware that
-the content will display neatly on clients whose display device is as
-wide as the hard-wrapped lenth or wider, but will appear with
-irregular line widths on narrower clients.
+Clients can present links to users in whatever fashion the client
+author wishes.
+
+1.3.5.3.3 Preformatting toggle lines
+
+Any line whose first three characters are "```" (i.e. three
+consecutive back ticks with no leading whitespace) are preformatted
+toggle lines.  These lines should NOT be included in the rendered
+output shown to the user.  Instead, these lines toggle the parser
+between preformatted mode being "on" or "off".  Preformatted mode
+should be "off" at the beginning of a document.  The current status
+of preformatted mode is the only internal state a parser is required
+to maintain.  When preformatted mode is "on", the usual rules for
+identifying line types are suspended, and all lines should be
+identified as preformatted text lines (see 1.3.5.3.4).
+
+Preformatting toggle lines can be thought of as analogous to 
 and
+
 tags in HTML.
+
+1.3.5.3.4 Preformatted text lines
+
+Preformatted text lines should be presented to the user in a "neutral",
+monowidth font without any alteration to whitespace or stylistic
+enhancements.  Graphical clients should use scrolling mechanisms to
+present preformatted text lines which are longer than the client
+viewport, in preference to wrapping.  In displaying preformatted text
+lines, clients should keep in mind applications like ASCII art and
+computer source code: in particular, source code in langugaes with
+significant whitespace (e.g. Python) should be able to be copied and
+pasted from the client into a file and interpreted/compiled without
+any problems arising from the client's manner of displaying them.
+
+1.3.5.4 Advanced line types
+
+The following advanced line types MAY be recognised by advanced
+clients.  Simple clients may treat them all as text lines as per
+1.3.5.3.1 without any loss of essential function.
+
+1.3.5.4.1 Heading lines
+
+Lines beginning with "#" are heading lines.  Heading lines consist of
+one, two or three consecutive "#" characters, followed by optional
+whitespace, followed by heading text.  The number of # characters
+indicates the "level" of header;  #, ## and ### can be thought of as
+analogous to 
, 
 and 
 in HTML.
+
+Heading text should be presented to the user, and clients MAY use
+special formatting, e.g. a larger or bold font, to indicate its
+status as a header (simple clients may simply print the line,
+including its leading #s, without any styling at all).  However, the
+main motivation for the definition of heading lines is not stylistic
+but to provide a machine-readable representation of the internal
+structure of the document.  Advanced clients can use this information
+to, e.g. display an automatically generated and hierarchically
+formatted "table of contents" for a long document in a side-pane,
+allowing users to easily jump to specific sections without excessive
+scrolling.  CMS-style tools automatically generating menus or
+Atom/RSS feeds for a directory of text/gemini files can use first
+heading in the file as a human-friendly title.
+
+1.3.5.4.2 Unordered list items
+
+Lines beginning with a * are unordered list items.  This line type
+exists purely for stylistic reasons.  The * may be replaced in
+advanced clients by a bullet symbol.  Any text after the * character
+should be presented to the user as if it were a text line, i.e.
+wrapped to fit the viewport and formatted "nicely".  Advanced clients
+can take the space of the bullet symbol into account when wrapping
+long list items to ensure that all lines of text corresponding to
+the item are offset an equal distance from the left of the screen.

 1.4 TLS

-----END OF PAGE-----