💾 Archived View for rawtext.club › ~sloum › geminilist › 000348.gmi captured on 2020-11-07 at 01:25:43. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Text reflow woes (or: I want bullets back!)y

solderpunk solderpunk at SDF.ORG

Fri Jan 17 17:29:02 GMT 2020

- - - - - - - - - - - - - - - - - - - ```

On Fri, Jan 17, 2020 at 08:52:52AM -0800, Aaron Janse wrote:
>
> Definitely. Unless there is a problem I'm not seeing, this sounds very
> exciting!

I'm excited by this, too. Because I can't control myself I've alreadystarted writing up a rough spec for this, included below for comment. Idefinitely want to wait until more people have chimed in before gettingtoo excited, and I'd especially like to hear from all, or at least most,of the authors of existing clients before making even a tentativedecision. But I have to say, in writing up the below, I get a very goodfeeling. The description is not exactly short, but it's very *notfiddly* compared to how it would look if we were going to support"reflow in both directions". This "half reflow" approach seems to hitan amazing sweetspot of simplicity, richness and adaptability of displaywidths. I have figured out how to get vim to let me write this kind ofcontent in a pleasant and easy way, so I think I'm happy to switch. Andif anybody *really* hates it, they can still hard-wrap their files andwide clients following these rules will display it properly. Narrowclients will end up with a mess, but that's just the price people willhave to pay for sticking to their hard-wrapping guns. Many of them willprobably be happy to dismiss mobile clients out of hand, anyway!

Feedback on the below very welcome!

Cheers,Solderpunk

---------

The text/gemini syntax is inspired by and looks visually similar toMarkdown, but it is significantly simpler (and consequently lesspowerful). The syntax is strictly line-based: a file can be processedone line at a time and each line can be handled in a way which doesnot depend upon any previous or subsequent lines. The only internalstate a rendering engine needs to maintain is a single booleanvariable (for preformatting mode, described below).

The lines of a text/gemini file come in 8 different types. It ispossible to unambiguously determine the type of a line by onlyconsidering its first three characters. Knowing a line's type is theonly information necessary to know how to handle it correctly.

Just like Gemini's status code system is designed so that simpleclients can ignore the second digit of the code and still functioncorrectly, the text/gemini syntax is designed so that simple clientscan treat several different types of line identically and stillprovide a usable representation of the document. A bare-minimumclient need only recognise four different types of line. These are:

1. PREFORMATTED TOGGLE LINES

Lines consisting of only and exactly three back ticks (```) arepreformatted toggle lines. These lines should not be displayed to theuser and are instead used to toggle preformatted mode on and off (themode is off when the parser is intialised). When preformatted mode ison, the usual rules for identifying line types are suspended and alllines should be unconditionally identified as PREFORMATTED TEXT LINES.

2. PREFORMATTED TEXT LINES

Preformatted text lines should be presented to the user in a monowidthfont exactly as they appear in the text/gemini file. Lines longerthan the client's viewport must not be wrapped, leading or trailingwhitespace must not be removed, etc. Handling of lines longer than theviewport is client-specific. Advanced clients may display ahorizontal scrollbar. Simple clients may simply truncate the line.

3. LINK LINES

Lines beginning with the two characters =
> are link lines. We all knowhow these work by now.

4. TEXT LINES

All other lines are TEXT LINES. They should be presented to the userin a client-specific "pleasing manner". Lines longer than theclient's viewport should be wrapped into multiple lines of a suitablelength. Variable width fonts may be used. Blank lines are a specialcase of TEXT LINES and should be reproduced in the output.

It is important to realise that while Markdown, HTML, LaTeX and manyother document markup formats are "block based" or "paragraph based",the text/gemini format is not. Consecutive, non-blank lines of textwhich are much shorter than the client's viewport should *not* becombined into longer lines. Equivalently, *every* newline characterin a text/gemini file is significant, not only consecutive pairs ofnewline characters. Clients ignoring this fact will produce incorrectoutput.

Advanced clients may also recognise the following additional linetypes. Simple clients may treat all line types below as TEXT LINESwith no loss of essential function.

5. HEADING LINES

Lines beginning with one, two or three consecutive # characters areHEADING LINES, corresponding to headings, subheadings or susubheadingsrespectively. The text following the # characters (with leadingwhitespace removed) constitute the heading and should be displayed tothe user. Clients MAY choose to apply special styling to headings todistinguish them from ordinary lines. However, the primary purpose ofHEADING LINES is to represent the internal structure of the documentin a machine-readable way. Advanced clients can use this informationto, e.g. display a hierarchically formatted "table of contents" for along document in a side-pane, allowing users to easily jump tospecific sections without excessive scrolling. Or CMS-style toolsautomatically generating menus or Atom/RSS feeds for a directory oftext/gemini files can use the first heading in a file as ahuman-friendly label for links to it.

6. UNORDERED LIST ITEMS

Lines beginning with a * are UNORDERED LIST ITEMS. This line typeexists purely for stylistic reasons. The * may be replaced inadvanced clients by a bullet symbol. Any text after the * charactershould be presented to the user as if it were a TEXT LINE, i.e.wrapped to fit the viewport. Advanced clients can take the space ofthe bullet symbol into account when performing wrapping and ensurethat all lines of text corresponding to the item are aligned with oneanother.

7. ORDERED LIST ITEMS

As above with obvious changes.