about summary refs log tree commit diff stats
path: root/dwm.html
blob: bb8e22dff19301938eda7f0c47e4bfe75323b623 (plain) (blame)
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
<html>
	<head>
		<title>dwm - dynamic window manager</title>
		<meta name="author" content="Anselm R. Garbe">
		<meta name="generator" content="ed">
		<meta name="copyright" content="(C)opyright 2006 by Anselm R. Garbe">
		<style type="text/css">
			body {
				color: #000000;
				font-family: sans-serif;
				margin: 20px 20px 20px 20px;
			}
		</style>
	</head>
	<body>
		<center>
			<img src="dwm.png"/><br />
			<h3>dynamic window manager</h3>
		</center>
		<h3>Description</h3>
		<p>
		dwm is a dynamic window manager for X11.
		</p>
		<h4>Philosophy</h4>
		<p>
		As founder and main developer of wmii I came to the conclusion that
		wmii is too clunky for my needs. I don't need so many funky features
		and all this hype about remote control through a 9P service, I only
		want to manage my windows in a simple, but dynamic way. wmii never got
		finished because I listened to users, who proposed arbitrary ideas I
		considered useful. This resulted in an extreme <a
		href="http://www.jwz.org/doc/cadt.html">CADT</a> development model,
		which was a mistake. Thus the philosophy of dwm is simply <i>to fit my
		needs</i> (maybe yours as well). That's it.
		</p>
		<h4>Differences to ion, larswm, and wmii</h4>
		<p>
		In contrast to ion, larswm, and wmii, dwm is much smaller, faster and simpler.
		</p>
		<ul>
			<li>
			dwm has no Lua integration, no 9P support, no menu, no editable
			tagbars, no shell-based configuration, no remote control, and comes
			without any additional tools like printing the selection or warping
			the mouse.
			</li>
			<li>
			dwm is only a single binary, it's source code is intended to never
			exceed 2000 SLOC.
			</li>
			<li>
			dwm is based on tagging and dynamic window management (however
			simpler than ion, wmii or larswm). It manages windows in
			tiling and floating modes. Either mode can be applied dynamically,
			depending on the application in use and the task performed.
			</li>
			<li>
			dwm don't distinguishes between layers, there is no floating or
			tiled layer. Wether the clients of currently selected tag are in
			tiled mode or not, you can re-arrange all clients on the fly.
			Popup- and fixed-size windows are treated floating, however. 
			</li>
			<li>
			dwm is customized through editing its source code, that makes it
			extremely fast and secure - it does not process any input data
			which hasn't been known at compile time, except window title names
			and status text read from standard input. You don't have to learn
			Lua/sh/ruby or some weird configuration file format (like X
			resource files), beside C to customize it for your needs,
			you <b>only</b> have to learn C.
			</li>
			<li>
			Because dwm is customized through editing its source code, it's
			pointless to make binary packages of it. This keeps its userbase
			small and elitist. No novices asking stupid questions.
			</li>
			<li>
			dwm uses 1-pixel borders to provide the maximum of screen real
			estate to clients. Small titlebars are only drawn in front of
			unfocused clients.
			</li>
			<li>
			dwm reads from standard input to print arbitrary status text (like
			the date, load, battery charge). That's much simpler than
			larsremote, wmiir and what not...
			</li>
			<li>
			It can be downloaded and distributed under the conditions
			of the <a href="http://10kloc.org/cgi-bin/hgwebdir.cgi/dwm?f=f10eb1139362;file=LICENSE;style=raw">MIT/X Consortium license</a>.
			</li>
		</ul>
		<h4>Links</h4>
		<ul>
			<li><a href="http://10kloc.org/cgi-bin/man/man2html?query=dwm">Man page</a></li>
			<li><a href="http://10kloc.org/shots/dwm-20060714.png">Screenshot</a> (20060714)</li>
			<li><a href="http://10kloc.org/download/poster.ps">A4 poster (PostScript)</a></li>
			<li>Mailing List: <a href="http://10kloc.org/cgi-bin/mailman/listinfo/dwm">dwm at wmii dot de</a> <a href="http://10kloc.org/pipermail/dwm/">(Archives)</a></li>
			<li>IRC channel: <code>#dwm</code> at <code>irc.oftc.net</code></li>
		</ul>
		<h3>Development</h3>
		<p>
		dwm is actively developed in parallel to wmii. You can <a href="http://10kloc.org/cgi-bin/hgwebdir.cgi/dwm">browse</a> its source code repository or get a copy using <a href="http://www.selenic.com/mercurial/">Mercurial</a> with following command:
		</p>
		<p>
		<code>hg clone http://10kloc.org/cgi-bin/hgwebdir.cgi/dwm</code>
		</p>
		<h3>Download</h3>
		<ul>
			<li><a href="http://10kloc.org/download/dwm-0.5.tar.gz">dwm 0.5</a> (13kb) (20060721)</li>
		</ul>
		<h3>Miscellaneous</h3>
		<p>
		You can purchase this <a href="https://www.spreadshirt.net/shop.php?op=article&article_id=3298632&view=403">tricot</a>
		if you like dwm and the dwm logo, which has been designed by Anselm.
		</p>
		<p><small>--Anselm (20060719)</small></p>
	</body>
</html>
0 -0700 .' href='/akkartik/teliva/commit/README.md?id=8d5d27af0c206b827e379c67c7073b71251bb275'>8d5d27a ^
1b25d58 ^


917646f ^
1e63a57 ^




e43cdbe ^
440f6e9 ^
8d5d27a ^
e43cdbe ^

440f6e9 ^


8d5d27a ^
6eecba1 ^



516ac2f ^

47e4224 ^

c4984c2 ^

31af4bd ^








516ac2f ^
f204dff ^













e43cdbe ^
156f978 ^
4dffcac ^
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
                                                  
 

                                                                                            
 

                                                                                                
 





                                                                                      

                                                                             
 

                                                                                                                
     

                                            
                                                                 
                    

   

                                                                                
                                                                        










                                                                                                  
 
                                                                           









                                                                             
 












































                                                                              


                                                                              

                                                                          
 






                                                                             






                                                                          


                                                                              
                                                                  
 

                                                                            
 

                                                                            
 
                                                                          
                                                                             
                                             
 

                                                                              
                                                    
 



                                                                             
 

                                                                           
 





                                                                             
                                                                              

                                                                         
 















                                                                                                            
 
                                                                            
                                                                     
 


                                                                      
              




                                                                            
                                                                                                                    
                                                                                                                          
 

                                                                              


                                                                                                                
 



                                                                         

               

                                                                         

                                                                         








                                                                             
 













                                                                         
           
 
                                                 
# Teliva - an environment for end-user programming

> &ldquo;Enable all people to modify the software they use in the course of using it.&rdquo;
> &mdash; https://futureofcoding.org/episodes/033.html

> &ldquo;What if we, and all computer users, could reach in and modify our favorite apps?&rdquo;
> &mdash; https://www.inkandswitch.com/end-user-programming

> &ldquo;Software must be as easy to change as it is to use.&rdquo;
> &mdash; https://malleable.systems

## What's this, then?

An extremely naïve, [brutalist](https://en.wikipedia.org/wiki/Brutalist_architecture)
environment for little text-mode [Lua](http://www.lua.org) apps that are easy
to modify.

Here's how you run one of the example apps (the [Tower of Hanoi](https://en.wikipedia.org/wiki/Tower_of_Hanoi)):

```sh
git clone https://github.com/akkartik/teliva
cd teliva
make linux  # replace with 'macosx' or 'bsd' depending on your OS
src/teliva hanoi.tlv
```

<img alt='screenshot of Teliva running the Towers of Hanoi' src='doc/hanoi.png'>

No matter what app you run, you are always guaranteed access to a single
obvious, consistent way (currently the hotkey `ctrl-e`) to inspect its
sources.

When you look under the hood of an app, the first thing you see is a
_big-picture view_ which shows the app's major data structures and a top-down
view of the app's code.

<img alt='screenshot of big-picture view for the Towers of Hanoi' src='doc/hanoi-big-picture.png'>

Select a definition, make a change, hit `ctrl-e` again, and the app will run
with your updates. ([video](https://archive.org/details/akkartik-2021-11-14))

You will need some Unix-like platform with a C compiler and the ncurses and
openssl libraries. Some possible commands to install them, depending on your
OS and package manager of choice:

* `guix shell -D lua openssl -- make linux`
* `nix-shell --pure` (from a directory containing shell.nix in this repo)
* `sudo apt install libncursesw6-dev openssl`
* `brew install ncurses openssl`

So far I've tested Teliva on Linux, Mac OS X and OpenBSD; it should also work
on other flavors of BSD, WSL on Windows, etc. with only minor modifications.

## What else can it do?

Anything! Some more sample apps to try out:

* Conway's Game of Life, as an example of an animated local app.
  ```
  src/teliva life.tlv
  ```

  [video](https://merveilles.town/@akkartik/107277755421024772)

* A viewer for [LiChess TV](https://lichess.org/tv), as an example of
  animation and accessing a remote API over a network.
  ```
  src/teliva chesstv.tlv
  ```

  [video](https://merveilles.town/@akkartik/107319684018301051)

* A browser for the [Gemini protocol](https://gemini.circumlunar.space).
  ```
  src/teliva gemini.tlv
  ```

  [video](https://merveilles.town/@akkartik/107489728557201145)

These are just a start. The sky is the limit.

## So, just a programming language, then?

There's one big difference with other programming languages: Teliva apps are
sandboxed like a browser. Most languages assume the fiction that the person
running a program trusts all the code in the program. This assumption hasn't
been valid since a decade after the Unix big bang, if then. Teliva takes on
the reality that apps can get complex and use code written by strangers. In
response, Teliva tries to always summarize for you what the program you're
running is trying to do, and to ask you before a random app tries to do
something sensitive. Permissions you grant a Teliva app will be _flexible_ and
_easy to understand_. Browsers and mobile apps today tend to make you choose
between those two properties.

Sandboxing is still in progress. It isn't yet safe to run untrusted Teliva
apps you download from the internet. (Fortunately you're unlikely to run into
any such apps.)

## Isn't this just an IDE?

There's one big difference: these apps are not intended to be runnable outside
of the Teliva environment. Editing the sources and visualizing permissions
granted will always be core features that are front and center in the UI.

A second, more subtle difference: it's primarily an environment for _running_
apps, and only secondarily for editing them. Starting up the environment puts
you in a running app by default. Creating an app from a clean slate is a
low-priority use case, as is lots of specialized support for developing
complex apps. The sweet spot for Teliva is simple apps that people will want
to edit after using for a while.

## Why Lua?

It's reputedly the fastest interpreted language per line of implementation
code.

## Will it run any Lua program?

Not quite. My priority is providing a good experience for newcomers to
comprehend and modify the programs they use. If it's not clear how to provide
that experience for some kinds of Lua programs, I'd rather disable support for
them in Teliva and let people use regular Lua. Or other platforms!

- This approach doesn't make sense for batch programs, I think. I also don't
  yet have a good story for building server programs in this way.

- I don't know how to obtain a simple, shallow graphics stack, so there's no
  support for graphics at the moment.

- Teliva initializes the ncurses library by default, so apps should assume
  they have access to a (color, UTF-8) text-mode window for printing text to,
  and a keyboard for reading keystrokes from.

- Teliva doesn't use files for source code, so the `require` keyword no longer
  makes sense. You get some libraries preloaded (see below). Beyond those,
  apps should include all Lua code they want to use.

- I want to provide sandboxed access to system resources (file system,
  network, etc.) which will likely create incompatibilities with the standard
  library. I'm disinclined to try to &lsquo;improve&rsquo; on Lua syntax,
  however. It's not my favorite, but it's good enough.

- To create a well-behaved sandbox, Teliva doesn't support adding libraries
  with C bindings beyond the few it starts up with.

- Functions that start with `test_` are special. They're considered automated
  tests and called without arguments every time an app starts up.

- The function `main` is special. It runs every time an app starts up, if all
  its automated tests pass.

Teliva is not tested much at all yet. This is my first time programming either
in Lua or within Lua. So bug reports are most appreciated if Lua programs
behave unexpectedly under Teliva.

## What's included?

* [Lua 5.1](https://www.lua.org/manual/5.1)
* The [ncurses](https://tldp.org/HOWTO/NCURSES-Programming-HOWTO) library for
  building text-mode user interfaces. ([Alternative documentation](https://tldp.org/LDP/lpg-0.4.pdf))
* The [Kilo](https://github.com/antirez/kilo) text editor, modified to use
  ncurses. (Read more about it in this [fantastic walk-through](https://viewsourcecode.org/snaptoken/kilo).)
* The [lcurses](https://github.com/lcurses/lcurses) binding for ncurses (as
  module `curses`).
* The [luasocket](https://w3.impa.br/~diego/software/luasocket) library of
  networking primitives (modules `socket`, `http`, `url`, `headers`, `mime`,
  `ltn12`).
* The [luasec](https://github.com/brunoos/luasec) library for HTTPS support
  (modules `https` and `ssl`).
* The [json.lua](https://github.com/rxi/json.lua) library for
  serializing/deserializing to JSON (module `json`).

The modules mentioned above are always available, just like standard Lua 5.1
libraries. However, a few things are different from conventional Lua:

* Some functions are disabled because I don't know how to sandbox them
  effectively:
  - `os.execute`
  - `io.popen`
* Some functions are disabled because they don't seem to make sense in an
  ncurses environment. This includes the Lua notions of default files, which
  start out as stdin/stdout.
  - `io.input`, `io.read`
  - `io.output`, `io.write`, `io.flush`
* Some functions in lcurses have [additional smarts](https://github.com/lcurses/lcurses/blob/master/lib/curses.lua).
  Teliva is [consistent with the underlying ncurses](https://github.com/akkartik/teliva/blob/main/src/lcurses/curses.lua).

While most things in these modules are currently available, I expect to delete
capabilities throughout this stack as I discover features that don't fit well
with the Teliva experience. If you find Teliva of use, please [introduce yourself](http://akkartik.name/contact)
to me so that I am aware of your use cases. Anybody who is interested can gain
a say in its future direction.

## What's with the name?

Teliva is the Tamil root for &lsquo;clear&rsquo;. Very much aspirational.

## Known issues

* Colors are currently hardcoded. You get a light background even if your
  terminal started out dark. To tweak colors, look for calls to
  `assume_default_colors()` and `init_pair()`, either in .tlv files for a
  specific app, or in the C sources for the standard code browser/editor.

* Backspace is known to not work in some configurations. As a workaround,
  typing `ctrl-h` tends to work in those situations.

* Keys outside the main keyboard area are mostly not supported. This includes
  the delete key when it's set away from the main keyboard area. (Macs call
  the backspace key &ldquo;delete&rdquo;; it should behave like backspace. As
  a consequence the menu sometimes mentions keys that don't work, just to
  encourage people to try options.)

## Mirrors and Forks

Updates to Teliva can be downloaded from the following mirrors:
* https://github.com/akkartik/teliva
* https://repo.or.cz/teliva.git
* https://codeberg.org/akkartik/teliva
* https://tildegit.org/akkartik/teliva
* https://git.tilde.institute/akkartik/teliva
* https://git.sr.ht/~akkartik/teliva
* https://pagure.io/teliva

Forks of Teliva are encouraged. If you show me your fork, I'll link to it
here.

## Feedback

[Most appreciated.](http://akkartik.name/contact)