From cb1c8f8563868979f20be4e4d20a61bee5504821 Mon Sep 17 00:00:00 2001 From: Přemysl Eric Janouch Date: Wed, 12 Aug 2020 01:40:45 +0200 Subject: Render the README as AsciiDoc The little issues aren't worth the monospace font in Gitea. --- README | 294 ------------------------------------------------------------ README.adoc | 294 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 294 insertions(+), 294 deletions(-) delete mode 100644 README create mode 100644 README.adoc diff --git a/README b/README deleted file mode 100644 index f5fab4c..0000000 --- a/README +++ /dev/null @@ -1,294 +0,0 @@ -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. 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. -- cgit v1.2.3-70-g09d2