Subject: Rules for files installed into bindir

From: Mikhael Goikhman <[email-masked]>
Date: Sat, 9 Nov 2002 05:35:40 +0000

To keep quality and consistency I follow these rules for our files
installed into bindir. I would like others to follow them too.

1) We have a special bin/ subdirectory for programs installed to bindir.

2) We don't install any program to bindir that does not have a man page.

3) We don't install any program to bindir without --help and --version.

4) The programs in the system's bindir should not have any extension.

   Extensions like .sh or .pl are good for files without +x permissions
   so that a user could know what interpretter to run on these files.
   Additional reasoning:
   My /usr/bin has 2002 files. From 280 sh/bash scripts only 11 are *.sh.

5) The programs should have the "fvwm-" prefix for consistency.

   Additional reasoning:
   My /usr/bin has 242 files in the dash form like "gnome-bug" and 
   and only 95 files in the underscore form like "pg_dump".

I think many projects follow these rules. They lead to a better user
experience.

Regards,
Mikhael.
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Dominik Vogt <[email-masked]>
Date: Sat, 9 Nov 2002 18:24:18 +0100

> 3) We don't install any program to bindir without --help and --version.

And "-h", "-?" and "-V" please.  In the long run I would like to
switch to GNU style long options.

> I think many projects follow these rules. They lead to a better user

Although I don't see rule 5 as mandatory, it is still better to
follow some rules than to let chaos reign.  One should also point
out that only programs should be installed into bindir that are
useful when they are exectued from a command line.  Programs that
do not fulfill this criterion belong into libexecdir.

This is what I think it should look like for the current programs:

                                  source dir   install dir
  ---------------------------------------------------------
  fvwm-bug                        bin          bindir
  fvwm-config                     bin          bindir
  fvwm-convert-2.2                bin          bindir
  fvwm-convert-2.4                bin          bindir
  fvwm-convert-2.6                bin          bindir
  fvwm-menu-desktop               bin          libexecdir
  fvwm-menu-directory             bin          libexecdir
  fvwm-menu-headlines             bin          libexecdir
  fvwm-menu-xlock                 bin          libexecdir
  fvwm-perllib                    bin          libexecdir
  fvwm-root                       bin          bindir
  build_dev.sh                    utils        -
  configure_dev.sh                utils        -
  fvwm_make_browse_menu.sh        examples     docdir
  fvwm_make_directory_menu.sh     examples     docdir
  make_fvwmdist.sh                utils        -
  quantize_pixmaps                bin          ?
  rebuild_dev.sh                  utils        -
  xselection                      bin          -

And while we are defining rules, I think every new script or
program should follow the GNU coding standards with respect to
handling and naming command line options, default options and the
output of the -V/--version option.  We can save a lot of trouble
by using getopt_long() (yes, I know it's not portable - we need
the getopt source file in the distribution).  I even have a nice
template for option parsing with getopt.

P.S.:  I have just removed all the "-blabla" options from
fvwm-root.  They were all introduced after 2.5.0 and can thus be
removed without notice before 2.6.

Bye

Dominik ^_^  ^_^

 --
Dominik Vogt, [email-masked]
Reply-To: [email-masked]
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Mikhael Goikhman <[email-masked]>
Date: Sat, 9 Nov 2002 20:33:51 +0000

> switch to GNU style long options.

I think -V is a historical casus and it should better be -v, but let it
be -V... But not -?, it is not even inputable in many shells, should be
escaped as -\?.

> This is what I think it should look like for the current programs:

I am not sure where did you get such crazy idea. :))

libexecdir is for loadable modules, it is specifically designed _not_ to
be in $PATH, because it is hardcoded into the main executable and used when
a module is loaded.

All of the scripts above are designed to be run from the command line and
to be in $PATH. Actually, fvwm-perllib _must_ be in $PATH otherwise no
user modules in perl, at least the ones that do not harcode anything, will
work (ok, they may use fvwm-config instead, but they don't). I am not
speaking about reading man pages like "fvwm-perllib man".

All of fvwm-menu-* scripts are a standard way in fvwm starting from 2.4.0
to achieve four different tasks, like providing the KDE/GNOME integration
support, building all kinds of directory and web headlines menus and
designed to work under PipeRead, so they should be in $PATH.

>   fvwm_make_directory_menu.sh     examples     docdir

I think it is a good opportunity to remove quantize_pixmaps and xselection
all together. In any case they should not be installed into bindir, so
should not be in bin/.

> removed without notice before 2.6.

Actually supporting the -version form would not harm. I saw many shell
scripts do it, for example our own autogenerated ./configure. Before you
removed it, most (if not all) our bindir programs supported both variants.
But this is not very important.

Regards,
Mikhael.

---

From: Dan Espen <[email-masked]>
Date: Sat, 09 Nov 2002 16:00:06 -0500

> be -V... But not -?, it is not even inputable in many shells, should be

I like to see a version/usage string on any unknown arg.

> > This is what I think it should look like for the current programs:

Don't forget FvwmCommand.

-- 
Dan Espen                           E-mail: [email-masked]

---

From: Dominik Vogt <[email-masked]>
Date: Sat, 9 Nov 2002 23:06:53 +0100

On Sat, Nov 09, 2002 at 08:33:51PM +0000, Mikhael Goikhman wrote:
> be -V...

As far as I know, -v is traditionally reserved for --verbose and
-V for --version.  I'll look that up.

> But not -?, it is not even inputable in many shells, should be
> escaped as -\?.

Well. personally I've never even thought of using -?, but it was
an old standard variant of -h that is preferredly used today.
Anyway, I agree with Dan that every unknow option should print the
usage message.

>From the GNU coding standards ;-)

> designed to work under PipeRead, so they should be in $PATH.

Yes, they are run from the command line, but it makes no sense to
run them outside fvwm context.  I guess one could fight lengthy
flame wars about the question if that qualifies them for bindir
or the "pure" path via fvwm-config/libexecdir should be taken.

Whatever, I'll shut up now, especially I really couldn't care less
what gets installed where.  My only concern here is not breaking
things that worked in the past.

> all together. In any case they should not be installed into bindir, so

No objections.

> But this is not very important.

No, it doesn't hurt, but on the other hand they *will* be removed
*everywhere* in 3.0.  So, if we don't add them now, we have one
tool less to worry about later.

Bye

Dominik ^_^  ^_^

---

From: Cameron Simpson <[email-masked]>
Date: Sun, 10 Nov 2002 12:45:07 +1100

On 20:33 09 Nov 2002, Mikhael Goikhman <[email-masked]> wrote:
| On 09 Nov 2002 18:24:18 +0100, Dominik Vogt wrote:
| > > 3) We don't install any program to bindir without --help and --version.
| > And "-h", "-?" and "-V" please.  In the long run I would like to
| > switch to GNU style long options.
| I think -V is a historical casus and it should better be -v, but let it
| be -V... But not -?, it is not even inputable in many shells, should be
| escaped as -\?.

I beg to differ here. Well, not entirely, but slightly.

My personal opinion is that a program should _always_ emit the usage
listing if it gets a bad option. The GNU behaviour of "bad option, tell
them to run with --help" enrages me. It is only sensible for programs
with very many options; most programs' usage listing will happily fit
on a single 24 lines screen.

With that preamble, in my shells I expect to be able to go

	foo -?

to most programs and get a usage message _because_ -? is not a valid
option. And I insist on my shells letting me type an unescaped -?,
and take care not to make stupidly named -* files.

So, what's I'm asking here is that:
	- whether you implement an actual -? option doesn't
	  bug me, provided that _any_ bad option elicits the
	  full usage string
	- if you do implement -?, I request that it definitely
	  emits a usage message

| > > 4) The programs in the system's bindir should not have any extension.
| > > 
| > >    Extensions like .sh or .pl are good for files without +x permissions
| > >    so that a user could know what interpretter to run on these files.
| > >    Additional reasoning:
| > >    My /usr/bin has 2002 files. From 280 sh/bash scripts only 11 are *.sh.

And extensions as _so_ tacky.

| > > 5) The programs should have the "fvwm-" prefix for consistency.
| > > 
| > >    Additional reasoning:
| > >    My /usr/bin has 242 files in the dash form like "gnome-bug" and 
| > >    and only 95 files in the underscore form like "pg_dump".

Besides, on most keyboards "-" doesn't need shift, and "_" does.
Easier to type.
-- 
Cameron Simpson, DoD#743        [email-masked]    http://www.zip.com.au/~cs/

Third, I propose prompt action on legislation extending and reforming the
state's asset seizure law. The current law, which is a valuable tool for law
enforcement in its fight against drug criminals, is set to expire on January
1st. This law provides over $30 million a year to law enforcement agencies,
and should be quickly renewed.	- Kathy Brown
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Mikhael Goikhman <[email-masked]>
Date: Sun, 10 Nov 2002 09:02:34 +0000

On 10 Nov 2002 12:45:07 +1100, Cameron Simpson wrote:
> | 

You know, zsh and tcsh by default give you an error on unescaped -?.

> 	  bug me, provided that _any_ bad option elicits the

It is good that you said GNU tells to print 2 lines only in this case,
so I don't need to add more than several paragraphs of reasonings. :)

I am against dumping the whole usage (that is usually more than 24 lines
since all my programs are very configurable) every time a user makes a
typo. A user wants to see that "option -X is not supported", he does not
need to go several screens up to determine whether this option means
"show usage" or it is unrecognized or maybe needs an additional argument.
The only correct way to handle a bad option is to print 2 lines:

  program: unrecognized option '-o'   (or: missing file argument after -o)
  Run --help to get the list of all recognized options.

A user knows what he does if he specified -o option, he wants the result
now. Or to see the diagnostic error line to know what he did wrong. He is
not interested in anything forced like copyright/license/--version/--help.
(In fact, IMHO the only place for copyrights is the man page and sources.)

And I would prefer these two lines to be dumped to stderr like gcc does it
and not stdout like gnome-terminal does it. Because stdout should contain
the result of the program's run designed to be parsable/piped, an error
option should not damage the expectations of the following piped program.
It is ok for me that --help is dumped to stdout like GNU says, because in
this case the usage screens are the output of the program, i.e. parsable.

> 	- if you do implement -?, I request that it definitely

I will add the -? alias to all my scripts for everyone to be happy. :)
It's a matter of adding 2 characters "|?" to a perl script or a module.

In any case, I would not blindly follow all GNU "standards", only the
reasonable ones. Even GNU projects do not follow all of them.

Regards,
Mikhael.

---

From: parv <[email-masked]>
Date: Sun, 10 Nov 2002 10:24:53 -0500

(sorry, i lost the OP.)

...
>    and only 95 files in the underscore form like "pg_dump".

i totally favour use of '-' instead of '_'.

  - parv

--

---

From: Dominik Vogt <[email-masked]>
Date: Sun, 10 Nov 2002 23:08:21 +0100

> > | On 09 Nov 2002 18:24:18 +0100, Dominik Vogt wrote:

[snip]

>   Run --help to get the list of all recognized options.

The proper solution - in my eyes - is to print the
"unknown option xyz" message *after* the usage message.  If the
verbose message is too long it should omit the lengthy
explanation.  And of course only the one letter options belong
into the usage line.  For example:

  $ foobar -z
  usage: foobar [-a] [-b] [-c] ... [-x] [-y]   <- one to two lines
  foobar: unknown option -z
  1 $ <-- return code 1

and

  $ foobar --help
  usage: foobar [-a] [-b] [-c] ... [-x] [-y]   <- many lines
    -a: explanation of option a
    -b: explanation of option b
    ...
    -x: explanation of option x
    -y: explanation of option y
  0 $ <-- return code 0

I think this is a good solution in between.  I have committed a
patch that cleans up the chaos in the fvwm executable and the man
page and uses this style.  Take a look and tell me what you think.
Try "fvwm -x" and "fvwm --help".

> reasonable ones. Even GNU projects do not follow all of them.

Neither would I.  But standardizing option names and usage
messages is one of the useful things.

Bye

Dominik ^_^  ^_^

---

From: Dominik Vogt <[email-masked]>
Date: Sun, 10 Nov 2002 21:30:03 +0100

[snip]
> And extensions as _so_ tacky.

Hey, careful!  One more work and I'll rename the executable to
fvwm.exe ;-)  Actually, I use extensions only to mark executables
that are just hacks and do not have production quality.

[snip]

Bye

Dominik ^_^  ^_^

---

From: Mikhael Goikhman <[email-masked]>
Date: Sun, 10 Nov 2002 23:27:38 +0000

>     -y: explanation of option y

If a short usage line helps, it may be added. But usually a usage line
with dozens of unrelated options (especially a one letter ones and without
description) only distracts an attention from the actual error message.
I am pretty happy with how programs in bin/ handle the situations.
(BTW, it always bugged me that "fvwm-bug --help" tried to send an email.)

> Try "fvwm -x" and "fvwm --help".

Hmm, I don't like too much short names. If it is a unix command that is
run often short names help, fvwm is not run often by hand. I would only
support long names except for the backward compatibility (-d, -f, -s).
You see we already ran out of letters, this is not really necessary.
Do you think a usage line like this helps to understand anything:

fvwm (2.5.5): usage: fvwm [-d display] [-D] [-f cfgfile] [-c cmd] [-s] [-V] [-h | -?] [-r] [-i client-id] [-F sm_file] [-I vis-id | -C vis-class] [-l colors [-L] [-A] [-S] [-N]]

See also 'xv -reuse', can you understand what was a problem? Hardly, but
at least it uses long descriptive option names. Long names are good.
But I just let you decide what should be the option list of fvwm itself.

Regards,
Mikhael.

---

From: Cameron Simpson <[email-masked]>
Date: Mon, 11 Nov 2002 11:08:52 +1100

On 21:30 10 Nov 2002, Dominik Vogt <[email-masked]> wrote:
| > And extensions as _so_ tacky.
| 
| Hey, careful!  One more work and I'll rename the executable to
| fvwm.exe ;-)  Actually, I use extensions only to mark executables
| that are just hacks and do not have production quality.

So do I. Cheers,

Nothing is so smiple that it can't get screwed up.

---

From: Cameron Simpson <[email-masked]>
Date: Mon, 11 Nov 2002 11:15:29 +1100

On 09:02 10 Nov 2002, Mikhael Goikhman <[email-masked]> wrote:
| > With that preamble, in my shells I expect to be able to go
| > 	foo -?
| > to most programs and get a usage message _because_ -? is not a valid
| > option. And I insist on my shells letting me type an unescaped -?,
| > and take care not to make stupidly named -* files.
| 
| You know, zsh and tcsh by default give you an error on unescaped -?.

I'm a zsh user myself, and turn that behaviour off. I consider it a sop to
[t]csh users (zsh has extensive "pretend to be csh" customisation options).

| > So, what's I'm asking here is that:
| > 	- whether you implement an actual -? option doesn't
| > 	  bug me, provided that _any_ bad option elicits the
| > 	  full usage string
| 
| It is good that you said GNU tells to print 2 lines only in this case,
| so I don't need to add more than several paragraphs of reasonings. :)
| I am against dumping the whole usage (that is usually more than 24 lines
| since all my programs are very configurable) every time a user makes a
| typo.

For long usage messages, I agree. For short (eg up to, say, 12 lines?) I'd
much rather get a usage message than have to invoke the program yet again.

[...]
| The only correct way to handle a bad option is to print 2 lines:
| 
|   program: unrecognized option '-o'   (or: missing file argument after -o)
|   Run --help to get the list of all recognized options.

For many-option commands, again I agree. But _please_, support '-h' in
addition to '--help'; --help is a pain to type for such a trivial task.

| A user knows what he does if he specified -o option, he wants the result
| now. Or to see the diagnostic error line to know what he did wrong. He is
| not interested in anything forced like copyright/license/--version/--help.

Speaking as a user: agree/agree/maybe/disagree. Unless the help is very long.

| (In fact, IMHO the only place for copyrights is the man page and sources.)

Yep.

| And I would prefer these two lines to be dumped to stderr like gcc does it
| and not stdout like gnome-terminal does it. Because stdout should contain
| the result of the program's run designed to be parsable/piped, an error
| option should not damage the expectations of the following piped program.

And also, not only does error->stdout bugger the pipeline, it swallows the
error message from the user's eyes!

| In any case, I would not blindly follow all GNU "standards", only the
| reasonable ones. Even GNU projects do not follow all of them.

Hear hear!

Cheers,

Pardon my driving, I'm trying to reload.

---

From: Dominik Vogt <[email-masked]>
Date: Mon, 11 Nov 2002 10:39:16 +0100

[snip]

> But I just let you decide what should be the option list of fvwm itself.

Actually, I had already written a line about xv as a bad example
but removed it :-)  That is why the short usage message lists only
the short options.  It allows you to check which option letters
are available - no more:

 - If you made a typo or forgot the exact option letter, you can
   quickly check which ones are available.
 - If the user has no idea what the options do (s)he needs more
   verbose output anyway and should use "--help".

Okay, I will commit a cleaned up version.  It cuts down the list
of short options that is printed to the ones that are interesting
when trying to get it run.  It should be readable enough and
usefull too.

Bye

Dominik ^_^  ^_^

---

From: Mikhael Goikhman <[email-masked]>
Date: Fri, 29 Nov 2002 15:16:36 +0000

> Don't forget FvwmCommand.

Yes, it should not be forgotten.

I think it should be replaced with a new command line utility fvwm-exec.
I would like to find a way to do it without FvwmCommandS similarly to how
fvwm-root tells fvwm it changed a root image. I may check whether it is
possible to communicate using X dirrectly and, if yes, will do it later.

fvwm-commands is a good name too since it will read multiple commands
either from a file (-f file) or stdin (unless -c "cmd" option is given).
Which name do you prefer: fvwm-commands, fvwm-command, fvwm-cmd,
fvwm-send, fvwm-exec? I prefer fvwm-exec or fvwm-commands.

Later we may add an fvwm command RemoteCommands on|off|restricted.
The default may be "restricted" that disables Exec, PipeRead and modules
with "/" in the path. But on the other hand it may be confusing that Read
is allowed and PipeRead is not, so other default would be ok for me too.

If the default is "on" then, in addition to removing FvwmCommand/,
FvwmConsole may be removed as well (it is just "xterm -name FvwmConsole
-e fvwm-exec").

Regards,
Mikhael.

---

From: Dominik Vogt <[email-masked]>
Date: Fri, 29 Nov 2002 16:24:05 +0100

> possible to communicate using X dirrectly and, if yes, will do it later.

Scripting by using roundtrips to the X server?  I don't think that
is a good idea.  On one hand it is far slower than even the
current module interface.  And on the other hand it creates a lot
of problems with permissions and opens even more security holes.

Bye

Dominik ^_^  ^_^

---

From: Dan Espen <[email-masked]>
Date: Fri, 29 Nov 2002 10:34:11 -0500

> of problems with permissions and opens even more security holes.

If Mozilla/Netscape is any example, I agree with Dominik, its horribly
slow.

I hate breaking  compatibilty, more than I  dislike inconsistency.   If
you change the name, please consider providing a link to the old name.

I agree that FvwmCommand is a security exposure.  Users should
only use it when they have their environment under control.  Its good
that it needs to be explicitly turned on.

---

From: Mikhael Goikhman <[email-masked]>
Date: Fri, 29 Nov 2002 16:14:06 +0000

> If Mozilla/Netscape is any example, I agree with Dominik, its horribly

The communication should not be done using X, only a notification of such
communication. I think it is better than sending a signal, because this
requires knowing a process number. After a notification the comminication
may be initialized just like now, using local pipes in /tmp or similar.
Then nothing will be changed regarding security.

> you change the name, please consider providing a link to the old name.

Yes, if any of FvwmCommand/FvwmCommandS/FvwmConsole are to be removed,
they will be replaced with wrappers in 2.6.x. I don't want to remove them
at this point. I want to try to implement fvwm-exec first and then think
whether something is redundant.

> that it needs to be explicitly turned on.

Ok, the default may be "off" until we define a better way.
A better way may be to have it "on" for the same local user.

Regards,
Mikhael.