summaryrefslogtreecommitdiff
path: root/README.md
blob: eb5a17aee9d1af82672c7fdf9161d533cf36c402 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
# uTab

## What

![Screenshot](https://fkfd.me/static/utab-0.3.0.png)

uTab (`[UuΜµ]{TAB|Tab|tab}`, pronounced you-tab, mu-tab, or microtab) is a New Tab daemon that runs on localhost to satisy your desire for cross-browser consistency of New Tabs. To enable it, read on.

## Why

I hopped from Firefox to Falkon (KDE's browser) a while ago. It doesn't offer many choices as to a new tab. The default home page is not useful, and the speed dial is buggy and slow. I miss the "Top Sites" in Firefox, which manifests your most frequently visited sites in a 8\*4 matrix. So I made this.

## How

Reluctant to squat on precious four-letter PyPI namespace, I did not upload utab to it, lest someone should foster a much better clone. Anyways, using this version of utab doesn't involve significantly more work than doing pip install.

### Installation

Assuming `python` == `python3.6` or higher:

1. Fetch source: `git clone https://git.sr.ht/~fkfd/utab`
2. Install: `cd utab && python setup.py install` (will install deps. append `--user` if desired.)

### Configs and Data

These are in your user data dir. For Linux, this is typically `~user/.local/share/utab/`.

What is in the dir? On default, these:

```
utab/
    css/
        index.css
    icons/
        home.svg
        pencil.svg
        plus.svg
    config.yml
    index.html
    site.html
    sites.csv
```

After due consideration, I picked whichever file format I considered most efficient to write, by machine and by hand. Let's explain some of the files.

#### `config.yml`

```yaml
columns: 8
rows: 4
engines:
  keyword:
    url: https://search.engine/?q={{query}}
  # example
  ddg:
    url: https://duckduckgo.com/?q={{query}}
  wk:
    url: https://en.wikipedia.org/wiki/{{query}}
default_engine: keyword
```

- `column/row`: Ezpz. Layout for your grid.
- `engines/default_engine`: An index of your search engines plus a default pointer. To use, type `/keyword query` into the search bar, e.g. `/wk HTTP` will search for HTTP on English Wikipedia.

#### `sites.csv`

| URL                | Title                | Favicon src             | Visits                                             |
| ------------------ | -------------------- | ----------------------- | -------------------------------------------------- |
| site URL, mandated | site title, optional | URL or base64, optional | integer, used to rank sites from highest to lowest |

Example:

```csv
https://en.wikipedia.org,English Wikipedia,https://en.wikipedia.org/static/favicon/wikipedia.ico,3
```

#### `*.html`

DST (Dead Simple Template) files[1]. Anything wrapped in `%` are injected with dynamic data, such as site headings.

#### `icons/*.svg`

Icons from [open-iconic](https://github.com/iconic/open-iconic). MIT License.

To change color, open them in a text editor (inkscape et al. will spew metadata all over the file). Modify `fill:#ffffff` to any other color in the `style` attribute of `<path>`.

### Running

To run it inside the command line, run `python -m utab`. It will start running as a daemon, on port 64366. To start it on startup, consider putting it in `.profile` or something. Then head to your web browser and switch the home page to `http://localhost:64366`.

### Updating

1. Make sure your working tree isn't polluted. Try applying `git stash` or moving your changes to another branch. In extreme cases, consult [xkcd #1597](https://xkcd.com/1597/).
2. Pull source: `git pull`
3. Install new version: `python setup.py install`
4. Your configs and data will remain untouched if they exist in your data dir. If you wish, you can copy some of them from `utab/data/` and overwrite the old ones. Alternatively, do a backup for your `sites.csv`, completely overwrite, then move that back in.

## Known Defects

- The grid doesn't align if there is an odd-numbered amount of cells on the last row when your grid width is even, and vice versa. Instead, they are centered.
- When you set title of a site too long, it will break into multiple lines and the cell will misalign (shift upward).
- The favicons are cached, or they are not. In the latter case, additional traffic cost may be induced.
- The CSS I wrote is the best exemplification of "it works on my machine".
- There are small `<a>` artifacts below the svg icons in the bottom.

![Two short purple lines each between two icons, each 4px wide](https://fkfd.me/static/utab-defect-link-artifact.png)

## Contributing

There are three ways to contribute. One is bug reports in the provided scope. If so, contact `fkfd at macaw dot me`. Another is feature requests. If I'm interested, I may spin up a mailing list and we collaborate. Then there's forking. This is the preferred method if you are to introduce a lot of changes. Configurability is limited by design in my version of utab, to make codebase lightweight. Fork this project and do whatever 0BSD allows (i.e. anything). Thank you.

## Usable Technology Certificate

[![UT badge](https://img.shields.io/badge/usable-technology-blue)](https://fkfd.me/ut/landing.html)

This is a piece of Usable Technology. It supports the philosophy that fewer restrictions should be imposed on individual developers, thereby maximizing the **community value**. It doesn't spoil anyone's fun, because 99% of the time it's another innocent person rather than an evil corp.

License: 0BSD  
Copyright: nope  
Forks: welcome; features intentionally lacking to encourage them. If you have a fork, contact me so I can add it here.

[1] Don't bother looking it up. There ain't such a thing.