dragora-members
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Dragora-members] Qi 2.0rc14


From: Michael Siegel
Subject: Re: [Dragora-members] Qi 2.0rc14
Date: Sat, 25 Jul 2020 01:21:11 +0200
User-agent: Mozilla/5.0 (X11; Linux i686; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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.

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

>> 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.
>>
> 
> 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.


--Michael

Attachment: usage
Description: Text document

Attachment: usage2
Description: Text document


reply via email to

[Prev in Thread] Current Thread [Next in Thread]