tilde-wiki/rfc.org

140 lines
5.4 KiB
Org Mode

* 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 4 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)
4. as needed, ~wiki~ should print human readable and informative errors.
*** 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 <path>
- 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~ -> ~</p><p>~.
Compiled HTML pages are put together naively: ie, it is assumed that the
content of a given page can be shoved into a ~<body>~ 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 ~<title>~ 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.
- An ~admin~ subcommand with subsubcommands that can start a tilde-style wiki
at an arbitrary path. For now, the initial seeding of ~/wiki~ is all manual.