Re: [Dragora-members] Qi 2.0rc14

[Michael Siegel]

Am 26.07.20 um 01:11 schrieb 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ó:
>>>>
>>>> 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:

[...]

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

Nice. But why would you re-implement cat(1) for this? I wouldn't do
that, for two reasons:

  * Displaying help text is a one-shot operation, i.e., `cat'-ing that
    heredoc is the only actual action Qi has to perform when called with
    `--help'. In other words: This really doesn't need to be optimized
    for speed. Running `printf' in a loop is probably not providing much
    of an optimization there anyway.

  * You're using cat(1) already elsewhere in the script and would
    therefore have to check for its availability anyway. (This is not
    done, currently, as far as I can see, by the way.)

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

Thanks.

[...]

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

I see. IMO, info documents serve a bit of a different purpose than
manual pages, so:

  a) Converting the texinfo manual to a manual page would probably not
     be such a good idea anyway.
  b) The man page doesn't have to contain everything the info manual
     contains.

All things considered, I think the only way to have a reasonable manual
page alongside the info manual is to write that manual page by hand. So,
this should probably be a long-term goal, at least. I've started
learning to work with groff's 'man' macro package a bit, recently
because I need to create a manual page for my note-taking script. So, I
might be able to assist with Qi's manual page.


--Michael