diff --git a/doc/Language/101-basics.rakudoc b/doc/Language/101-basics.rakudoc index 08be1e87d..a90097314 100644 --- a/doc/Language/101-basics.rakudoc +++ b/doc/Language/101-basics.rakudoc @@ -416,7 +416,7 @@ Let's see an example of this now. In this example, you will see some special syntax that makes it easier to make a list of strings. This is the C«<...>» L -construct. When you put words in between the < and > they are all assumed +construct. When you put words in between the C«<» and C«>» they are all assumed to be strings, so you do not need to wrap them each in double quotes C«"..."». diff --git a/doc/Language/5to6-nutshell.rakudoc b/doc/Language/5to6-nutshell.rakudoc index 54dbe8772..7352d914a 100644 --- a/doc/Language/5to6-nutshell.rakudoc +++ b/doc/Language/5to6-nutshell.rakudoc @@ -1108,7 +1108,7 @@ ago and may lack features that have been added since the beginning of the Raku project. Two such features not yet implemented in Raku for the P5 syntax are the Perl Unicode property matchers C<\p{}> and C<\P{}>. -=head2 Special matchers generally fall under the <> syntax +=head2 Special matchers generally fall under the C«<>» syntax There are many cases of special matching syntax that Perl regexes support. They won't all be listed here but often, instead of being diff --git a/doc/Language/5to6-perlvar.rakudoc b/doc/Language/5to6-perlvar.rakudoc index 46b8f98d8..78c7f50b1 100644 --- a/doc/Language/5to6-perlvar.rakudoc +++ b/doc/Language/5to6-perlvar.rakudoc @@ -216,7 +216,7 @@ The C method on all of the above produces the I version of the infor at the current time the C. All the objects have other methods that can be useful when trying to identify the -exact running instance, for more information use <.^methods> to introspect all the above. +exact running instance, for more information use C<.^methods> to introspect all the above. =head3 %SIG diff --git a/doc/Language/js-nutshell.rakudoc b/doc/Language/js-nutshell.rakudoc index ccfc3d9bd..7bdf8f102 100644 --- a/doc/Language/js-nutshell.rakudoc +++ b/doc/Language/js-nutshell.rakudoc @@ -99,6 +99,7 @@ constant foo = 1; # Package scoped; constant my $*foo = 1; # Dynamic variable; lexically scoped our $*foo = 1; # Dynamic variable; package scoped +=for code GLOBAL::<$foo> := 1; # Globally scoped Use C where you'd use C, C for variables you'd define in the diff --git a/doc/Language/modules.rakudoc b/doc/Language/modules.rakudoc index 84a1ed51c..c074b568e 100644 --- a/doc/Language/modules.rakudoc +++ b/doc/Language/modules.rakudoc @@ -1063,7 +1063,7 @@ fez register =item Now you can upload your module! -Before doing the following, ensure your C file's "auth" matches "zef:" and then: +Before doing the following, ensure your C file's C matches C«zef:» and then: =begin code :lang fez upload diff --git a/doc/Language/quoting.rakudoc b/doc/Language/quoting.rakudoc index 5d70f48ac..a38bef20e 100644 --- a/doc/Language/quoting.rakudoc +++ b/doc/Language/quoting.rakudoc @@ -355,7 +355,7 @@ It's easier to write and to read this: my @directions = qw|left right up down|; -=head2 Word quoting: < > +=head2 Word quoting: C«< >» X«|Syntax,< > word quote» =for code :allow diff --git a/doc/Language/regexes.rakudoc b/doc/Language/regexes.rakudoc index 0dbba86bd..3424813b8 100644 --- a/doc/Language/regexes.rakudoc +++ b/doc/Language/regexes.rakudoc @@ -2388,7 +2388,7 @@ C«<.ws>» subrule calls depending on where it occurs in the regex. =end code C acts the same as -C shop <.ws> />. By default, C«<.ws>» makes sure that +C» shop <.ws> />. By default, C«<.ws>» makes sure that words are separated, so C and C<^&> will match C«<.ws>» in the middle, but C won't: diff --git a/doc/Type/CX/Done.rakudoc b/doc/Type/CX/Done.rakudoc index 403c6d1dc..8adb7ccc5 100644 --- a/doc/Type/CX/Done.rakudoc +++ b/doc/Type/CX/Done.rakudoc @@ -15,6 +15,6 @@ indicate a supply block is finished by calling C. method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Emit.rakudoc b/doc/Type/CX/Emit.rakudoc index 2aa0b65c1..dca7da48b 100644 --- a/doc/Type/CX/Emit.rakudoc +++ b/doc/Type/CX/Emit.rakudoc @@ -15,6 +15,6 @@ emit is used inside a C block. method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Last.rakudoc b/doc/Type/CX/Last.rakudoc index 23aaab536..b951667f5 100644 --- a/doc/Type/CX/Last.rakudoc +++ b/doc/Type/CX/Last.rakudoc @@ -15,7 +15,7 @@ when C is called. method message() -Returns "". Since this type of exception is to be +Returns C<''>. Since this type of exception is to be consumed by type and not really by the content of the message, this is a generic message, similar to all other C exceptions. diff --git a/doc/Type/CX/Next.rakudoc b/doc/Type/CX/Next.rakudoc index f844a4202..4b0015ab2 100644 --- a/doc/Type/CX/Next.rakudoc +++ b/doc/Type/CX/Next.rakudoc @@ -39,6 +39,6 @@ We're in 9 method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Proceed.rakudoc b/doc/Type/CX/Proceed.rakudoc index 28be609a2..baa1f5a6a 100644 --- a/doc/Type/CX/Proceed.rakudoc +++ b/doc/Type/CX/Proceed.rakudoc @@ -15,6 +15,6 @@ C is used within C or C blocks. method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Redo.rakudoc b/doc/Type/CX/Redo.rakudoc index d69aaec97..632c16983 100644 --- a/doc/Type/CX/Redo.rakudoc +++ b/doc/Type/CX/Redo.rakudoc @@ -15,6 +15,6 @@ C is called. method message() -Returns "". +Returns C<''>. =end pod diff --git a/doc/Type/CX/Return.rakudoc b/doc/Type/CX/Return.rakudoc index b7462f1aa..06e0c5063 100644 --- a/doc/Type/CX/Return.rakudoc +++ b/doc/Type/CX/Return.rakudoc @@ -15,6 +15,6 @@ return is called from within a sub. method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Succeed.rakudoc b/doc/Type/CX/Succeed.rakudoc index f9d360e76..023d7247f 100644 --- a/doc/Type/CX/Succeed.rakudoc +++ b/doc/Type/CX/Succeed.rakudoc @@ -15,6 +15,6 @@ C is called from a C or C block. method message() -Returns "" +Returns C<''>. =end pod diff --git a/doc/Type/CX/Take.rakudoc b/doc/Type/CX/Take.rakudoc index f8a91e47e..e22ae5a97 100644 --- a/doc/Type/CX/Take.rakudoc +++ b/doc/Type/CX/Take.rakudoc @@ -15,6 +15,6 @@ C. method message() -Returns "". +Returns C<''>. =end pod diff --git a/doc/Type/CX/Warn.rakudoc b/doc/Type/CX/Warn.rakudoc index 06d6cd84a..afe00b7f0 100644 --- a/doc/Type/CX/Warn.rakudoc +++ b/doc/Type/CX/Warn.rakudoc @@ -15,5 +15,4 @@ incidence. C objects are created when a warning is thrown in any block. - =end pod diff --git a/doc/Type/Thread.rakudoc b/doc/Type/Thread.rakudoc index ac60c3631..5f2246bb2 100644 --- a/doc/Type/Thread.rakudoc +++ b/doc/Type/Thread.rakudoc @@ -109,7 +109,7 @@ the thread will be killed when the main thread of the process terminates. method name(Thread:D: --> Str:D) Returns the user defined string, which can optionally be set during object -creation in order to identify the C, or '' if no such string +creation in order to identify the C, or C<''> if no such string was specified. my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }}); diff --git a/doc/Type/X/Method/InvalidQualifier.rakudoc b/doc/Type/X/Method/InvalidQualifier.rakudoc index a50e1f913..b82fb3355 100644 --- a/doc/Type/X/Method/InvalidQualifier.rakudoc +++ b/doc/Type/X/Method/InvalidQualifier.rakudoc @@ -7,7 +7,7 @@ class X::Method::InvalidQualifier is Exception { } Thrown when a method is call in the form C<$invocant.TheClass::method> if -<$invocant> does not conform to C. +C<$invocant> does not conform to C. For example diff --git a/xt/rakudoc-brackets.rakutest b/xt/rakudoc-brackets.rakutest new file mode 100755 index 000000000..f8a5e2622 --- /dev/null +++ b/xt/rakudoc-brackets.rakutest @@ -0,0 +1,62 @@ +#!/usr/bin/env raku + +=begin overview + +It's possible for users to forget to add a formatting code when +wrapping something in angle brackets: + + This was supposed to be . + +This is valid pod, but in practices, these dangling <>'s often indicate an error. +Complain whenever we find them, except for infix:<> and prefix:<> + +=end overview + +use Test; +use lib $*PROGRAM.parent(2).child('lib'); + +use Test-Files; +use Pod::Convenience; + +my @files = Test-Files.pods; + +if @files { + plan +@files; +} else { + plan :skip-all +} + +sub is-valid-text($node) { + # Should be ok to look at only literal strings that get passed + if $node ~~ Str { + if $node ~~ / $=['<' .*? '>'] / { + return if ~$/.contains("prefix:<" | "infix:<" ); + flunk ~$/ ~ " is likely missing a formatting code"; + } + } + +} + +sub walk-content($item) { + if !( + $item ~~ Pod::Block::Code or + $item ~~ Pod::Block::Comment or + $item ~~ Pod::FormattingCode + ) { + is-valid-text($item); + next unless $item.can('contents'); + for @($item.contents) -> $child { + walk-content($child); + } + } +} + +# Walk through pod on each file. +for @files -> $file { + my @chunks = extract-pod($file).contents; + + # This emits pass or flunk for each local L<> found. + subtest $file => { + walk-content($_) for @chunks; + } +}