From a7a3ddccec691ba319a600e2ac7cd81573f9e4aa Mon Sep 17 00:00:00 2001 From: nathaniel smith Date: Mon, 28 Aug 2017 16:51:27 -0700 Subject: [PATCH] first pass on RFC --- rfc.org | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 rfc.org diff --git a/rfc.org b/rfc.org new file mode 100644 index 0000000..30042f0 --- /dev/null +++ b/rfc.org @@ -0,0 +1,137 @@ +* tilde-wiki RFC + +Author: [[https://tilde.town/~vilmibm][~vilmibm]] +Status: in review +Date submitted: <2017-08-28 Mon> + + +** Background + + Many moons ago, I thought it would be interesting to have a user that we all + shared whose home directory was a git repo. In addition to being able to modify the shared + user's home directory, it had a public_html that could be filled with pretty standard wiki style content. + + Users took to the html portion of the wiki user and generated a lot of useful + content. the home directory / shared user aspect, however, was left untouched + for years. + + Thus, this RFC outlines both a shift to a formalized wiki that retains the + spirit of the origial idea (git based, shell oriented, low barrier to entry) + while streamlining and improving it. + +** Glossary + + - /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 + - /compiled/: a purely html version of the wiki content served through a web interface + - /source/: the raw files of the wiki in various formats (html, markdown, plaintext) + +** Proposal + + - the system path /wiki , a git repository (structure to follow). + - 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 + - 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 + + The following is the proposed layout for the wiki with sample files + + #+BEGIN_EXAMPLE + /wiki + |- .git/ + |- .gitignore + |- src/ + |-- toc.md + |-- header.md + |-- footer.md + |-- articles/ + |---- index.md + |---- new_user.md + |---- ssh.html + |---- editors/ + |------ vim.md + |------ ed.txt + |------ nano.html + |- compiled/ + |-- index.html + |-- new_user.html + |-- ssh.html + |-- editors/ + |---- vim.html + |---- ed.html + |---- nano.html + #+END_EXAMPLE + +** wiki Command + + The ~wiki~ command has 3 principles: + + 1. ~wiki~ should complement, not replace, ~git~ + 2. ~wiki~ subcommands take actions that can be easily summarized in a step-by-step way + 3. ~wiki~ should be fully documented both at rest (manual page) and live (-h, usage info) + +*** Subcommands + +**** init + - Clones /wiki to ~/wiki, erroring if directory exists + - Configures .git/config accordingly + - prints next steps +**** preview + - commits working tree + - compiles wiki + - if it doesn't exist, creates symlink ~/public_html/wiki pointing at ~/wiki/compiled + - prints link to ~user/wiki/ +**** publish + - commits working tree + - 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 succeeds, pushes to origin +**** get + - given a valid wiki path, opens it in w3m + - if no path, suggests creating it with ~$EDITOR~ +**** reset + - prompts y/N + - ~git fetch origin && git reset --hard origin~ + +** Web Presentation + + A guiding principle of this RFC is that the wiki should be comfortable to + view locally via w3m or similar. A CSS oriented table of content sidebar is + thus out of the question. Thus, I propose the following: + + - A standalone page, ~toc.html~, that lists the directory structure / pages of the wiki (i.e., a site map) + - A header with a site title (/The Tilde Town Wiki/, for example) and basic navigation + links (/home/, /table of contents/, /how to contribute/, /tilde.town home/) + - a footer with metadata (/page compile time/, /most recent author/) + - Source files in ~.txt~ format are turned into HTML naively; ~\n\n~ -> ~

~. + + Compiled HTML pages are put together naively: ie, it is assumed that the + content of a given page can be shoved into a ~~ element. + +**** Page titling + + After compiling to HTML but before combining with ~head.md~, if the first + line of a page's content is an h1 or h2 element its content will be used as + the ~~ of the page. + +** Open Questions + + I'd appreciate feedback on these questions (in addition to general feedback). + + 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? + 2. 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. + 3. Should the ~wiki~ command be implemented using Python's ~subprocess~ modules to call + out to ~git~ or use something like ~PyGit2~ or ~GitPython~? + +** Future Improvements + + - A macro system that can handle the following expansions: + - prefixing a string with ~: expands to a user's page link. e.g. /~vilmibm/ + - prefixing a string with ~wiki: expands to a wiki page link, e.g. /~wiki:editors/ed.html/ + - modify the ~wiki get <path>~ command to act as a local flavor replacement + of ~man~. This might look like a different compilation "target" distinct + from compiling HTML for the web.