Render the README as AsciiDoc

The little issues aren't worth the monospace font in Gitea.

1 files changed, 294 insertions, 0 deletions

diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..f5fab4c
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,294 @@
+Project haven
+=============
+
+haven is an umbrella project for a range of mostly desktop applications.
+
+Goal
+----
+The greater goal is to create a fresh computing environment for daily work and
+play--easily controllable, reasonably complex, both visually and internally
+unified and last but not least responsive.  One should be able to use it
+comfortably with a 60% keyboard and no pointing device.
+
+haven serves as a testing ground, leaning on the side of compromises.  It aims
+to use today's Linux desktop as a support, relying on X11/Wayland, existing
+window managers and web browsers.
+
+The focus is therefore on going breadth-first, not depth-first.  Applications
+only need to be good enough to be able to replace their older siblings at all.
+I.e. for me personally.
+
+Scope
+-----
+Subproject names aim to have the minimum viable, reasonably identifiable name.
+To group them together, a common prefix of "h" is used.  The second column is
+what should be used as the name in .desktop files, just like the GNOME project
+figured out it would make sense:
+
+ - hbe  - bitmap editor
+ - hbfe - bitmap font editor
+ - he   - text editor
+ - hfm  - file manager
+ - hib  - IRC bouncer
+ - hic  - IRC client
+ - hid  - IRC daemon
+ - hiv  - image viewer
+ - hm   - mail client
+ - hmpc - MPD client
+ - hnc  - netcat-alike
+ - ho   - all-powerful organizer
+ - hsm  - system monitor
+ - hss  - spreadsheets
+ - htd  - translation dictionary
+ - ht   - terminal emulator
+ - htk  - GUI toolkit library
+
+See Projects for more information about the individual projects.
+
+Some taken names in Debian: hd (important), hte, hy.
+
+Identity
+--------
+The name merely hints at motivations and otherwise isn't of any practical
+significance other than that we need an identifier.  This time I resisted using
+something offensive for personal amusement.
+
+A logo covering the entire project is not needed and it seems hard to figure out
+anything meaninful anyway, though we might pick a specific font to use for the
+project name <1>.
+
+The only mascot I can think of would be a black and white or generally grayscale
+My Little Pony OC but I don't really want to bring my own kinks into the project
+and I'd also need to learn how to draw one so that I don't infringe on someone
+else's copyright, or find someone else to do it.  Anyway, in lack of a proper
+logo, she could have a simple "h" or "hvn" for a cutie mark <2>.
+
+         __
+ <2>   _/ /_    <1>  | _     _          _    _
+      \  _  \        |/ \   / \| \  /  /_\ |/ \
+      / / / /        |   | |   | \  / |    |   |
+     /_/ /_/         |   |  \_/|  \/   \_/ |   |
+
+I'm not sure where I took this "h" letter styling from, it seems too familiar.
+The above illustrations also show how awful it looks when a logo is just
+a stylized version of the first letter of a name when you put the two next to
+each other.  Distinctly redundant.  Facebook and Twitter are doing fine, though,
+perhaps because they do not use them together like that.
+
+Technicalities
+--------------
+
+Languages
+~~~~~~~~~
+Primarily Golang with limited C interfacing glue, secondarily C++17, mostly for
+when the former cannot be reasonably used because of dependencies.
+
+Build system
+~~~~~~~~~~~~
+https://github.com/zevv/bucklespring is a good example of a rather simplified
+project that makes do with a single Makefile, even for cross-compilation on
+Windows.  Let us avoid CMake and the likes of it.
+
+It seems that Go can link dynamically, therefore I could build libhaven.so
+(https://docs.google.com/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ
+and https://stackoverflow.com/questions/1757090/shared-library-in-go)
+and have the rest of the package as rather small binaries linking to it.
+The "cannot implicitly include runtime/cgo in a shared library" error is solved
+by "go install", which again requires "-pkgdir" because of privileges.
+libstd.so is a beautiful 30 megabytes (compared to libc.a: 4.9M).
+
+GUI
+~~~
+Probably build on top of X11/Xlib or xgb<1>.  Wayland can wait until it
+stabilizes--it should not be a major issue switching the backends.
+Vector graphics can be handled by draw2d<2>.
+
+<1> https://rosettacode.org/wiki/Window_creation/X11#Go
+<2> https://github.com/llgcode/draw2d
+
+The c2 wiki unsurprisingly has a lot of material around the design and
+realisation of GUIs, which might be useful.
+
+It seems like an aligning/constraint-based "layout manager" will be one of the
+first harder problems here.  However I certainly don't want to use fixed
+coordinates as they would introduce problems with different fonts and i18n.
+
+We could use BDF fonts from the X11 distribution, but draw2d has native support
+for FreeType fonts and it's more of a choice between vectors and bitmaps.
+
+The looks will be heavily inspired by Haiku and Windows 2000 and the user will
+have no say in this, for simplicity.
+
+.Resources:
+ - https://github.com/golang/exp/tree/master/shiny is a GUI library
+ - https://github.com/as/shiny is a fork of it
+ - http://man.cat-v.org/plan_9/1/rio has a particular, unusual model
+
+Internationalisation
+~~~~~~~~~~~~~~~~~~~~
+For i18n https://github.com/leonelquinteros/gotext could be used, however I'll
+probably give up on this issue as I'm fine enough with English.
+
+Go also has x/text packages for this purpose, which might be better than GNU,
+but they're essentially still in development.
+
+Versioning
+~~~~~~~~~~
+Versions are for end users.  We can use a zero-based, strictly increasing
+number, be it a simple sequence or date-based numbers such as 1807.  If we do
+this at all, we will eventually also need to release patch versions.
+
+Since dates don't seem to convey important information, let us settle on 0, 1,
+1.1, 2, 3, 3.1, 3.2, ...  In practice releases are going to be scarce, unless
+we find a person to take care of it.  Note that there is no major/minor pair--
+a new project will be created when radical philosophical or architectural
+changes are to be made.  See Goal.
+
+Projects
+--------
+These are sorted in the order in which they should be created in order to gain
+the best possible momentum.  The htk GUI toolkit is implied as a side product
+permeating the entire list.
+
+Some information is omitted from these descriptions and lies either in my head
+or in my other notes.
+
+hid -- IRC daemon
+~~~~~~~~~~~~~~~~~
+This project is unimportant by itself, its sole purpose is to gain experience
+with Go on something that I have already done and understand well.  Nothing
+beyond achieving feature parity is in the initial scope.
+
+One possibility of complicating would be adding simple WebSocket listeners but
+that's already been done for me https://github.com/kiwiirc/webircgateway and
+it's even in Go, I just need to set up kiwiirc.
+
+Later, when we have a pleasant IRC client, implement either the P10 or the TS6
+server-linking protocol and make atheme work with a generic module.
+Alternatively add support for plugins.  The goal is to allow creating integrated
+bridges to various public forums.
+
+hnc -- netcat-alike
+~~~~~~~~~~~~~~~~~~~
+The result of testing hid with telnet, OpenSSL s_client, OpenBSD nc, GNU nc and
+Ncat is that neither of them can properly shutdown the connection.  We need
+a good implementation with TLS support.
+
+hpcu -- PRIMARY-CLIPBOARD unifier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An improved replacement for autocutsel in selection synchronization "mode":
+
+ - using only one OS process;
+ - not polling selections twice a second unnecessarily;
+ - calling SetSelectionOwner on change even when it already owns the selection,
+   so that XFIXES SelectionNotify events are delivered;
+ - not using cut buffers for anything.
+
+Only UTF8_STRING-convertible selections are synchronized.
+
+hasp -- (lib)asciidoc syntax preprocessor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Provisional tool to make libasciidoc understand more syntax, namely
+two-line/underlined titles for my Gitea projects.
+
+ht -- terminal emulator
+~~~~~~~~~~~~~~~~~~~~~~~
+Similar scope to st(1).  Clever display of internal padding for better looks.
+
+hib and hic -- IRC bouncer and client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An IRC client is a good starting application for building a GUI toolkit, as the
+UI can afford to be truly minimalistic and most of it is text.
+
+To resolve an issue I have with my current IRC client, the client is going to be
+split into two parts: a bouncer that manages all connections and state, and
+a separate GUI that communicates with the backend over TLS/WebSocket.  Perhaps
+only the per-buffer input line is going to be desynchronized.
+
+https://godoc.org/github.com/gorilla/websocket
+
+The higher-level client-server API could be made rather generic to allow for
+smooth integration with non-IRC "backends" such as Slack or Mattermost.
+
+he -- text editor
+~~~~~~~~~~~~~~~~~
+VIM controls, no scripting, no syntax highlight, single-file, made for
+variable-width/proportional fonts.  Initially done primarily to produce a text
+editing widget, which is going to be an interesting challenge, arguably better
+solved by whole program composition.  Scintilla may provide some inspiration.
+
+In the second stage, support for the Language Server Protocol will be added so
+that the project can be edited using its own tools.  Some scripting, perhaps
+a tiny subset of VimL, might be desirable.  Or other means of configuration.
+
+Visual block mode or the color column may still be implemented.
+
+The real model for the editor is Qt Creator with FakeVIM, though this is not to
+be a clone of it, e.g. the various "Output" lists could be just special buffers,
+which may be have names starting on "// ".
+
+.Resources:
+ - http://doc.cat-v.org/plan_9/4th_edition/papers/sam/
+
+ho -- all-powerful organizer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Zettelkasten with fulltext search, arbitrary reciprocal links, arbitrary tags.
+Flat storage.  Should be able to use translation dictionaries for search hints.
+
+Indexing and search may be based on a common database, no need to get all fancy:
+
+ - http://rachbelaid.com/postgres-full-text-search-is-good-enough/
+ - https://www.sqlite.org/fts3.html#full_text_index_queries (FTS4 seems better)
+
+htd -- translation dictionary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This specific kind of application doesn't need a lot of user interface either,
+just a tab bar, text entry and two columns of text with simple formatting.
+
+For simplicity we will establish a custom dictionary format based on either
+simple compress/gzip with separate files in StarDict style or, since we don't
+really strive for random access and memory-efficiency (those 120M that sdtui
+takes with my 10 dictionaries isn't particularly bad), pack everything with
+archive/zip.
+
+Instead of ICU we may use x/text/collate and that's about everything we need.
+Since we have our own format, we may expect the index to be ordered by the
+locale's rules, assuming they don't change between versions.
+
+hmpc -- MPD client
+~~~~~~~~~~~~~~~~~~
+Here the focus will be on the GUI toolkit.  I don't expect this application to
+get big, since its predecessor nncmpp isn't either.  The daemon takes care of
+all complex stuff.  It would be nice to add lyrics and search later, though.
+
+hiv -- image viewer
+~~~~~~~~~~~~~~~~~~~
+JPG, PNG, first frame of GIF.  Zoom.  Going through adjacent files in directory
+using cursor keys.  Possibly a dialog with image metadata.
+
+hfm -- file manager
+~~~~~~~~~~~~~~~~~~~
+All we need to achieve here is replace Midnight Commander, which besides the
+most basic features includes a VFS for archives.  The editing widget in
+read-only mode could be used for F3.  The shell is going to work very simply,
+creating a PTY device and running things under TERM=dumb while decoding SGR,
+or one could decide to run a new terminal emulator with a different shortcut.
+ht could probably also be integrated.
+
+Eventually the number of panels should be arbitrary with proper shortcuts for
+working with them.  We might also integrate a special view for picture previews,
+which might or might not deserve its own program.
+
+hss -- spreadsheets
+~~~~~~~~~~~~~~~~~~~
+The first version doesn't need to be able to reference other cells, and can more
+or less be a CSV editor.
+
+We can take inspiration from Excel:
+
+ - https://docs.microsoft.com/en-us/office/client-developer/excel/excel-recalculation
+ - https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
+
+The rest
+~~~~~~~~
+Currently there are no significant, specific plans about the other applications.