Re: [Dragora-members] Qi 2.0rc14

[Matias Fonzo]

El 2020-07-24 20:21, Michael Siegel escribió:
> Am 24.07.20 um 23:29 schrieb Matias Fonzo:
> > El 2020-07-24 17:42, Michael Siegel escribió:
> > > Am 24.07.20 um 20:51 schrieb Matias Fonzo:
> > > > Attached is Qi 2.0rc14, which removes the replacement for 
> > > > basename(1)
> > > > and dirname(1)...
> > >
> > > Thanks!
> > >
> > > > Better to keep it simple, right?.  ;-)
> > >
> > > That's what I thought. :)
> > >
> > > Okay, next thing: I would suggest using a "here-document"[1] to
> > > implement the `usage()' function. This will make the code much more
> > > readable.
> >
> > What's wrong with printf?
>
> I think there are several things wrong with that:
>
> It requires 138 double quote characters, 76 backslashes (for code line
> breaks and to escape backticks), and lots of rather weird whitespacing
> to make things work, while using a heredoc would not require that.

Well, it avoids to use heredoc and the external cat(1) to print the 
help, at the cost of using more quotes and line breaks...

> A heredoc would therefore:
>
>   * be much more readable
>   * be much more easily maintainable
>   * consume considerably less space
>
> I have attached two files to this message. The first one, `usage',
> contains the version of the `usage()' function as it is currently
> implemented in Qi. The second one, `usage2', contains an implementation
> of that same function as a heredoc.
>
> Just trying to read the code of those two files in a pager, you will
> notice that `usage2' is much more readable. Also, here's a size
> comparison of the two on my system:
>
>   $ du -b *
>   6673  usage
>   3742  usage2

I am attaching a version of Qi that uses heredoc for clarity, avoiding 
invoking cat(1) to print help.

It uses spaces rather than tabs.

> > > As far as the content of `usage()' goes, I think the description of 
> > > Qi
> > > should be kept to a single line. That's pretty much what most GNU-ish
> > > command-line tools do, in my experience. People who want to know more
> > > should consult the manual page. I would keep the description as the
> > > first thing in the output of `usage()', however.

Done.

> > This is not mandatory as other GNU software contains a long 
> > description
> > (more than one line).  I see this more descriptive than a single line.
>
> Well, `--help' should really only show a quick reference, and not
> include any extensive description of the command. That's what the 
> actual
> documentation is for. `--help' is most useful as sort of a cheatsheet.
>
> > About Qi's manual page, there is not much to consult, since it is
> > oriented to the texinfo manual/guide.
>
> I see. I don't think it is a good idea to make manual pages 
> second-class
> citizens, but I know it's official GNU policy to do that.

I'm not applying a GNU policy here.  I am using GNU texinfo for 
convenience:

Unless there is a way to convert the Qi manual or guide from .texi 
format to manpage format.. I will not write or maintain a full version 
in manpage format.