Troubleshooters.Com®, Linux Library and Steve's ctwm Secret Stash Present:
Overview of ctwm
Copyright © 2017 by Steve Litt
See the Troubleshooters.Com Bookstore.
Contents:
Ctwm is one of the most configurable lightweight window managers around. On a scale of lousy to great, I'd rate ctwm as spectacular. I'm thinking seriously about replacing my beloved Openbox with ctwm.
By editing ~/.ctwmrc, you can make it into almost any kind of interface you want. Although the available .ctwmrc files around the Internet seem to imply that most folks use ctwm in a mouse-centric manner, one of the sub-documents of Steve's ctwm Secret Stash show how to turn ctwm into a lightning speed, keyboard-respecting productivity machine.
It's very hard to find people to discuss ctwm with, hence the name "Steve's ctwm Secret Stash". Even the project's own mailing list can take days to answer a question. If your distro has a ctwm package, it's likely to be old, incomplete, and only partially working. It's very tough to find living, breathing ctwm users to share info with. Ctwm is wonderful, but you need some self-sufficiency to use it. I have such a high opinion of ctwm that I'm willing to spend the extra time finding its secrets, and as I find them, I might as well pass them on to you.
This documentation is incomplete: It just scratches the surface. This is partially because there's almost no decent ctwm documentation around, and very few people willing and able to speak to you about ctwm. With "Steve's ctwm Secret Stash" I'm trying to improve the situation.
Ctwm docs are hard to find, and people knowledgeable about ctwm are few and far between. Therefore, a lot of ctwm learning is based on:
Ugh! ctwm-4.0.1/doc/devman/README.md states that you must have Asciidoctor to compile their .adoc files into HTML, or, in he case of the man page, a man page. My Void Linux distro has no Asciidoctor. My Devuan VM does have Asciidoctor, but this whole thing invites the question: Should a prospective user be made to jump through hoops like this in order to use the software? I suggest the project pre-compile their .adoc files into .html files so a casual tire-kicker can see the docs as they were meant to be seen. Most true believers started as tire kickers.
So what you probably will do is read the .adoc files in a text editor. This is probably a little easier in AsciiDoctor than it is in most files containing markup tags.
ctwm-4.0.1
doc
manual
ctwm.1.adoc #The man page, vital info
devman
README.md #discusses role of AsciiDoctor
principles.adoc #Architectural details too low level for most needs
functions.adoc #Informative if you get past the ambiguities
code_style.adoc #A must before reading the source code
Of all the preceding files, the man page (ctwm.1.adoc is by far the most useful to someone adapting ctwm to their needs. You might be able to find an HTML version on the net, but be sure it's for 4.0.1 (or whatever the latest is when you're reading this). Or, if you have AsciiDoctor installed, use the instructions in README.md.
Other peoples' ~/.ctwmrc files is a powerful springboard to ctwm mastery. Most such files scattered across the web show a screenshot of the result. Better yet, as you compare and contrast various /.ctwmrc files, you get a feeling for which configs accomplish which needs. Those revelations on your part can then be confirmed and enhanced by looking at the ctwm man page. Simply perform a web search for the string ctwmrc to find what you need.
Most free software documentation is ambiguous, and experimentation is your weapon against ambiguity. Make a single small change, record the change in program behavior. Keep repeating till problem solved.
Danger!
Source code experimentation works only if you run the just compiled copy of ctwm. For instance, if you have both a /usr/bin/ctwm and a ~/compiles/ctwm-4.0.1/build/ctwm, experimentation will work only if you run the latter copy.
If it seems that nothing you do in ctwm source changes behavior, check to make sure you're using the correct ctwm. Make a shellscript that deletes that copy before recompiling it. And make an ultra-simple, obvious change like the text on a menu item, in order to see that your compilation is indeed having an effect.
When you've looked at all the docs, compared and contrasted all the ~/.ctwmrc files you could find, experimented heartily with various ~/.ctwmrc files of your own, and you still have questions, that's the time to bust into the source code and take a look. Like most source code, it's not easy, but it's doable. I found a workaround for ctwm's unexpected menu Enter key behavior there.
The person who closes ctwm, re-logs in, then re-opens all necessary windows just to view the result of a config file change, will soon give up in frustration. Ctwm has a function, called f.restart, that rereads ~/.ctwmrc and restarts according to that file's configuration. It leaves all windows up, and neither terminates your X session nor makes you log in again. It's a huge timesaver: A necessary timesaver.
Most ctwm setups have this setup available from the menu: Click the main menu's Exit choice, slide right, then click "No, restart ctwm." If your menu doesn't have an obvious way to restart ctwm, then you can create a keyboard hotkey as follows:
"F9" = m | c | s : all : f.restart
Put the preceding hotkey def with the other hotkey defs in ~/.ctwmrc, or if there are none, put it right below the mouse button command definitions.
You probably noticed that this hotkey involves Alt, Shift and Ctrl. That's because you don't want this hotkey to be easy to hit. It's for emergencies only, when your menu can't restart ctwm.
As long as you're at it, you might as well add a hotkey to terminate ctwm. Here it is, mapped to Ctrl+Shift+Alt+F8:
"F8" = m | c | s : all : f.quit
Put it right below the hotkey that restarts ctwm, and as mentioned before, use it only for emergencies: Quitting your graphical user interface deserves the time and attention of a mouse process.
Ctwm is very simple software. It has no way to know what software you've installed via your package manager. Package managers don't update the
~/.ctwmrcmenu system with new programs that get installed. It's pretty certain that unless you stick to a very small subset of programs, your ctwm menus won't be up to date without your personally adjusting them. Troubleshooting, configuration and experimentation are very bad times to stop your forward progress to adjust your menus.
Once you have ctwm installed and able to restart itself at will, it's an excellent move to install dmenu, adjust it to the needs of a program chooser, and integrate it via hotkey with ctwm. The way to do all of this is discussed in the Incorporating dmenu into ctwm document. Even if you're normally a mouse-only type of person, take it from me: This one hotkey will make your life much happier when troubleshooting, configuring, and experimenting with ctwm.
By the way, if you're running ctwm in a window (ctwm -w, the underlying WMDE gets first crack at any keystrokes, so be sure you have a dmenu hotkey that's different from the one in your host WMDE. You can make another ctwm hotkey that's the same as the one on your host (if you have a dmenu hotkey on your host WMDE), so that once you switch to ctwm, you can use your accustomed keystrokes. If you're not running ctwm in a window, this entire paragraph is moot.
The ideal situation for ctwm experimentation is if your computer's WMDE is already ctwm. But until your ctwm setup is armed with a workflow like you're used to, running in ctwm will slow you down. So you can run ctwm in a virtual machine (VM). I use qemu for that. As long as you press the keystroke to isolate the mouse and the keyboard from the host OS, the guest vm running ctwm gets all the keystrokes first-hand, which of course is the best way to test. The downside of using a VM is it's not trivial to set up, it detracts from the performance of the host computer, and it's difficult to copy and paste from the VM to the host computer. Nevertheless, running ctwm in an OS on a VM is a great option. Configuration of virtual machines is beyond the scope of Steve's ctwm Secret Stash, but many fine documents reside on the net, including http://www.troubleshooters.com/linux/diy/qemu.htm.
The ideal situation for ctwm experimentation is if your computer's WMDE is already ctwm. But until your ctwm setup is armed with a workflow like you're used to, running in ctwm will slow you down. The subsection before this one discusses the option of running ctwm in a virtual machine, but if that doesn't work for you, ctwm has a feature enabling you to run it in a window instead of as the basic GUI of X. All you need to do is the following simple command:
ctwm -w
Or, if you didn't do a complete ctwm install, the following command should do it:
/path/to/ctwm-4.0.1/ctwm -w
Almost every WMDE you'll meet enables you to perform all WMDE tasks with the mouse. Most WMDEs have some hotkeys enabling you to perform some WMDE tasks with the keyboard. Some WMDEs enable you to perform every WMDE task via the keyboard. In every case, the WMDE must be configured to take advantage of these options. Ctwm can be configured to do it all, or any subset you want.
Some people like using the mouse all the time. Perhaps they're bad typists, or perhaps they don't want to remember a bunch of keystrokes. Some people like using the keyboard all the time. They've sacrificed some quick discoverability for the ability to keep their fingers at touch-typist home-position all the time, and work much faster. It's a little like the people who like Vim vs the people who like gEdit or Leafpad.
Ctwm has a special facility called "Icons", which entails minimizing a window to a little icon representing it. Users of Unity and WindowMaker will immediately understand the concept. The trouble is, these icons don't appear in any protected place, or any special place at all. You click the Iconize button (leftmost button), and the window is replaced by a little icon, which rides on top of all the windows until a focused window covers it, at which it's lost unless you hunt around or use the IconManager. I guess you move it around so it doesn't get in the way or get lost, but these icons still manage to get in the way or get lost. You single click an icon to restore its window.
I use icons in exactly one situation: I store an always-on-top workspace thingy to an always-on-top icon that I store in the lower left, mostly off the screen, until I need it, at which time I windowize it, use it, and then iconize it again.
Until somebody convinces me icons are an asset, and shows me a way to use them productively, I consider them much more trouble than they're worth, and don't discuss them anywhere in Steve's ctwm Secret Stash except for storing the workspace thingy. My advice is if you accidentally iconize a window, right away click the icon to turn it back into a window.
[ Training | Troubleshooters.Com | Email Steve Litt ]