Re: CVS commit: [pgoyette-compat] src/sys/kern

[Christos Zoulas]

In article <20180317025636.7ee0df...@cvs.netbsd.org>,
Paul Goyette  wrote:
>-=-=-=-=-=-
>
>Module Name:   src
>Committed By:  pgoyette
>Date:  Sat Mar 17 02:56:36 UTC 2018
>
>Modified Files:
>   src/sys/kern [pgoyette-compat]: kern_cpu.c
>
>Log Message:
>Use two different compat stubs since they have different prototypes.

This is more of a mess now. There is no point exposing all these functions
and API's.

christos

Re: CVS commit: src/bin/sh

[Robert Elz]

Date:Sat, 17 Mar 2018 03:46:44 +0300
From:Valery Ushakov 
Message-ID:  <20180317004644.gh3...@pony.stderr.spb.ru>

  | That reminds me...  We currently abuse ENVIRONMENT section to document
  | variables like PS1 or HISTSIZE which are quite obviously not
  | environment variables.

Actually they are - those two particularly.   In principle, essentially
all shell variables are (potentially) environment variables - all they
need to be is either in the environ when the shell starts, or be the
subject of export (or set -a).

But it is very common for PS1 and HISTSIZE to be imported from
the environment, and exported again - if sh were a true posix
shell that would be the normal way for them to be set in all but
login shells.   But that's how I set that kind of var when I run
an xterm - I do "HISTSIZE=nnn PS1='$ '  xterm -ut -geom ..."
and the HISTSIZE (etc) passed in the env to xterm get passed
down to the shell, and set that way.   [Different xterms get different
settings of course, so the shells run in them get configured
differently, to meet the needs of whatever that window is to
be used for.]

LINENO (which was the subject of an earlier commit) is a trickier
case - it can be exported to the environment, but it isn't imported
from there (though if it is in the environ of the shell when it starts,
it will be exported again - just the value in the environ is ignored.)
Having it in the environ is a rare (and not so useful) case.

  I think most of them should be moved out of
  | .Sh ENVIRONMENT into a separate .Ss section inside .Sh DESCRIPTION

I will leave that to the people who understand the principles of
the NetBSD man page layout.

  | (and the LINENO section should moved into DESCRIPTION as well).

That too.   The content (text) is what matters more to me,  where in the
man page it appears, and what kind of markup macros are used is of
far less interest.   (This also does not imply that I am satisfied with
the content of the section, or that the other issues are unimportant.)

kre

Re: CVS commit: src/bin/sh

[Valery Ushakov]

On Fri, Mar 16, 2018 at 23:58:30 +0700, Robert Elz wrote:

> Date:Fri, 16 Mar 2018 17:24:55 +0300
> From:Valery Ushakov 
> Message-ID:  <20180316142455.gf3...@pony.stderr.spb.ru>
> 
>   | mdoc.samples(7) is a very handy reference.
> 
> For me that is the same as mdoc(7) (a copy of the same
> man page) - is that what is intended (I see mdoc.samples(7) has
> 2 links - I did not chase down and find what the other is, except
> to know it is not mdoc(7) which is a copy) and while I agree that it is
> useful, it isn't all that useful - for example, it says that Dv is
> for:
>   A variable (or constant) which is defined in an include file
> 
> And so which would never be appropriate in sh(1) for which
> include files are irrelevant.
>
> This is one of the reasons I have typically avoided mdoc -- while
> I understand and agree with the intent, much of what it provides
> is far too specific, and leaves too many cases fall through the
> cracks.   Defined variables (which I would extend beyond include
> files to also allow anything #define'd - in an include file or not)
> environment variables, arguments, internal commands, command
> modifiers (and flags) all have macros, just just simple variables,
> which are none of those, and constants, do not seem to have a
> macro of their own - and just fall back on the catch all Li (literal).
>
> Given that, was changing .Li 0 into .Dv 0 really the right thing to
> do?   "0" is certainly not a defined variable...(changing the
> input to whatever just happens to generate the output desired,
> regardless of semantics seems like cheating to me.)

Right, mdoc vocabulary is defined sometimes in a bit too C-centric
terms, however even its own man page has a passage or two that
indicate that common sense should be used when it's applied to other
languages.  Defining wast hair-splitting vocabularies is possible, but
do we really want a version of DocBook for troff? :)

IMO, .Dv is the perfect match for shell parameters that has defined
semantic associated with them.

That reminds me...  We currently abuse ENVIRONMENT section to document
variables like PS1 or HISTSIZE which are quite obviously not
environment variables.  I think most of them should be moved out of
.Sh ENVIRONMENT into a separate .Ss section inside .Sh DESCRIPTION
(and the LINENO section should moved into DESCRIPTION as well).

-uwe

re: CVS commit: src

[matthew green]

"Ryota Ozaki" writes:
> Module Name:  src
> Committed By: ozaki-r
> Date: Fri Mar 16 04:37:55 UTC 2018
> 
> Modified Files:
>   src/share/man/man4: ddb.4
>   src/sys/ddb: db_command.c
>   src/sys/sys: lockdebug.h
> 
> Log Message:
> Add a new command, show lockstat, which shows statistics of locks
> 
> Currently the command shows the number of allocated locks.
> 
> The command is useful only if LOCKDEBUG is enabled.

would you mind renaming this?  "lockstat" makes me think of
lockstat(8), not what this does.  "lockinfo"?  "lockstate"?

thanks.


.mrg.

Re: CVS commit: src/bin/sh

[Robert Elz]

Date:Fri, 16 Mar 2018 17:24:55 +0300
From:Valery Ushakov 
Message-ID:  <20180316142455.gf3...@pony.stderr.spb.ru>

  | mdoc.samples(7) is a very handy reference.

For me that is the same as mdoc(7) (a copy of the same
man page) - is that what is intended (I see mdoc.samples(7) has
2 links - I did not chase down and find what the other is, except
to know it is not mdoc(7) which is a copy) and while I agree that it is
useful, it isn't all that useful - for example, it says that Dv is
for:
A variable (or constant) which is defined in an include file

And so which would never be appropriate in sh(1) for which
include files are irrelevant.

This is one of the reasons I have typically avoided mdoc -- while
I understand and agree with the intent, much of what it provides
is far too specific, and leaves too many cases fall through the
cracks.   Defined variables (which I would extend beyond include
files to also allow anything #define'd - in an include file or not)
environment variables, arguments, internal commands, command
modifiers (and flags) all have macros, just just simple variables,
which are none of those, and constants, do not seem to have a
macro of their own - and just fall back on the catch all Li (literal).

Given that, was changing .Li 0 into .Dv 0 really the right thing to
do?   "0" is certainly not a defined variable...(changing the
input to whatever just happens to generate the output desired,
regardless of semantics seems like cheating to me.)

kre

Re: CVS commit: src/bin/sh

[Valery Ushakov]

On Fri, Mar 16, 2018 at 18:59:49 +0700, Robert Elz wrote:

> Date:Fri, 16 Mar 2018 14:41:22 +0300
> From:Valery Ushakov 
> Message-ID:  <20180316114122.gd3...@pony.stderr.spb.ru>
> 
>   |  Please, add them back, and ideally add them also to
>   | the references to the parameters that you changed
> 
> Done.  Including one or two that you had not marked I think.
> 
> I also fixed the @ that should have been $@.
> 
> I will also change the Li to Dv in the ones that should be
> changed (mdoc markup is not my thing - I use whatever
> seems to work)

Thanks!

mdoc.samples(7) is a very handy reference.

-uwe

Re: CVS commit: src/bin/sh

[Robert Elz]

Date:Fri, 16 Mar 2018 14:15:47 +0300
From:Valery Ushakov 
Message-ID:  <20180316111547.gc3...@pony.stderr.spb.ru>

  | Or:
  |
  | When a shell function is executed, all of the shell positional
  | parameters (except $0, which remains unchanged) are set to [...]
  |
  | where 0 is a special parameter, not a positional parameter, to begin
  | with, and where the principle you refer to in your mail requires
  | "except 0", without the $ sign.

Yes, I was fixing all that while you were sending this message.

  | Also some of them are in .Dq and some not, so
[...]
  | but may be it would be a good idea to
  | mark up all of them in this (or some other) way consistently.

Yes, probably, but that is, I think, for some other day.

sh(1) still needs lots of work - thanks for all you have done in the
past few days.

  | I also try to add the form with the dollar sign in a comment for the
  | occurences I stumble upon just to make them more searchable in the
  | source at least (cf. "far more zeroes" :).

Wsh I had seen that before I deleted them all...   but they should be back
now I think (along with a comment on the first such comment commenting
on what the comment is commenting on).
[And *no-one* make comments about ending sentences with
 prepositions!]

kre

Re: CVS commit: src/bin/sh

[Robert Elz]

Date:Fri, 16 Mar 2018 14:41:22 +0300
From:Valery Ushakov 
Message-ID:  <20180316114122.gd3...@pony.stderr.spb.ru>

  | The yak is much more entangled now, at least its source form is!
  |
  | -.Dv 0 \" $0
  | +.Dv 0
  |
  | Why did you delete roff *comments* with $0 and the like?! 

I had not seen your earlier message - I (wrongly) assumed that
those were ones that (had you been ready to change) were planned
to switch from 0 to $0 (etc).

  |  Please, add them back, and ideally add them also to
  | the references to the parameters that you changed

Done.  Including one or two that you had not marked I think.

I also fixed the @ that should have been $@.

I will also change the Li to Dv in the ones that should be
changed (mdoc markup is not my thing - I use whatever
seems to work)

kre

Re: CVS commit: src/bin/sh

[Valery Ushakov]

On Fri, Mar 16, 2018 at 14:41:22 +0300, Valery Ushakov wrote:

> -.Li $1 ,
> +.Li 1 ,

PS: Also, the semantically correct change is from .Li $1 to .Dv 1

-uwe

Re: CVS commit: src/bin/sh

[Valery Ushakov]

On Fri, Mar 16, 2018 at 11:19:24 +, Robert Elz wrote:

> Module Name:  src
> Committed By: kre
> Date: Fri Mar 16 11:19:24 UTC 2018
> 
> Modified Files:
>   src/bin/sh: sh.1
> 
> Log Message:
> Give the yak a quick trim and shave, and make one or two minor
> wording changes (which are, hopefully, improvements).

The yak is much more entangled now, at least its source form is!

-.Dv 0 \" $0
+.Dv 0

Why did you delete roff *comments* with $0 and the like?!  That makes
it MUCH harder to search the roff sources for single character
parameter names.  Please, add them back, and ideally add them also to
the references to the parameters that you changed

-.Li $1 ,
+.Li 1 ,

-uwe

Re: CVS commit: src/bin/sh

[Valery Ushakov]

On Fri, Mar 16, 2018 at 17:11:09 +0700, Robert Elz wrote:

> Date:Thu, 15 Mar 2018 01:20:43 +
> From:"Valeriy E. Ushakov" 
> Message-ID:  <20180315012043.c3d92f...@cvs.netbsd.org>
> 
>   | The manual is still rather inconsistent e.g. when referring to
>   | parameters where it randomly uses both $0 and 0 or $@ and @ - but I'm
>   | not shaving that yak at least for now.
> 
> Please be careful if you get cold, and decide you need the wool.
> 
> I have just done a brief scan (of the @ uses at least) and I think
> at least most of them are correct as they are (at least, I did not
> see any that are not - but I did not look carefully at every one.)
> 
> The man page uses just "@" when it is referring to the name of
> the special parameter, and "$@" when it is referring to the results
> of expanding that special paramater, so it is correct to say
> 
>   $@ expands to ...
> but would not be to say
>   @ expands to
> as @ doesn't expand to anything, it is just a character.
> 
> Similarly,
>   the special parameter @ gives a list of ...
> (or "expands to ...") is correct,. but
>   the special parameter $@ gives ...
> would not be, as $@ is not a special parameter (or
> not normally.)
> 
> $0 is also the expansion of the special parameter 0,
> it would have the same usage rules (though I did not
> look for that one - there are far more 0's in the man page
> than @'s!)

Yes, I understand that.  Though there are still some problematic (at
least to my eye) wording in that area.  E.g.

If there are no positional parameters, the expansion of @
generates zero arguments, even when @ is double-quoted.  [...]
then "$@" expands to [...]

where

when @ is double-quoted

is, pedantically, wrong.  It's not @ that is double-quoted, it's $@.


Or:

When a shell function is executed, all of the shell positional
parameters (except $0, which remains unchanged) are set to [...]

where 0 is a special parameter, not a positional parameter, to begin
with, and where the principle you refer to in your mail requires
"except 0", without the $ sign.


Also some of them are in .Dq and some not, so

A sub-shell retains the same value of $ as its parent.

but

the value of the special parameter ``!''

Now, obviously, the exclamation mark without .Dq would be very
confusing inside a sentence, but may be it would be a good idea to
mark up all of them in this (or some other) way consistently.

I also try to add the form with the dollar sign in a comment for the
occurences I stumble upon just to make them more searchable in the
source at least (cf. "far more zeroes" :).

-uwe

Re: CVS commit: src/bin/sh

[Robert Elz]

Date:Thu, 15 Mar 2018 01:20:43 +
From:"Valeriy E. Ushakov" 
Message-ID:  <20180315012043.c3d92f...@cvs.netbsd.org>

  | The manual is still rather inconsistent e.g. when referring to
  | parameters where it randomly uses both $0 and 0 or $@ and @ - but I'm
  | not shaving that yak at least for now.

Please be careful if you get cold, and decide you need the wool.

I have just done a brief scan (of the @ uses at least) and I think
at least most of them are correct as they are (at least, I did not
see any that are not - but I did not look carefully at every one.)

The man page uses just "@" when it is referring to the name of
the special parameter, and "$@" when it is referring to the results
of expanding that special paramater, so it is correct to say

$@ expands to ...
but would not be to say
@ expands to
as @ doesn't expand to anything, it is just a character.

Similarly,
the special parameter @ gives a list of ...
(or "expands to ...") is correct,. but
the special parameter $@ gives ...
would not be, as $@ is not a special parameter (or
not normally.)

$0 is also the expansion of the special parameter 0,
it would have the same usage rules (though I did not
look for that one - there are far more 0's in the man page
than @'s!)

kre