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.

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.

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.

-- 
Best regards,
Sebastian Gniazdowski