update rfc

master
nathaniel smith 2017-08-28 23:23:31 -07:00
parent 91286dd639
commit e6a5738b0a
1 changed files with 27 additions and 18 deletions

43
rfc.org
View File

@ -1,7 +1,7 @@
* tilde-wiki RFC * tilde-wiki RFC
| Author | [[https://tilde.town/~vilmibm][~vilmibm]] | | Author | [[https://tilde.town/~vilmibm][~vilmibm]] |
| Status | in review | | Status | accepted |
| Date Submitted | <2017-08-28 Mon> | | Date Submitted | <2017-08-28 Mon> |
** Background ** Background
@ -22,8 +22,8 @@
- /the wiki/: the files in a git repo that constitute the town's wiki content. accessible by command line or web. - /the wiki/: the files in a git repo that constitute the town's wiki content. accessible by command line or web.
- ~wiki~: the ~wiki~ command, used locally to work on the wiki and publish changes - ~wiki~: the ~wiki~ command, used locally to work on the wiki and publish changes
- /compiled/: a purely html version of the wiki content served through a web interface - ~tildetown/wiki~: a github repo for storing the content of our wiki
- /source/: the raw files of the wiki in various formats (html, markdown, plaintext) - ~tildetown/tilde-wiki~: a github repo for storing the ~wiki~ command
** Proposal ** Proposal
@ -31,7 +31,6 @@
- the url tilde.town/wiki, configured at nginx level to serve system path /wiki/compiled - the url tilde.town/wiki, configured at nginx level to serve system path /wiki/compiled
- Deleting the wiki user and setting a redirect in nginx from /~wiki to /wiki - Deleting the wiki user and setting a redirect in nginx from /~wiki to /wiki
- a ~wiki~ command used for initializing, adding to, and publishing the wiki - a ~wiki~ command used for initializing, adding to, and publishing the wiki
- a convention of symlinking from ~/wiki/compiled to ~/public_html/wiki so people can preview their edits
** Wiki Layout ** Wiki Layout
@ -41,6 +40,7 @@
/wiki /wiki
|- .git/ |- .git/
|- .gitignore |- .gitignore
|- wiki-githooks
|- src/ |- src/
|-- toc.md |-- toc.md
|-- header.md |-- header.md
@ -53,16 +53,21 @@
|------ vim.md |------ vim.md
|------ ed.txt |------ ed.txt
|------ nano.html |------ nano.html
|- compiled/
|-- index.html
|-- new_user.html
|-- ssh.html
|-- editors/
|---- vim.html
|---- ed.html
|---- nano.html
#+END_EXAMPLE #+END_EXAMPLE
After a ~wiki publish~, the resulting site structure will look like this:
#+BEGIN_EXAMPLE
/var/www/tilde.town/html/wiki/
|- index.html
|- new_user.html
|- ssh.html
|- editors/
|-- ed.html
|-- nano.html
|-- vim.html
#+END_EXAMPLE
** wiki Command ** wiki Command
The ~wiki~ command has 4 principles: The ~wiki~ command has 4 principles:
@ -80,14 +85,14 @@
- prints next steps - prints next steps
**** preview **** preview
- commits working tree - commits working tree
- compiles wiki - compiles wiki to ~/~/public_html/wiki~
- if it doesn't exist, creates symlink ~/public_html/wiki pointing at ~/wiki/compiled - prints link to https://tilde.town/~user/wiki/
- prints link to ~user/wiki/
**** publish **** publish
- commits working tree - commits working tree
- attempts to pull from origin - attempts to pull from origin
- if this fails, reports on the failure and says to fall back to ~git~ or ask for help - if this fails, reports on the failure and says to fall back to ~git~ or ask for help
- if this succeeds, pushes to origin - if this succeeds, pushes to origin
- compiles all source files and outputs to ~/var/www/tilde.town/wiki~
**** get <path> **** get <path>
- given a valid wiki path, opens it in w3m - given a valid wiki path, opens it in w3m
- if no path, suggests creating it with ~$EDITOR~ - if no path, suggests creating it with ~$EDITOR~
@ -95,6 +100,9 @@
- prompts y/N - prompts y/N
- ~git fetch origin && git reset --hard origin~ - ~git fetch origin && git reset --hard origin~
NB: preview and publish both audit all links in changed files for absolute
links to the wiki and error, explaining relative links.
** Web Presentation ** Web Presentation
A guiding principle of this RFC is that the wiki should be comfortable to A guiding principle of this RFC is that the wiki should be comfortable to
@ -122,9 +130,10 @@
1. The ~compiled/~ directory is ignored by git, but compiled both locally and remotely. 1. The ~compiled/~ directory is ignored by git, but compiled both locally and remotely.
Does this make sense? Should it not live in the folder at all? Does this make sense? Should it not live in the folder at all?
2. is ~/wiki/src/articles/~ too deep of a path? is it cumbersome? i like that it is - After discussing with \~datagrok, I've decided to target directories outside the repo for compilation.
3. is ~/wiki/src/articles/~ too deep of a path? is it cumbersome? i like that it is
explicit and i have a policy of erring on the side of explicitness. explicit and i have a policy of erring on the side of explicitness.
3. Should the ~wiki~ command be implemented using Python's ~subprocess~ modules to call 4. Should the ~wiki~ command be implemented using Python's ~subprocess~ modules to call
out to ~git~ or use something like ~PyGit2~ or ~GitPython~? out to ~git~ or use something like ~PyGit2~ or ~GitPython~?
** Future Improvements ** Future Improvements