remarks on the user guide

'wmii.pdf' was a useful read while preparing a custom wmiirc. Especially
useful were the property lists of 'ctl' files.
Since the whole control of wmii revolves around the filesystem, wouldn't it
be worth it to have a separate 'wmii Filesystem Reference' document?

I'm attaching a patch against 'wmii.tex'. Some remarks/questions follow.

1. Why do you use the following characters in 'code' environments:
    ' => ‘’
    " => “”
    # => ＃
   They cause an additional hurdle for users pasting to their scripts/terminal.

2. Does the 'Notice' event serve any other purpose beyond illustration?

3. I couldn't understand what the introductory paragraph of \section{Control
   Files} was trying to say.

4. Line 1060 says:
    Mod4-d) wmiir xwrite /tag/sel/ctl colmode sel -stack-max;;
   but '-stack' doesn't switch from stack to default mode. This isn't
   touched by the patch, because it looks like the line is supposed to work.

5. Regarding 'wmiir setsid', why isn't this command documented in the man
   page? When is it really needed?

6. In the patch, I've changed /sel/ regexp to /^sel$/, so that 'wimenu'
   shows tags like 'selinux'.

7. Is 'eval' here so that I can run commands like 'ls -l /tmp/lsl'? What is
   the purpose of 'exec', then?
    Mod4-p) eval exec wmiir setsid "$(proglist $PATH | wimenu)" &;;

8. There's an explanation for ‹Color Tuple›, but how does one specify fonts?
   A mention of 'xfontsel' and perhaps fontconfig's 'fc-list' could be
   useful. Btw., specifying xft fonts is no fun: 'font xft:Font Name-size'
   works, but how does one add Bold/Italic?

9. 'colrules' and 'tagrules' aren't mentioned anywhere in the document and
   I think that they would fit in under \section{The Root}.

10. A (beige-like?) color used in the 'code' environment is hard on the eyes
    (sample attached in 'code_colors.png').

The following is to abuse this bug report a little:
  11. Regarding 'colrules', I'm unable to find out what it does (without
      even trying to look at the source, that is).
  12. As for 'tagrules', would it make sense to have a client, matching
      a rule like '/name/ -> +tag', appear in the current view and the
      'tag' view?
  13. There is a 'border' setting for floating windows. Is there anything
      to control (turn off) the border of managed windows?

Original issue reported on code.google.com by rogu...@gmail.com on 7 Nov 2009 at 9:11

Attachments:

>'wmii.pdf' was a useful read while preparing a custom wmiirc.  
>Especially useful were the property lists of 'ctl' files.

I'm glad it was useful.

>Since the whole control of wmii revolves around the filesystem, 
>wouldn't it be worth it to have a separate 'wmii Filesystem 
>Reference' document?

Yes, and it exists, in the man page.

>1. Why do you use the following characters in 'code' environments:
>    ' => ‘’
>    " => “”
>    # => ＃
>   They cause an additional hurdle for users pasting to their 
>   scripts/terminal.

Well, the sharp sign is a hack so that ordinary hash symbols don't 
get colored as comments in the code secion. They're encoded as 
ordinary hashes in the PDF, so they shouldn't pose any problems. As 
for the quotes, it's partly for syntax highlighting, and partly 
because that part of the guide is based on Knuth's web which mangles 
quotes as such.

>2. Does the 'Notice' event serve any other purpose beyond 
>   illustration?

Yes, the standard wmii scripts all process notice events so 
arbitrary external processes can post notices to the bar. I use it 
for my volume control script, among other things. I also have an osd 
script that greps the event file for notices and posts them to the 
middle of the screen.

>3. I couldn't understand what the introductory paragraph of 
>   \section{Control Files} was trying to say.

You're right, it's confusing (in my defense, I wrote it at 4AM). 
I'll work on it.

>4. Line 1060 says:
>    Mod4-d) wmiir xwrite /tag/sel/ctl colmode sel -stack-max;;
>   but '-stack' doesn't switch from stack to default mode. This 
>   isn't touched by the patch, because it looks like the line is 
>   supposed to work.

You're right, it should work. That's a new feature in this release. 
I'm not quite sure why I chose 'default' rather than '-stack', but 
I'll fix it.

>5. Regarding 'wmiir setsid', why isn't this command documented in 
>   the man page? When is it really needed?

I'll document it. It's needed in shell scripts so when wmiirc is 
killed, the signal doesn't propagate to the apps it starts, and they 
don't die as well.

>7. Is 'eval' here so that I can run commands like 'ls -l /tmp/lsl'? 
>   What is the purpose of 'exec', then?
>    Mod4-p) eval exec wmiir setsid "$(proglist $PATH | wimenu)" &;;

Mainly for efficiency, so you don't have extra shells hanging around 
when you don't need them. Without the exec, long running processes 
all have another shell as their parent. Without the eval, pipes, 
variables, and such don't work.

>8. There's an explanation for ‹Color Tuple›, but how does one specify 
fonts?
>   A mention of 'xfontsel' and perhaps fontconfig's 'fc-list' could be
>   useful. Btw., specifying xft fonts is no fun: 'font xft:Font Name-size'
>   works, but how does one add Bold/Italic?

I'll work on that. If you want to specify font styles for xft, you 
do something like xft:Arial:bold or xft:Arial:italic, but that's a 
fontconfig feature so I didn't see the need to document it.

>9. 'colrules' and 'tagrules' aren't mentioned anywhere in the document and 
>   I think that they would fit in under \section{The Root}.

Probably. They're in the man page, though.

>10. A (beige-like?) color used in the 'code' environment is hard on 
>    the eyes (sample attached in 'code_colors.png').

Sorry, I'm colorblind, and I can read them fine on my screen, at 
least. I can darken them a bit, though.

>The following is to abuse this bug report a little:
>  11. Regarding 'colrules', I'm unable to find out what it does 
>       (without even trying to look at the source, that is).

See the man page.

>  12. As for 'tagrules', would it make sense to have a client, 
>      matching a rule like '/name/ -> +tag', appear in the current 
>      view and the 'tag' view?

It might, but you can already do that with sel+tag.

>  13. There is a 'border' setting for floating windows. Is there 
>      anything to control (turn off) the border of managed windows?

Nope, they're always 1px plus whatever padding is necessetated by 
increment hings.

Original comment by maglion...@gmail.com on 7 Nov 2009 at 10:44

jerluc / wmii

remarks on the user guide #155