Tagged parameters

Tagged parameters

[Marlon Richert]

man zshbuiltins says that `typeset -t` "tags the named parameters",
but also that "tags have no special meaning to the shell."

Is there a practical use case for this? Why was this implemented?

Re: Tagged parameters

[Peter Stephenson]

> On 15/08/2023 06:51 Marlon Richert <marlon.richert@gmail.com> wrote:
> man zshbuiltins says that `typeset -t` "tags the named parameters",
> but also that "tags have no special meaning to the shell."
> 
> Is there a practical use case for this? Why was this implemented?

It's inherited from ksh.

It's useful if there are certain parameters you want to keep track
of e.g. for debugging, because you can ask the shell to show you all
tagged parameters instead of giving a list.

% typeset -t foo=one bar=two
% typeset -t                
bar=two
foo=one

Saying they have "no special meaning to the shell" is perhaps not a
100% helpful description. since the fact of just having this option
associated with them is itself "special" in the way shown above.

pws

Re: Tagged parameters

[Ray Andrews]

On 2023-08-15 01:27, Peter Stephenson wrote:
>
> Saying they have "no special meaning to the shell" is perhaps not a
> 100% helpful description. since the fact of just having this option
> associated with them is itself "special" in the way shown above.
Thanks Peter.  "tags have no special meaning to the shell" is 
anti-information.  Perhaps something like: "When a parameter is tagged, 
it changes in no way except that the command: 'typeset -t' will make a 
list of all tagged parameters along with their values."
> pws
>

Re: Tagged parameters

[Peter Stephenson]

On 15/08/2023 15:30 Ray Andrews <rayandrews@eastlink.ca> wrote:
> On 2023-08-15 01:27, Peter Stephenson wrote:
>> Saying they have "no special meaning to the shell" is perhaps not a
>> 100% helpful description. since the fact of just having this option
>> associated with them is itself "special" in the way shown above.
>
> Thanks Peter.  "tags have no special meaning to the shell" is 
> anti-information.  Perhaps something like: "When a parameter is tagged, 
> it changes in no way except that the command: 'typeset -t' will make a 
> list of all tagged parameters along with their values."

Yes, it's worth doing something... here's my go.

pws

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 5eb9327..b8ce31a 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -2320,8 +2320,10 @@ readonly). Special variables that have been made readonly retain their value
 and readonly attribute when made local.
 )
 item(tt(-t))(
-Tags the named parameters.  Tags have no special meaning to the shell.
-This flag has a different meaning when used with tt(-f); see above.
+Tags the named parameters.  Tags only exist to mark the parameter for
+the user's own purposes: the set of tagged parameters can be queried
+using `tt(typeset -t)'.  They have no further special meaning to the
+shell.  This flag has a different meaning when used with tt(-f); see above.
 )
 item(tt(-u))(
 Convert the result to upper case whenever the parameter is expanded.

Re: Tagged parameters

[Ray Andrews]

On 2023-08-15 07:39, Peter Stephenson wrote:
>
> Yes, it's worth doing something... here's my go.
>
> +Tags the named parameters.  Tags only exist to mark the parameter for
> +the user's own purposes: the set of tagged parameters can be queried
> +using `tt(typeset -t)'.  They have no further special meaning to the
> +shell.  This flag has a different meaning when used with tt(-f); see above.
>   )

That is so much better.  We go from a conveyed information score of -10 
to +90 in one effort.  Since there is no end to little edits (which have 
an asymptotic convergence on perfection), I'd tweak it:

+Tags the named parameters.  Tags only exist to 'flag' the parameter for
+the user's own purposes -- the list of tagged parameters can be queried
+using `tt(typeset -t)'.  Tags have no other use.  Note that the `-t` flag has a different meaning when used with tt(-f); see above.
  )

'flag' because that's the word used lower down

'list' instead of 'set' because set sounds too mathematical

'no other use' is simpler than 'no further special meaning to the shell' -- there is no other, not just no other *special* -- it makes one wonder what an un-special meaning might be.  And 'to the shell' makes one wonder what a use *outside the shell* might possibly be.

'-t' just keeps things specific.

And I'd add 'Note that' simply to flag the otherwise usage.  It's polite.

I dream of a manual that is designed to inform the one seeking information rather than display the knowledge of the writer to himself.

Re: Tagged parameters

[Lawrence Velázquez]

On Tue, Aug 15, 2023, at 11:16 AM, Ray Andrews wrote:
> I dream of a manual that is designed to inform the one seeking 
> information rather than display the knowledge of the writer to himself.

The contributors are trying their best.  Kindly keep your
passive-aggressive, condescending editorializing to yourself.

-- 
vq

Re: Tagged parameters

[Ray Andrews]

On 2023-08-15 10:40, Lawrence Velázquez wrote:
> On Tue, Aug 15, 2023, at 11:16 AM, Ray Andrews wrote:
>> I dream of a manual that is designed to inform the one seeking
>> information rather than display the knowledge of the writer to himself.
> The contributors are trying their best.
Of course, and as I said, Peter just made what I'd call a small but 
exemplary improvement.
>    Kindly keep your
> passive-aggressive, condescending editorializing to yourself.

On the  contrary there's no aggression here and no condescension 
either.  The problem of manuals being written by people who are already 
experts is always hard to avoid.  Manuals must serve the person who is 
not already an expert and that's difficult because the minds are 
different.  If I was an expert I'd have the same issue.

But you are senior here and if my remarks are taken in a negative light 
then they will stop.  One seconder of your point of view and I'll never 
make another comment, positive or suggestive or negative.  Nothing I 
will every contribute is worth offending yourself,  you're too important.

Re: Tagged parameters

[Grant Taylor]

On 8/15/23 1:10 PM, Ray Andrews wrote:
> The problem of manuals being written by people who are already experts 
> is always hard to avoid.

Who would you suggest write about ${TOPIC} if not someone that has 
already learned about ${TOPIC} and ostensibly has some level of mastery 
/ expertise thereof?

> Manuals must serve the person who is not already an expert and that's 
> difficult because the minds are different.

I don't agree.

Documentation, of any sort, is better than no documentation.

N.B. I don't consider source code to be documentation that is accessible 
by most people.

Yes, there is some documentation that tends to qualify as more reference 
material and other documentation that qualifies as more teaching 
material.  Traditional manual pages are often an example of the former. 
While Ho-To guides on The Linux Documentation Project tend to be 
examples of the latter.

I believe there are places for both types of documentation.  What's more 
is that neither type of documentation precludes the other from existing.

I would much rather have something terse, dense, and quick from a 
programmer that doesn't have time to word smith than not have even that.

Others who don't feel comfortable can take the snippet from the 
programmer and turn it into more friendly if not training friendly 
documentation.

Re: Tagged parameters

[Clinton Bunch]

On 8/15/2023 17:41, Grant Taylor wrote:
> On 8/15/23 1:10 PM, Ray Andrews wrote:
>> The problem of manuals being written by people who are already 
>> experts is always hard to avoid.
>
> Who would you suggest write about ${TOPIC} if not someone that has 
> already learned about ${TOPIC} and ostensibly has some level of 
> mastery / expertise thereof?
>
>> Manuals must serve the person who is not already an expert and that's 
>> difficult because the minds are different.
>
> I don't agree.
>
> Documentation, of any sort, is better than no documentation.
>
> N.B. I don't consider source code to be documentation that is 
> accessible by most people.
>
> Yes, there is some documentation that tends to qualify as more 
> reference material and other documentation that qualifies as more 
> teaching material.  Traditional manual pages are often an example of 
> the former. While Ho-To guides on The Linux Documentation Project tend 
> to be examples of the latter.
>
> I believe there are places for both types of documentation. What's 
> more is that neither type of documentation precludes the other from 
> existing.
>
> I would much rather have something terse, dense, and quick from a 
> programmer that doesn't have time to word smith than not have even that.
>
> Others who don't feel comfortable can take the snippet from the 
> programmer and turn it into more friendly if not training friendly 
> documentation.
>
I always thought that was what technical writers were for.


Of course, we could always hand it to ChatGPT to write the Zsh manual :)

Re: Tagged parameters

[Bart Schaefer]

On Thu, Aug 17, 2023 at 4:41 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>
> I always thought that was what technical writers were for.

If you know any who would like to volunteer for this project, please
point them our way.  Otherwise you get what you pay for.

Re: Tagged parameters

[Ray Andrews]

On 2023-08-17 18:10, Bart Schaefer wrote:
> On Thu, Aug 17, 2023 at 4:41 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>> I always thought that was what technical writers were for.
> If you know any who would like to volunteer for this project, please
> point them our way.  Otherwise you get what you pay for.
>
True.  Which is why any any apparently negative comment of mine is never 
anything other than a suggestion, not a complaint.  I have zero grounds 
to complain about free software that is, overall, a fantastic 
achievement, warts and all.