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.