tilde-wiki/rfc.org

* 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.