Not sure what you mean here. They work in both the current stable and unstable releases of Fvwm.
– Thomas Adam
That shouldn’t be a problem if this setup is going to be distributed with future releases of FVWM. Anyone who got an old release gets the old config to go with it - shouldn’t be a problem.
The reason for the grad is that it’s easy on the eye, and not as expensive in memory as wallpaper. We want a little bit of eye candy, but we also want the default configuration to run on older machines without overhead. The third parameter is a bit more help for the fledgeling FVWMer. I’d welcome any ideas, given those parameters.
Interesting idea. The main danger with self documented things is that they tend to be a bit verbose, which sometimes leads to the documentation drowing out the code it is intended to document. Which isn’t too say it’s a bad idea; I’d certainly be interested to see what you had in mind.
Ok, thanks for clearing that out, I think I’ve got mixed with fvwm1x -series then.
Looking at the screenshot, I do have some thoughts:
the black text on so dark-blue is makes reading the black text hard. Also I’d guess removing the font shadow effect could improve readability.
I would like to make an short example of self-documented code I had in mind:
# Mouse and keyboard
# Keynames: {X11-include}/X11/keysymdef.h
# Contexts: [R(oot)|W(indow)|D(esktop)|T(itlebar)|S(ide)|F(rame)|I(con)|0-9(buttons)| A(ny)|M(enutearoff)]
# Modifiers: [N(o)|C(ontrol)|S(hift)|M(eta)|L(caps-lock)|A(ny)|1-5(x11 modifiers)]
# Keyname Context Modifier(s) Function
key return A M maximizeColour is always going to be an issue, but I do agree that the colours could change – perhaps having a lighter blue background.
The majority of people aren’t going to care in which header file the keysym definitions are – and those that do will almost certainly know where to look. I like the idea of self-documenting, but try and make it a little less technical.
– Thomas Adam
I’d quite like to keep the shadow in some form. Maybe we could set the font shadow to white. That would help the visibility aspect.
I like the column headers!
In general, I think I prefer hand written comments. I like to tell the reader in fairly informal language what the code is going to do - with the emphasis on what it is going to acheive rather than paraphrasing the code. That way they can see what the point of the code is.
[code]
The next section contains keybindings. This is where we tell FVWM to
perform certain actions when particular keys are pressed
See “man fvwm” for details
Key Context Modifier Command
key return A M Maximize # Max out the window if return key is pressed anywhere[/code]
Admittedly, everyone has their own style.
Have you considered setting that auto documenting stuff to churn out some quick reference cards? I think that format could be tremendously valuable for something like that.
I am sorry, I think I have been a bit too unclear when I talked about self-documented code.
It is something I’ve seen in many other window magagers, in this case I think one shouldn’t mix up the comments of a window manager configuration ‘code’, and, say, C -source code. They both serve different purposes. Whereas C -source code comments serve as a purpose of explaining what is happening inside a code, the window manager configuration codes comments traditionally serve the purpose of explaining how to configure the behavior of window manager (ie, not explaining what the actual code does). Please, correct me if it does not make sense.
So the idea is to show the options (maybe not all? ATM I’m putting together the 'Style '- options … long list 
) which you can use, in comments.
Even though the xkeysyms might seem technical, it straight off shows the reader where to look for additional information or pointers to know what to use for names in keybindings. Yes? It is on one line, and I have to admit, I didn’t know where to look until ‘man fvwm’ 
Oh, almost forgot the other important thing that was on my mind when talking about “default fvwm config”.
The colours. I have to say it is very difficult to find colours which would be easy on the eye, yet have some ‘colour’ in them (ie, not grey).
What I came up with, were cornsilk2 and paleturqoise3. Not sure about the latter one though, it does get sore on eyes on larger areas (ie, long titlebar).
Any thoughts about this?
Whoops - thought I posted this on Saturday!
The thing with C is that you get dense code lacking in narrative elements. If you want to be able to read C programs without mentally parsing each statement, you need the comments. I’ve coded C professionally since 1984, and I know that if I don’t comment a block of code, even now, I can come back to it after six months and have to figure it out all over again. And that’s with the coding style with which I am most comfortable.
I’m not sure where the window manager tradition comes from. Maybe one or more of them were short of documentation, so the default configs were intended to serve as interim docs until the proper ones were written, with the style being propagated down through subsequent releases. I can’t see a functional advantage to turning the config into the documentation to this extent, given that proper docs di exist for FVWM.
On the other hand, FVWM does seem to share C’s high obfuscatuion factor, and having an informal english statement of intent seems useful. For one thing, it is information that cannot be gleaned from the manuals, which is in fact, available nowhere else. On the other hand the documentation is available in the documentation. The odd aide memoire is useful, but too much and the documentation becoes noise that drowns the signal of the config.
It sounds like a fabulous resource. I’m still thinking “flashcards” and “quick reference chart” rather than “comments in config files” though.
Relevant information that isn’t readily retrievable from the manual page is useful and has a place in comments everywhere. But I still hold that the most important things are first:that the user should know what the code is intended to achieve; and second: that the structure of the code itself can be discerned through the interruptions of the comments.
Well as Thomas points out, people are always going to argue over colours. The ultimate descision for any new color scheme (or any other element) is going to be the fvwm-workers, so maybe it would be well to give them a selection. Thomas: Is it much of a pain to factor out the colours so they can be easily changed?
Incidentally the closest I could get was
Colorset 1 BGradient 256 cornsilk2 PaleTurquoise, fg black
Colorset 2 bg DarkSlateBlueWhich gives us
(Or would you run the grad the other way?) I still think I prefer this.
No, not really – but I will obviously have to use something as a default.
– Thomas Adam
But then this comes back to what you and I originally spoke of, Nick. Although I’m a programmer, and can quite easily follow code as comments – for the average user that cannot understand C, or doesn’t care, isn’t going to want to know about whether it is a struct or enum that holds window information; nor are they going to care in which header file a particular key definition is stored. It just becomes irrelevant information, and added obfuscation to configuring Fvwm.
The majority of users are just going to want to know how to configure the window manager. Those that care about lowlevel internals will often have the inclincation, and understanding of knowing where to look in the first place.
– Thomas Adam
Fair enough, then. Getting a modernised default config for FVWM is the objective here - It doesn’t matter who designs what so long as we meet the design criteria. One set of colours is as good as another in that respect.
Similarly for comments: I had a play with torsmo today. That uses a heavily documented default config, and I found that helpful for getting started quickly.
‘Default fvwm config’ would seem crucial enough to leave me wondering why not more of people have participated in this conversation.
Anyways, I would like to thank you Nick for ideas and inspiration for my own ‘default configuration’ participant (screenshots and configs -> morbusg stuff -> X)
I still don’t agree with the comments documentation with Thomas, but what the heck, I can always make my own config
-Mikko
Well, one shouldn’t participate in a conversation if one hasn’t got anything to say that could contribute to the conversation…
So I don’t have any comments about the config itself, however I don’t really understand the comments issue, is Nick objecting to comments about the source or closely relating to the source spread throughout a configuration? Or is the argument that coders should be able to read code without comments (sound quite preposturous to me…)…or something else?
It might just be me 
. I like the idea of self-documenting, but what I have a hard time believing is that the average person [1] using Fvwm isn’t going to want to know where/what/how/why, for example, the keysyms are in which header, or whether a struct or enum governs an internal windowing structure.
If something is to be documenting – it should be meaningful and descriptive. Fvwm isn’t “easy” in that sense – so IMO, efforts are better spent in explaining via comments (with example) which part of the configuration file does what, and how. Telling a window, for instance which colorset to use is of no use to the person configuring it, which source file it is contained in.
If you start adding what I see as extraneous information (such as header file definitons and the like) then the assumption that I’d make as a novice at Fvwm (remember this is why we’re doing this – to help those new to Fvwm, or who wish to understand it better) is that it’s too complex – not to mention the fact it detracts from the point of helpful comments.
However, if one is curious or cares enough about which header file or source file contains XYZ, then in almost all cases that person is going to know where to look, and more importantly what it does.
– Thomas Adam
[1] A slight sweeping generalisation, but we are trying to target novices to Fvwm. That’s not to say these novices aren’t coders, but that doesn’t (nor should it) neccessitate the inclusion of header-file information, IMO.
That kind of comments indeed doesn’t belong in a configuration file, it might belong in some other kind of documentation, but in that case I’d rather have them document the Fvwm source in a decent fashion, alright I might be a novice when we’re talking about C but the Fvwm code (or at least the part I looked at: the FvwmButtons stuff) is very badly, if at all, documented and I couldn’t get heads nor tails on it…but that wasn’t the point of course 
Not to sound rude, but… Thomas, I don’t even know what struc or enum means. How does one know what to use for keynames?
I’m no coder. I’m a themer. So my comments are stricktly from that perspective (+ a newbie perspective). I think the average person would rather know how to configure his window manager, than:
# the following makes resizing windows opaque
Style * ResizeOpaque
# the following makes window stay on top of other windows
Style "xterm" StaysOnTopFvwm ‘code’ is quite verbose, and commenting what it does seemed like a waste of time to me.
One uses the output (traditionally) from ‘xev’ – this is indeed what is mentioned in the FAQ and the man page. Further to that is the whole xmodmap situation which is (for the most part) outside the scope of Fvwm, save for the mention of clearing modifier statuses on modifier keys.
Then I’m glad you agree.
– Thomas Adam
As I see it there are four general categories of comments. I’ll call them Pointeless, Echo, Documentary and Expository.
Pointless comments are where the commentator uses the comment to wisecrack, mock, mislead or generally waste the time of the reader. These can sometimes be useful in maintaining reader attention, but generally they add no new data to the program.
FvwmButtons: Colorset 12 # RTFM n00b!Echo Comments are where the comment echoes back the program text without adding new information
FvwmButtons: Colorset 12 # use colorset 12Documentary comments explain the alternatives for the section of code that they comment upon
FvwmButtons: Colorset 12 # defined colorset range 1-20 Expository comments explain what they author is trying to achieve in the code
FvwmButtons: Colorset 12 # colour buttons with purple shading to blackThe examples are a little simplistic, but the get the idea across.
The debate here seems to be whether to use expository or documentary comments. I favour expository comments; morbusg documentary; I think I may have misunderstood Thomas’s position, so I’ll not try and categorise him.
None of the comment categories are exclude any of the others, so some level of compromise is easily achived. We could have exposition followed by documentation, although I still question the value of documentaty comments in an ultra minimal designed to be replaced configuration file. There is also the danger of drowing the code in comments. Dragon, think of /etc/make.conf in gentoo and why they moved the comments to make.conf.example. They can get in the way.
Anyway - that’s my take on the comments issue and on where people stand. Corrections and/or other models are welcome
One last point: The comments in the config file I proposed are for the benefit of forum members who might wish to ahem comment upon my design considerations. It was not intended as a final conifg, although I’ll admit I’d forgotten that until just now. I’ll see if I write a version commented the way I would like a FVWM newbie to see it. Hopefully sometime tomorrow.
[edit] give morbusg’s handle its proper spelling
If you’d like to include options in it, feel free to rip them off from my config (it was a tedious job gathering them, no need to do twice.)
Here we go. This is how I would do the comments. There’s a mix of documentation and exposition here, but I’ve made an effort to favour exposition and to keep the tone lightweight and unintimidating
[code]#
Welcome to FVWM.
This is the default configuration file for FVWM. This is the file to edit
if you want to change how FVWM works. As config files go this one is,
by design ultra-minimal. We hope you’ll replace it with something more
imaginative.
For some ideas on how to do that, the “Getting Started” menu option gives
some useful resources. Recommended are:
the fvwm man page (man fvwm)
the fvwm modules manuals (man -k Fvwm)
the fvwm home page (http://fvwm.org)
the fvwm forum (http://fvwm.lair.be)
the fvwm wiki (http://www.fvwmwiki.org)
Meanwhile, we’ll try and make this file as helpful as possible. We’ll start
by defining some constants.
The SetEnv command sets variables that can be accessed later in the
configuration script. The variables are inserted into the environment, and
can be accessed by processes initiated by fvwm
Environment variables can be accessed using the $[variable-name] syntax
eg. $[HOME] below
SetEnv resource_dir $[HOME]/.fvwm/New_Default
SetEnv helpfile $[resource_dir]/helpfile
SetEnv banner $[resource_dir]/fvwm-welcome.png
FVWM keeps uses colorsets to co-ordinate colours on the desktop. This defines
two colorsets: A blue shading to gray diagonal gradient that we’ll use for
the desktop and the menu, and a darker blue for the window with the focus
Colorset 1 BGradient 256 blue gray, fg black
Colorset 2 bg DarkSlateBlue
Styles are display options that affect groups of windows. The format is
Style pattern option [, option … ]
where pattern matches either the window title or the x-resource or class name
If that sounds complicated, just think “window title”.
For the possible options, see the fvwm man page. There are many.
Here we set the colorset for window titlebars and borders and then
we set the same for the window with the focus
style * Colorset 1 # non-focus
style * HilightColorset 2 # focus
this sets the font used by titles and menus (and most other things)
we’re using Arial Black. “Shadow=3 sw” means a three point font shadow
below and to the left of the text
DefaultFont “Shadow=3 sw:xft:ArialBlack”
Menus have thier own style command. this sets the menus to use the same
colour gradient as used by the desktop
MenuStyle * menucolorset 1
Fvwm farms out some large chunks of functionality to modules that can
be included or not as it suits the user. Module configuration is done as
part of the FVWM config file, usually begining with
DestroyModuleConfig ModuleName: *
and then a number of lines like this:
*ModuleName: Option Value
One such module is FvwmBacker. FvwmBacker manages transitions
between desks and pages for FVWM’s virtual desktops. In this case,
we only have a single desktop, so all we’re using FvwmBacker for is to
set the background. This requires minimal configuration.
man FvwmBacker for further details
man fvwm for more about modules and/or virtual desktops
DestroyModuleConfig FvwmBacker: * # erases previous settings
*FvwmBacker: Command Colorset 1 # sets backdrop to the blue-gray grad
Another module, FvwmBanner popus up a startup banner. This displays the
FVWM logo with the “click ANYWHERE for a menu” message.
DestroyModuleConfig FvwmBanner: *
*FvwmBanner: NoDecor # means no titlebar, icons, borders…
*FvwmBanner: Pixmap $[banner] # display the image defined earlier
*FvwmBanner: Timeout 6 # and do so for six seconds
FVWM supports functions. This is a simple one whoch launches an
xterm scrolling a helpfile. We’ll use it in the menu section later in the file
DestroyFunc FuncGettingStarted
AddToFunc FuncGettingStarted
- I Exec exec xterm -T “Getting Started” -bg navy -fg white -e less $[helpfile]
StartFunction is a special function. It’s user definable
and gets called when FVWM starts up. It’s a good place to start any modules,
gkrellms, desklets, torsmos or whatever apps and/or modules should be running
at startup.
We just have the two modules we just configured:
DestroyFunc StartFunction
AddToFunc StartFunction
- I Module FvwmBacker
- I Module FvwmBanner
This defines the menu you get when you click on the background.
each of the “+” lines is a menu item of the form:
‘&menu-text’ Command To Execute If Clicked
The char following any ‘&’ char will be underlined and used as a hotkey
for that choice.
DestroyMenu MenuFvwmRoot
AddToMenu MenuFvwmRoot ‘Builtin Menu’ Title
- ‘&1. Xterm’ Exec exec xterm -bg navy -fg white
- ‘&2. Getting Started’ FuncGettingStarted
- ‘&3. Setup Form’ Module FvwmForm FvwmForm-Setup
- ‘&4. Execute FVWM Commands’ Module FvwmConsole
- ‘&R. Restart’ Restart
- ‘&Q. Quit’ Quit
and this reads a file with some stuff to let you hot-swap configs on Windows+C
… but we aint decided that’s going in yet, so pretend I dint say nothin’.
read menu_config
[/code]
[edited to include FvwmWiki and some minor restructuring ]