~fkfd/sophon

71bc836d090b9f845434cc1e709f5f3522e5d87c — Frederick Yin 3 years ago c9cad05
Meta is now a section in documentation
2 files changed, 31 insertions(+), 26 deletions(-)

M docs/editing_on_sophon.gmi
M docs/wiki_pages.gmi
M docs/editing_on_sophon.gmi => docs/editing_on_sophon.gmi +13 -13
@@ 13,7 13,7 @@ Sophon is a wiki server. By definition, it allows users to edit a wiki page. How
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

## 2. Allowed operations
Listed below are allowed operations from a client on a Sophon server. "Interactive" operations, i.e. operations which require a staging process in which users make more than one transaction with the server to finalize the edit, are marked with an asterisk.
Listed below are allowed operations from a client on a Sophon server. 

(a) Site-level (information is needed from more than one page, e.g. to avoid naming collision)
    (1) creating a page


@@ 26,11 26,11 @@ Listed below are allowed operations from a client on a Sophon server. "Interacti
    (7) creating a section
    (8) deleting a section
    (9) renaming a section
    (10) * editing the meta field
    (11) * editing a section
    (10) editing a section

## 3. Procedures
This section can also be interpreted as Sophon's detailed API documentation. It does not aim to explain the internal workings of Sophon, but rather describe the requests, operations and responses as in a "black box".

### 3.1. Creating a page
### 3.2. Deleting a page
### 3.3. Creating a redirection


@@ 47,21 47,21 @@ Prior to implementing the page-editing functionability, a developer of a piece o
    * the diff, if too long, can be chunked into small, independent parts while the integrity is unaffected (optional; a workaround is pending involving serial numbers)
    * the diff, even without context, can be applied to the old string giving the new one, and reports an error if it cannot be applied

1. Client requests /wiki/<page>/edit?<part> where:
1. Client requests /wiki/<page>/edit?<section> where:
    * <page> is the computer name of the wiki page (lower case, no whitespace, words joined with underscores)
    * <part> is "meta" when the meta field is to be edited; is "section=<number>" when a section is, where:
        - <number> is the section number as specified in wiki_page.gmi, section 2.4.
    * server MUST remember <page> and <part> in the session to be initiated below
    * <section> is the section to edit, "meta" or the section number of a body section
        - section numbers are specified in wiki_page.gmi, section 2.4.
    * server remembers <page> and <section> in the session to be initiated below
2. Server initializes an edit session called <id>
    * <id> should be a random or pseudorandom string such that
        - collision is extremely unlikely between two sessions, whether simultaneous or not
        - brute-forcing is extremely difficult for someone who does not know <id>
        - it is short enough to fit in a URL, leaving a considerable amount of spare characters for other information
        - it employs no character out of the conventional set used in URLS
        - with the points above in consideration, Sophon at present uses the first 16 chars of a sha256 sum of metadata mixed with current time, making it 64 bits in entropy. You MAY also use other encodings such as base64 or decimal.
    * server creates a temporary copy of <page>.gmi and extracts <part> from the page
        - the extracted part is stored somewhere independent of <page>.gmi (either the copy or the original), and is called the stage (cf. git)
        - the extracted part MAY undergo a reversible process to bring convenience to user's edits or the diff algorithm (e.g. hard-wrapped to 80 chars or one sentence on each line)
        - with the points above in consideration, the Sophon implementation at present uses the first 16 chars of a sha256 sum of metadata mixed with current time, making it 64 bits in entropy. You MAY also use other encodings such as base64 or decimal.
    * server creates a temporary copy of <page>.gmi and extracts <section> from the page
        - the extracted section is stored somewhere independent of <page>.gmi (either the copy or the original), and is called the stage (cf. git)
        - the extracted section MAY undergo a reversible process to bring convenience to user's edits or the diff algorithm (e.g. hard-wrapped to 80 chars or one sentence on each line)
        - the stage is subject to changes from the user
    * server creates a temporary storage medium (e.g. temporary file) for users to upload diffs, which will be introduced later
    * the copy of <page>.gmi, the stage and the diff medium SHOULD remain in existence throughout session <id>


@@ 84,12 84,12 @@ Prior to implementing the page-editing functionability, a developer of a piece o
12. If user wants to make further changes, client should goto step 5.
13. Otherwise, client SHOULD request /wiki/<page>/edit/<id>/preview?page for a page preview before committing the session.
    * Committing the session without previewing the page is allowed (for prospective automation purposes). However, for human users this step is RECOMMENDED.
14. Server responds with 20 as status code, and what <page>.gmi would look like after contents in its original <part> is replaced with those on the stage
14. Server responds with 20 as status code, and what <page>.gmi would look like after contents in its original <section> is replaced with those on the stage
    * if contents on the stage have undergone a process, the process MUST be reversed before being sent to client but MUST NOT overwrite the stage itself, in case user has more changes to make
    * server SHOULD perform an integrity check on the contents, and respond with an error if problematic strings are found (e.g. headings in meta or section)
    * the copy of <page>.gmi MAY be overwritten in this process
15. If user is happy with the results, client commits the session by requesting /wiki/<page>/edit/<id>/commit?<message> where:
    * <message> is a brief description of edits made in this session, and MUST NOT be blank
16. Server merges the stage into <page>.gmi in the same way as in step 14, overwrites the original read-mode <page>.gmi with <page>.gmi in the session, keeps a log of this edit, removes the session, and finally responds to client with status code 30 redirecting it to /wiki/<page>, which should have been updated
    * the log, if specific to <page>, SHOULD record <part>, time committed, client's IP, and the diff (sent from client or regenerated by comparing the original <page>.gmi and the copy in its final state)
    * the log, if specific to <page>, SHOULD record <section>, time committed, client's IP, and the diff (sent from client or regenerated by comparing the original <page>.gmi and the copy in its final state)


M docs/wiki_pages.gmi => docs/wiki_pages.gmi +18 -13
@@ 14,7 14,7 @@ A wiki page MUST be a UTF-8-encoded file with extension ".gmi". The filename, if
A wiki page file is, in essence, a Gemini document but with more requirements, so as to make it uniform and machine-readable. When served over the network, its MIME type SHOULD be "text/gemini". Line breaks MUST be LF.

## 2. Contents
This section defines how a wiki page should be parsed by a computer.
This section defines how a wiki page should be parsed by a computer. Briefly put, a page consists of a title, several sections (including a meta section and body sections/subsections), a Table of Contents, and a Page Info field.

### 2.1. Title
The first line in a wiki page is defined as the title line. It MUST be a 1st-level heading line by Gemini's specs, with the following additional requirements:


@@ 27,12 27,22 @@ The heading text, which is extracted by trimming off the first two characters fr
Apart from the title line, additional 1st-level headings MUST NOT appear throughout the page.

### 2.2. Meta
Lines between the title line and the Table of Contents belong to the meta field. It MUST NOT contain any 2nd-level headings, which signal the start of the ToC; it MUST NOT contain any 1st-level headings either.
Lines between the title line and the Table of Contents belong to the meta section. It MUST NOT contain any 2nd-level headings, which signal the start of the ToC; it MUST NOT contain any 1st-level headings either.

The meta field can serve as a Quick Facts box or a notice board informing readers of issues in this page, but its specific purpose is unlimited.

### 2.3. Table of Contents (ToC)
The ToC serves as a quick index for human readers to navigate through the page. Each line inside inside the ToC below the heading MUST be a Gemini link line, with the following format:
The ToC serves as a quick index for human readers to navigate through the body of the page. It is signaled by the presence of the first (and only) 2nd-level heading in the page.

Some valid headings are:

```
## Table of Contents
## 目录
## Inhalt
```

Each line inside the ToC below the ToC heading MUST be a Gemini link line, with the following format:

```
=> #<section.number.>_<section_title> <section.number.> <section title>


@@ 46,20 56,15 @@ For example:

The URL segment of such line SHOULD be any valid URL that would take the reader to the section. However, note that no such standard that specifies how fragment navigation in Gemini should work exists. Hence, this is only a speculative suggestion based on little community consensus (I checked the Gemini list for that), and *subject to change*.

### 2.4. Sections and subsections
After the presence of the ToC, all 2nd- and 3rd-level headings signal the start of a logical block of text. Inside the aforementioned range, lines from one 2nd-level heading to the next one or the page info field, plus the heading itself, are called a section; lines from one 3rd-level heading to the next one inside the same section or the end of this section, plus the heading itself, are called a subsection. Sophon does not recognize deeper-level logical blocks of text branching out of a subsection. Therefore, they will NOT be indexed in the ToC, and SHOULD NOT be used. A blank line SHOULD be inserted above a section or subsection heading, but SHOULD NOT be inserted below one.

As specified above, a section MAY contain subsections. In addition, it MAY also contain content not belonging to any of its subsections. In such case, the content MUST be located between the section heading and its first subsection. When a section has no subsections, its content takes up the section.
### 2.4. Body sections, subsections and their contents
After the presence of the ToC, all 2nd- and 3rd-level headings signal the start of a logical block of text. Inside the aforementioned range, lines from one 2nd-level heading to the next one or the page info field, plus the heading itself, are called a section; lines from one 3rd-level heading to the next one inside the same section or the end of this section, plus the heading itself, are called a subsection. Sophon does not recognize deeper-level logical blocks of text branching out of a subsection. Therefore, they will NOT be indexed in the ToC, and SHOULD NOT be used. A blank line SHOULD be inserted above a section or subsection heading, but SHOULD NOT be inserted below one. When a user is manipulating a section extracted from the page, leading or trailing blank lines SHOULD be removed from it, and re-inserted when the section is merged back.

The numbering of sections MUST conform to the following standard:

A section is given a section number which is comprised of one or two consecutive groups of (a) one positive integer whose highest digit MUST NOT be 0(zero) and (b) a dot. For example, "1." and "2.34." are both valid section numbers, while "5", "6.78", "9.10.11.", "12.D.", and "013.14" are not.

A regular expression for this is "^([1-9]\d*\.){1,2}".
A section is given a section number which is comprised of one or two consecutive groups of (a) one positive integer whose highest digit MUST NOT be 0(zero) and (b) a dot. For example, "1." and "2.34." are both valid section numbers, while "5", "6.78", "9.10.11.", "12.D.", and "013.14" are not. A regular expression for this is "^([1-9]\d*\.){1,2}".

### 2.5. Contents
All lines that are not any of the above or part of the page info are classified as the contents of the page. Contents in a wiki page SHOULD conform to the Gemini specs and write each paragraph as a single long line, and SHOULD NOT be hard-wrapped to a certain width.

When parsed by the machine for the purpose of e.g. editing, blank lines SHOULD NOT appear at the beginning or the end of a piece of content. However, when generating a human-readable wiki page, one blank line SHOULD be sandwiched between the last line of the aforementioned content and the next section or subsection heading, but SHOULD NOT be sandwiched between a heading and the content that follows.
As specified above, a section MAY contain subsections. In addition, it MAY also contain contents not belonging to any of its subsections. In such case, the contents MUST be located between the section heading and its first subsection. When a section has no subsections, its contents take up the section.

### 2.6. Page Info
### 2.5. Page Info