shithub: docs.9front.org

--- a/index.md

+++ b/index.md

@@ -13,6 +13,7 @@

 The document source repository is currently hosted and available

 for browsing

 [here](https://git.sr.ht/~kvik/docs.9front.org).

 Get it locally for reading:

 	git/clone https://git.sr.ht/~kvik/docs.9front.org

@@ -22,13 +23,13 @@

 	git/clone ssh://git@git.sr.ht/~kvik/docs.9front.org

 Everyone is invited to get write access by asking (kvik) on IRC, grid,

-or kvik@a-b.xyz.  Otherwise you may submit patches by usual contribution

-mechanisms supported by [sr.ht](https://sr.ht), or by sending a mail

-to the 9front@9front.org mailing list, or privately to your favorite

+or kvik@a-b.xyz.  Otherwise you may submit patches through contribution

+mechanisms on [sr.ht](https://sr.ht), by sending a mail to the

+9front@9front.org mailing list, or communicating with your favorite

 editor.

-The contributed documents are mostly expected to be markdown

-files, denoted by a `.md` file extension.

+Contributed documents are mostly expected to be markdown-formatted

+files, denoted by the `.md` file extension.

 The formatting syntax used by the markdown processor

 [discount](https://github.com/Orc/discount)

@@ -35,39 +36,34 @@

 used by the backend is documented in the manual page

 [markdown(6)](http://a-b.xyz/6e/c837).

-In addition to markdown files, raw text files and HTML documents may be

-entered into the repository using the file extensions `.txt` and

-`.shtml`, respectively.  These files will copied verbatim into the

-rendered document tree.

+Additionally, plain text files and HTML documents may be entered into

+the repository with file extensions `.txt` and `.shtml`, respectively.

+These will be copied verbatim into the rendered document tree.

-**Note** Only one of `a.md`, `a.txt`, or `a.shtml` may exist in the

-repository at the same time.  This failing will prevent rendering of

-the entire tree.  This may or may not be fixed in the future.

+**Warning** only one of `a.md`, `a.txt`, or `a.shtml` may exist at

+the same time.  Otherwise the document generation will fail. This is

+a problem with the current implementation and may be fixed in the

+future.

+Images and other static content is best hosted outside this repository.

+Dedicated upload and stable link space may be provided later.

 Reading

 -------

-The source content available in the repository, as well as

-HTML pages generated from the markdown sources, are presented

-for reading using 9p and HTTP interfaces at

-[docs.a-b.xyz](http://docs.a-b.xyz).

+Document updates are periodically fetched by the backend, which then

+renders the document tree and makes it available for reading via 9p and

+HTTP.

-The updates to the docs repository are periodically pulled by the

-backend, which renders and publishes the updated documents.

-TODO: Describe how the backend works in more detail? This would

-be useful to allow people to preview their work locally.

 ### 9p

-The document tree may be mounted from Plan 9 as follows:

+On Plan 9, run:

-	9fs tcp!docs.a-b.xyz!909 /n/doc

+	9fs tcp!docs.a-b.xyz!909 /n/docs

 ### HTTP

-The document tree may be viewed with a web browser at

-[docs.a-b.xyz](http://docs.a-b.xyz)

+Visit [docs.a-b.xyz](http://docs.a-b.xyz) with a web browser.

 Index

 -----

@@ -75,10 +71,10 @@

 Until some form of indexing and autolinking is implemented please

 link to your pages from one of the top-level documents.

-Warning

--------

+THIS

+----

-Again, this is a prototype presented to the community for evaluation,

-development, and bikeshedding. If it does well it would probably be

-best to rehome the git repository to a 9front-based host and move or

-set up redirects from a [9front.org](http://9front.org) zone.

+This prototype is presented to the community for evaluation,

+development, and bikeshedding.

+Any input is appreciated, especially criticism.