Re: [Bug] S-flag imposes non-greedy match where it shouldn't

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Sebastian Gniazdowski wrote on Sun, Dec 29, 2019 at 01:56:12 +0100:
> sob., 28 gru 2019, 22:01 użytkownik Daniel Shahaf <d.s@daniel.shahaf.name>
> napisał:
> 
> > Sebastian Gniazdowski wrote on Sat, Dec 28, 2019 at 20:04:21 +0100:
> > > I think that many examples in the man pages are like that – they don't
> > > go the obvious path of just demonstrating the usage but instead, they
> > > cover some edge case that, after (sometimes quite long) thinking
> > > reveal something very peculiar about the feature.
> >
> > So what?  We're not going to accept a patch that adds an unclear
> > explanation
> > simply because other explanations are unclear.
> >
> 
> I think that the style of the docs has a value. At first one can get little
> angry "why the example just doesn't confirm what I already suspect",
> however, after untangling it one most probably will feel satisfaction and
> gratefulness. It's a way to share advanced, expert knowledge.

There should be no untangling.  Documentation is about conveying knowledge, not
about presenting riddles.  The documentation of (S) should explain what (S)
does assuming as little knowledge as practicable.  Likewise, the documentation
of (#b) should, if possible, explain what (#b) does without requiring the
reader to know — or, worse, reverse engineer — details such as the greediness
of the * operator.  That detail should, of course, be documented in the section
about that operator.

> > You can't actually get rid of the variable $foo; it's needed for the «print»
> > call on the next line.
> 
> 
> Just noticing that this shows another non-trivial aspect of the example -
> that it uses mbegin and mend instead of match.

Using mbegin and mend is not non-trivial in the context of that example.

> > Otherwise, I agree.  I'll go ahead and make the change,
> > and also change the spaces to underscores.  Thanks for pointing this out.
> > Do
> > you know any other examples that have room for improvement?
> >
> 
> As I said I see much value in the current style of the docs and I've
> learned much from it, so I don't think it should be changed.

Well, I'm sorry, but I expect consensus will not side with you on this.

Do you intend to send another revision of the (S) docs patch upthread?