💾 Archived View for jdcard.com › ReadingGemtext.txt captured on 2023-01-29 at 03:01:16.
-=-=-=-=-=-=-
# Reading Gemtext
Note: this document it is deliberately not valid gemtext, it is text/plain
rather than text/gemini. It is designed to help you to learn to read
gemtext without the aid of specialized software.
There are several good guides to help people write in the gemtext format.
Here is a brief guide to reading gemtext documents.
The programs that display nicely-formatted gemtext documents work by reading
only the first two or three characters at the beginning of each line of text.
In this document I will insert a blank space at the beginning of lines that
demonstrate gemtext markup as a way to show you what the markup looks like
(in case you happen to read this file in a gemtext browser).
Gemtext is written as one long line of text for each paragraph. Programs
that are designed to display gemtext automatically force any text that is
too long to fit in your window onto the next line. If you're reading gemtext
in a text editor you can achieve the same effect in many editors by enabling
their "word wrap" or "soft wrap" features. From this point forward this
document will use long lines.
## Headings
A line that begins with one or more "#" characters introduces a new section of the document. More "#" characters indicate lesser levels of importance, or greater levels of detail, within the document.
### Heading Types
Gemtext provides three types of headings. These are similar to what you might see in HTML code as <h1>, <h2>, and <h3> level headings.
# Level 1 Heading -- many documents have only one Level 1 heading, at the very top of the document, that serves as a title.
## Level 2 Heading -- these are often used to indicate the various major sections of the document.
### Level 3 Heading -- indicates a subsection of a larger portion the document.
## Lists
Lines that begin with the "*" character are list items. Gemtext supports only one type of bulleted list. It is what HTML designates as <ul>, or an unordered list.
### List Examples
* An asterisk at the beginning of a line denotes a list item.
* Gemtext client sofware will generally replace the asterisk with a dot or other marker, wrap list items that have long text, and may adjust margins to make list items like this one more readable.
* List items are not automatically numbered.
* 1. This is one way you might see a "numbered list" presented.
* 2. These numbers are inserted by the author manually.
* 4. They are not generated automatically -- that's why you see a break in the number sequence here, as a demonstration.
* 5. Nevertheless you may see gemtext authors use list items in this way.
## Links
A line that begins with "=>" indicates a reference to another document.
The text that immediately follows the "=>" marker is the "address" of the document being referenced. After the (often long and hard to read) "address" is often a blank space followed by a plain text description of the document being referenced.
If you're reading a gemtext document without the aid of gemtext software, you may have to copy the "address" information into a browser or file manager to manually retrieve the referenced document.
### Link Examples
=> Gemtext.gmi A brief guide for Gemtext authors.
This link points to another document (Gemtext.gmi) in the same location as the current document.
=> blog/hello-tildeverse.gmi One of my early blog posts
This link points to a document in the "blog" subdirectory relative to where this current file is located.
=> https://wagingnonviolence.org/ The Waging Nonviolence website
This link points to a web resource totally separate from the current document.
=> ../img/JDCARDlicense.jpg
Links may point to non-document resources. Also note that a link does not have to have any description following the resource address. This is another link relative to the current document: go up one directory and look in the "img" folder to find the "JDCARDlicense.jpg" file.
## Quotations
A ">" character at the beginning of a line indicates that text in that line is a quoted passage from another source.
### Quoted Text Examples
> "The cure for boredom is curiousity. There is no cure for curiousity." -- Ellen Parr
Here is a longer quotation (two paragraphs), followed immediately by a link to the source document.
> "Burning fossil fuels warms the planet, which harms others. It's that simple. Although the processes involved are distributed globally, accrue over decades, and are statistical in nature -- and therefore difficult for our brains to connect directly back to our individual actions -- the harm is nonetheless real.
>
> "Burning fossil fuels should be unacceptable socially, the way physical assault is unacceptable. The harm it does is less immediate, but just as real. We need to start speaking this truth -- burning fossil fuels harms others -- so that society can begin realizing it." -- Peter Kalmus
=> https://peterkalmus.net/books/read-by-chapter-being-the-change/ [Peter Kalmus in "Being The Change"]
## Preformatted Text
When a line begins with the "```" sequence it indicates that what follows -- until you come to another line starting with "```" -- is text that should be read using a mono-spaced font so that all the characters line up properly with one another. The "```" sequence is often followed by a brief explanation of what the preformatted section represents. The three most common uses for this are in presenting tables of data, computer source code, or ASCII art.
### Tables
``` Table: Number of incidents per month
┌────────────────┬───────┐
│ Month │ Count │
╞════════════════╪═══════╡
│ September 2020 │ 8 │
├────────────────┼───────┤
│ October 2020 │ 4 │
├────────────────┼───────┤
│ November 2020 │ 1 │
├────────────────┼───────┤
│ December 2020 │ 2 │
├────────────────┼───────┤
│ January 2021 │ 1 │
├────────────────┼───────┤
│ February 2021 │ 2 │
├────────────────┼───────┤
│ March 2021 │ 0 │
├────────────────┼───────┤
│ April 2021 │ 1 │
├────────────────┼───────┤
│ May 2021 │ 4 │
├────────────────┼───────┤
│ June 2021 │ 4 │
├────────────────┼───────┤
│ July 2021 │ 5 │
├────────────────┼───────┤
│ August 2021 │ 1 │
├────────────────┼───────┤
│ September 2021 │ 7 │
├────────────────┼───────┤
│ October 2021 │ 2 │
├────────────────┼───────┤
│ November 2021 │ 2 │
└────────────────┴───────┘
```
### Programming Code
``` Code: My first BASIC program: HELLO.BAS
10 REM HELLO.BAS - print a message to the output device
20 PRINT "Hello world."
30 END
```
### ASCII Art
``` ASCII art: cat and bunny
|\_/| **************************** (\_/)
/ @ @ \ * "Purrrfectly pleasant" * (='.'=)
( > º < ) * Poppy Prinz * (")_(")
`>>x<<´ * (pprinzexample.com) *
/ O \ ****************************
```
## Summary
Although it is less than ideal, it is quite possible to read gemtext documents without a browser or other specialized software.
=> ReadingGemtext.gmi Link to a valid gemtext version of this file.