On Sat, Oct 07, 2017 at 10:13:35PM -0400 I heard the voice of
Steve Litt, and lo! it spake thus:
>
> I mentioned I was writing documentation about ctwm for
> Troubleshooters.Com. I finished the docs, and they're at
> http://troubleshooters.com/linux/ctwm
Some notes in going through:
- overview.htm
- "ctwm docs distributed with ctwm". The doc/devman/ bits are the
_developer's_ manual, so a prospective user shouldn't even be
looking at them. That's why they're not even hooked into the main
build at all, and no great effort has been made to make them Just
Work in arbitrary environments; people doing dev are presumed
already willing to do a little tweaking if necessary(*) :). I
don't see any reason to even mention the dev manual in the sort of
docs you're writing here.
(*) Note that asciidoctor is often dist'd as a Ruby Gem; in a
look through the Void package list I don't see [m]any gems
obviously listed, so maybe it's more common in that world to
just use gem's native packaging to install them?
The doc/manual/ bits are the user's manual, in pretty much manpage
style. It's still (for the moment) explicitly intended to remain
compatible with the defunct python asciidoc implementation, but
any built tarballs (like releases) will already include the
processed man/HTML outputs of it anyway. And the HTML version of
it from the latest release(*) is kept up on the website as well.
(*) Actually, I've left the 4.0.0 manual up, since the 4.0.1 has
no changes at in either the manual or anything in describes,
so I skipped the churn.
- "Restarting ctwm". If you're talking about emergency restarting,
might want to mention SIGHUP. Dup to modernize.htm talking about
restarting.
- "Running ctwm in a Virtual Machine" and "Running a dedicated ctwm
window". I'd give strong mention to using xnest or xephyr here;
xephyr even gives you mouse/keyboard capturing like a VM so you
can bypass bindings in your outside WM. At least xnest does have
some occasional slightly odd behavior due to what it is, but none
of it gets in the way of testing configs. And it's a lot lower
overhead (both in terms of system resources, and user mental ones)
than using a VM.
The nested/window-mode ctwm with -w is still high up on my mental
chopping block; it's a really weird thing that doesn't actually
work all that well in a lot of ways, has fingers mucking up a lot
of different parts of the code, and has been involved in some
weird bugs in the past even when you're not using it. I would
definitely recommend not even mentioning its existence; xnest is
better in every practical and most impractical ways.
(dup comments to part of modernize.htm talking about a VM)
- "About Icons". I'd probably move this into a place talking about
the icon manager. In ctwm (and twm before it, for that matter)
I've always just used the icon manager and IconifyByUnmapping, so
icons never show up at all. Other people do differ.
- install.htm
- "Download either ctwm-4.0.1.tar.xz or ctwm-4.0.1.tar.xz." You
probably wanted one of those to be .gz. I'd consider skipping
talking about .gz depending on your audience, since it's just
there for what are now pretty old systems that lack xz.
- "Testing ctwm" (and the cp'ing of system.ctwmrc earlier); trust
me, nobody running ctwm uses or thinks too highly of the
system.ctwmrc :). Note that it's also baked into the binary, so
if you don't have a .ctwmrc (or .twmrc, as a fallback), it'll get
used anyway, so you may not have to bother cp'ing it around.
- modernize.htm
- (various comments handled in talking about config)
- f.fullscreenzoom mentions using F11 to "come back", but that isn't
something ctwm would do unless you added a key binding for it
(which I don't see in your config). Some _programs_ (like
Firefox) use F11 to toggle their own full-screen mode, which ctwm
implements (via an EWMH message) as f.fullscreenzoom, so it
happens to work for them, but it won't in general. x-ref config
stuff below.
- "Accommodating Workspaces"
- "There are two ways to navigate workspaces: Brute force menus,
and the super-magic workspace thingy, which looks like 8
chicklets in 2 rows of 4 columns each. This section uses a
little of each."
Actually, there's at least one more; keybindings, which you then
talk about and have in your sample config, and are probably
widely used anyway.
Also, the size and layout of the WSM is pretty depending on how
you config it; e.g., mine (when it's shown, which is extremely
rarely) is currently a 3x3 grid, and in your sample config,
you've got it 8-wide in 1 row.
- For me, I'd skip dealing with icons for the WSM as well, and
leave it with no title; just have key bindings for
f.toggleworkspacemgr to pop it up/down when needed. I use
Alt-F12 for that (and have the ridiculous "Print Screen" button,
which is right beside F12 on my keyboard, remapped to an extra
alt key as well, which makes it thoroughly convenient. And to
hit the Alt-F11 mapping for pulling up the Occupy window when I
want to adjust things around. I'll bet some keystroke handling
in that window would be in order, for popping it down if nothing
else...).
- menu_behavior.htm
- The "Slide left" behavior for the mouse is wrong. Sliding left by
itself never does anything, no matter what entry you're on.
Sliding _out_ of the current menu and _into_ the parent menu
collapses away the current, but of course you can do that by going
up as well as left.
- "How can you tell? It's simple: The selected entry has a little
left-arrow superimposed on top of it." It's also reverse
video'd.
- patch.htm
- vim-style menu navigation is an interesting idea. I'll bet there
are ways that could be cleanly(*) made an option.
(*) Well, not significantly less clean than anything else around
that part of the codebase, anyway...
- Re: the patch, I'd generally suggest something more like
- if(!strcmp(keynam, "Return")) {
+ if(0 && !strcmp(keynam, "Return")) {
instead of messing with the string being compared; it's more
explicit about the intention to the reader, as well as making it
completely removable by the compiler. Or using the preprocessor
to remove it, but that takes TWO lines instead of one, so it's
obviously only half as good.
- stevelitt_ctwmrc.htm (and -1.0.ctwmrc)
- I've academic interest in how MaxWindowSize is helping you. I had
it in my config for years, but I eventually took it out, because I
pretty much never saw it helping anything, and even once in a
great while (~yearly, if perhaps less) it got in my way.
- BorderWidth and ThreeDBorderWidth. If you're
UseThreeDBorders'ing, BorderWidth is meaningless.
- The various bits you have "Help kbd instantiated windows get
focus" commented probably need a little more precise explanation.
UsePPosition especially doesn't have anything to do with focus,
but with positioning, and ditto RandomPlacement. Possibly you
mean how that just plop the window somewhere rather than waiting
for the user to position? Of course, if you have RandomPlacement
on, UsePPosition wouldn't be needed for that anyway, and
RandomPlacement "on" is the default in 4.0.0+ as well.
Now, I don't see any obvious reason it would be difficult or
ambiguous to add an AutoFocusToNewWindows or the like... there
are certainly the various (IMO unpleasant) side effects, but
that's not the WM's fault.
- You may want to rethink whether to set NoDefaults; as long as
you're making some adjustments to the icons on the titlebar
anyway, you may want to just take over from scratch. That's pure
personal style though.
- (x-ref earlier discussion of WorkSpaceManager and icons vs.
f.toggle keybindings)
- (x-ref earlier about f.fullscreenzoom and F11) I note that you do
have Button8 bound to it, so you could reverse out of it that way;
may want to update earlier discussion or config so they match.
But I see you've also got the same button in titlebar context
bound to f.delete; that sounds like a dangerous mix for
user-training reasons.
- You've got a f.movetitlebar binding, but without SqueezeTitle set
that won't do anything. May be worth leaving in as an example,
but probably deserves a comment to that effect.
- On the menus:
- There's probably no reason you need xcalc/xman/xmag on there :)
- menu "workspace-special" looks like a fossil from
experimentation; probably not needed in a dist'd config.
- I'd definitely lose the f.adoptwindow binding, along with the
other nested stuff above. f.start/stop animation aren't really
window specific (you may want to access them from that menu for
convenience reasons, but they're WM-wide toggles, and I've never
used 'em myself). Similarly f.refresh; if you're really wanting
single-window refresh I'd just use f.winrefresh.
--
Matthew Fuller (MF4839) | [email protected]
Systems/Network Administrator | http://www.over-yonder.net/~fullermd/
On the Internet, nobody can hear you scream.
