nhanb/mcross

Simplest possible GUI browser for the gemini:// protocol, but no simpler. (this is a mirror - development happens over at sr.ht)

McRoss is a minimal and usable gemini:// browser written in python and tkinter, meaning it Just Works (tm) on any self-respecting desktop OS. I use and test it on Linux & Windows, but it should also run fine on macOS or any of the BSDs.

It currently looks like this:

Surfing plaintext and gemini content is already working well. The catch is it currently doesn't support downloading binary content and TOFU TLS verification. See feature checklist below for more details.

See my blog post for the rationale behind this project.

Installation

Dependencies are:

• python3.7+
• tkinter
• idlelib

idlelib is supposed to be included in the standard library but some linux distros split it into a separate package which you'll need to install manually. I know at least Ubuntu and Void Linux do this.

On Ubuntu:

sudo apt install python3 python3-pip python3-tk idle3
pip3 install --user mcross
# make sure ~/.local/bin is in $PATH first of course
mcross

On Arch:

sudo pacman -S python tk
pip install --user mcross

Also consider using pipx for a cleaner, better isolated installation.

Better distribution methods to be explored later. Maybe it's finally time to try nuitka?

Usage

Run mcross -h to get a full list of CLI arguments. The same arguments can also be defined in a TOML config file: run mcross-info to know where this file should be for your OS. For example, running mcross like this:

mcross --background-color pink -t "Ubuntu"

is the same as putting this in $HOME/.config/mcross/mcross.toml for linux:

background-color = "pink"
text-font = "Ubuntu"

The priority is CLI arg > config file > default.

Keyboard shortcuts:

• Ctrl-l: jump to address bar.
• Hold Alt to see possible button shortcuts underlined. This is what Qt calls Accelerator Keys.

Development

To get started:

pyenv install 3.7.7
pyenv virtualenv 3.7.7 mcross
pyenv activate
poetry install
mcross

# to publish, first bump version in pyproject.toml then
poetry publish --build

There are 2 McRoss-related mailing lists:

• ~nhanb/mcross-devel: discuss and submit your patches here
• ~nhanb/mcross-announce: low-volume announcement-only list

If you're not familiar with the mailing list workflow, check out git-send-email.io and mailing list etiquette. useplaintext.email also has useful plaintext setup tips for various email clients, though I don't necessarily agree with its "plaintext or nothing" stance.

Feature checklist

• back-forward buttons
• handle redirects
• non-blocking I/O using curio
• more visual indicators: waiting cursor, status bar
• parse gemini's advanced line types
• render text/* mime types with correct charset
• handle binary/* mime types
• configurable document styling
• human-friendly distribution
• TOFU TLS (right now it always accepts self-signed certs)

Long term high-level goals:

Easy for end users to install

If the words cargo build exists in the installation guide for your G U I application then I'm sorry it's not software made for people to use.

What-you-see-is-what-you-write

A rendered text/gemini viewport should preserve its original text content. This way once you've read a gemini page on the browser, you already know how to write one. No "View Source" necessary.

Responsive & pleasant to use

The Castor browser doesn't have visual indicators at all, for example, when clicking on a link it just appears to do nothing until the new page is completely loaded. That is A Bad Thing (tm).

Lightweight

In terms of both disk space & memory/cpu usage. The python/tkinter combo already puts us at a pretty good starting point.

Server bugs/surprises

Forces gemini:// in request

Spec says protocol part is optional, but if I omit that one the server will respond with 53 No proxying to other hosts!.

Newline

Spec says a newline should be \r\n but the server running gemini.circumlunar.space just uses \n every time.

License

Copyright (C) 2020 Bùi Thành Nhân

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Forks

McRoss development is... conservative and sporadic. If that bothers you, check out picross which is a nice fork with more features (TOFU, tabs, among other things).

mcross's Issues

screenshots

Support for the spartan protocol

Hi,

I don't know what your stand is on the support of other small net protocols in your project, but please close if this is out of scope of this project.

The spartan protocol has been developed with a similar rationale as gemini, less the TLS layer and with a lighter protocol specification. On top of that, the content is expected to be served with the existing text/gemini standard, so no significant change is to be expected on the presentation layer.

When compared with other smallnet clients, your project has the advantage to be portable outside of 64 bits platforms, and I thought you might be interested.

Kind regards,