Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The word “seems” is overused #619

Closed
AlexDaniel opened this issue Jun 21, 2016 · 1 comment
Closed

The word “seems” is overused #619

AlexDaniel opened this issue Jun 21, 2016 · 1 comment
Labels
docs Documentation issue (primary issue type)

Comments

@AlexDaniel
Copy link
Member

16:41:54 * BrokenRobot wishes the docs did not use "seems" [ "to work like ..." | "do this " | "etc. " ]
16:42:18 <BrokenRobot> Makes it sound like it's a guessing game and whoever wrote it doesn't have a clue

Yes, I agree.

Current status

grep -Ri --before 3 --after 3 'seems' *    # slightly filtered manually
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-Thankfully, C<$_> is the general default variable as in Perl 5. The
Language/5to6-perlvar.pod:main difference in Perl 6 seems to be that you can now call methods on
Language/5to6-perlvar.pod-it. For instance, Perl 5's C<say $_> can be rendered in Perl 6 as
Language/5to6-perlvar.pod-C<$_.say>. Furthermore, as it is the default variable, you don't even
Language/5to6-perlvar.pod-need to use the variable name. The previous example can also be
--
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-%ENV has been replaced by %*ENV in Perl 6. Note that the keys of this hash may
Language/5to6-perlvar.pod-not be exactly the same between Perl 5 and Perl 6. As of this writing, the
Language/5to6-perlvar.pod:only difference seems to be that OLDPWD is missing from Perl 6's %ENV.
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-=item $OLD_PERL_VERSION
Language/5to6-perlvar.pod-
--
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-C<$/> now contains the match object, so the Perl 5 behavior of C<$&> can
Language/5to6-perlvar.pod-be obtained by stringifying it, i. e. C<~$/>. C<$/.Str> also should
Language/5to6-perlvar.pod:work, but C<~$/> seems to be the consensus preference.
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-=item ${^MATCH}
Language/5to6-perlvar.pod-
--
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-=item $^R
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod:S28 suggests C<$*LAST_REGEXP_CODE_RESULT>, but no variable seems to actually
Language/5to6-perlvar.pod-exist yet.
Language/5to6-perlvar.pod-
Language/5to6-perlvar.pod-=item ${^RE_DEBUG_FLAGS}
--
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=item chdir EXPR
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod:Seems to work as it does in Perl 5.
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=head2 chmod
Language/5to6-perlfunc.pod-
--
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=item evalbytes EXPR
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod:No longer seems to exist.
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=head2 exec
Language/5to6-perlfunc.pod-
--
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=item prototype FUNCTION
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod:No available in Perl 6. The closest equivalent seems to be
Language/5to6-perlfunc.pod-C<.signature>. E. g. C<say &sprintf.signature> results in "(Cool
Language/5to6-perlfunc.pod-$format, *@args)".
Language/5to6-perlfunc.pod-
--
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=item require VERSION
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod:Seems that C<require> may work for modules in Perl 6, but unclear if it
Language/5to6-perlfunc.pod-will work with version numbers.
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=head2 reset
--
Language/5to6-perlfunc.pod-=item utime LIST
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-S32 says this is gone, and refers you to C<Path.times>. Unfortunately, there
Language/5to6-perlfunc.pod:seems to be no sign of C<Path.times>. Perhaps there will be something in
Language/5to6-perlfunc.pod-C<IO::Path>, but it is not currently evident.
Language/5to6-perlfunc.pod-
Language/5to6-perlfunc.pod-=head2 values
--
Language/5to6-perlop.pod-
Language/5to6-perlop.pod-Works as you would expect. The caveat in Perl 5's perlop about C<**>
Language/5to6-perlop.pod-binding more tightly than unary minus (i. e. "-2**4" evaluates as "-(2**4)"
Language/5to6-perlop.pod:rather than "(-2)**4)") seems to hold true for Perl 6.
Language/5to6-perlop.pod-
Language/5to6-perlop.pod-=head2 Symbolic Unary Operators
Language/5to6-perlop.pod-
--
Language/5to6-perlop.pod-
Language/5to6-perlop.pod-The C<qr> operator is gone from Perl 6.
Language/5to6-perlop.pod-
Language/5to6-perlop.pod:C<tr///> is not well documented, but seems to work similarly to how it
Language/5to6-perlop.pod-does in Perl 5. The one caveat is that ranges are specified differently.
Language/5to6-perlop.pod-Instead of using a range "a-z", you would use "a..z", i. e. with Perl's
Language/5to6-perlop.pod-range operator. C<tr///> has a method version, which is better
--
Language/modules.pod-    =end code
Language/modules.pod-
Language/modules.pod-Note, C<EXPORT> can't be declared inside a package because
Language/modules.pod:presently Rakudo (2015.09) seems to treat C<EXPORT> as part of the
Language/modules.pod-compunit rather than the package.
Language/modules.pod-
Language/modules.pod-Whereas C<UNIT::EXPORT> packages deal with the named parameters passed
--
Type/IO/Notification.pod-
Type/IO/Notification.pod-The type of the change is very much dependent both on the platform and on
Type/IO/Notification.pod-specific system calls that were used initiate the change. At this point in
Type/IO/Notification.pod:time, relying on them seems to be a bad idea.
Type/IO/Notification.pod-
Type/IO/Notification.pod-=head1 Methods
Type/IO/Notification.pod-
@AlexDaniel AlexDaniel added the docs Documentation issue (primary issue type) label Jun 21, 2016
@dha
Copy link
Contributor

dha commented Jun 23, 2016

FWIW, a lot of these probably date from when these items were much less clear than they hopefully are now. As a result, there was hedging. If any of these items can be firmly nailed down, we can certainly get rid of some "seem"s.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation issue (primary issue type)
Projects
None yet
Development

No branches or pull requests

3 participants