Re: [Dragora-members] Qi 2.0rc14

[Matias Fonzo]

El 2020-07-30 21:20, Michael Siegel escribió:
> 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.

I do not consider that invoking an external tool is reliable to show the 
help of a program/script (do you know any language that does this?).  So 
optimization doesn't matter much here.

(Anyway, I can switch to echo, since printf is more effective (faster) 
when you have to print several lines, and knowing what the expected 
output is, I think there will be no problem using echo instead of 
printf).

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

Right, cat(1) is being used to produce the meta data file.  Here we can 
replace it with printf and avoid adding cat(1) in the loop for the 
requirement.

As alternative two, replace dog() with cat(1) to print the help, add 
cat(1) to the loop of requirements, and move the whole loop to the 
beginning of the script.  But as I said before, I'm still not entirely 
convinced (at least right now)...

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

Why not?.  If such a conversion exists, and it is neat.  Then the 'man' 
and 'info' audience would be satisfied.  :-)

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

That's good.  Thanks.