Raku / RakuDoc-GAMMA

Community review of the RakuDoc standard
Artistic License 2.0
2 stars 1 forks source link

Custom bullets as per #19 #20

Closed finanalyst closed 11 months ago

finanalyst commented 11 months ago
thoughtstream commented 11 months ago

Great work, @finanalyst!

I especially love the fact that you made my examples much funnier. :-)

Here are some minor tweaks on the PR. With them in place, I'm more than happy to sign off on the PR (and for us to close out this phase of the redesign process).

-By default a compliant renderer will provide bullets for each item. RakuDoc allows
+By default, a compliant renderer will provide a bullet for each item. RakuDoc also allows
 for custom bullets as L<discussed below|#Bullets and bullet strategy>.

 =head3 Bullets and bullet strategy

-Each C<=item>R<N> will be preceded by a bullet and each level
+When rendered, each C<=item>R<N> will be preceded by a bullet and each level
-may have a different bullet. A compliant renderer will define a I<default> bullet for at least four
+may have a different bullet. A compliant renderer will define a I<default> bullet for at least the first four
-levels within a nested list, with the bulletting strategy for other levels being up to the renderer.
+levels within a nested list, with the bulleting strategy for other levels being up to the renderer.

 The default bullet can be over-ridden with a custom bullet for any C<=item>R<N>, for example
-=begin code :lang<rakudoc>
+=begin code :lang<rakudoc> :allow<B>
 The project originally consisted of five phases, of which
 two are already complete and two have been abandoned:

-=for item :bullet< E<BALLOT BOX WITH CHECK> >
+=for item B<:bullet< E<BALLOT BOX WITH CHECK> >>
 Investigate existing solutions

-=for item :bullet< E<BALLOT BOX WITH CHECK> >
+=for item B<:bullet< E<BALLOT BOX WITH CHECK> >>
 Define a minimal initial feature set

-=for item :bullet< E<BALLOT BOX> >
+=for item B<:bullet< E<BALLOT BOX> >>
 Implement this minimal set of features

-=for item :bullet< E<BALLOT BOX WITH CROSS> >
+=for item B<:bullet< E<BALLOT BOX WITH CROSS> >>
 Secure 100 million in venture capital

-=for item :bullet< E<BALLOT BOX WITH CROSS> >
+=for item B<:bullet< E<BALLOT BOX WITH CROSS> >>
 Abscond to the Bahamas with the cash
 =end code

-However, more interesting bullets are possible, including multiple characters. For example,
+However, more interesting bullets are possible, including multiple characters. For example:
-=begin code
+=begin code :lang<rakudoc> :allow<B>
-=for item :bullet< E<tick symbol> >
+=for item B<:bullet< E<tick symbol> >>
 Investigate existing solutions

-=for item :bullet< E<tick symbol> >
+=for item B<:bullet< E<tick symbol> >>
 Define a minimal initial feature set

-=for item :bullet< E<anticlockwise arrows> >
+=for item B<:bullet< E<anticlockwise arrows> >>
 Implement this minimal set of features

-=for item :bullet< E<prohibited> >
+=for item B<:bullet< E<prohibited> >>
 Secure 100 million in venture capital

-=for item :bullet< E<prohibited; palm tree> >
+=for item B<:bullet< E<prohibited; palm tree> >>
 Abscond to the Bahamas with the cash
 =end code

-By using the C<=config> directive, it is possible to change the default bullets for
+By using the C<=config> directive, it is also possible to change the default bullets for
 the duration of a section. For example,
-=begin code
+=begin code :lang<rakudoc> :allow<B>
     =begin section

-    =config item1 :bullet< E<globe showing Europe and Africa> >
+    B<=config item1 :bullet< E<globe showing Europe and Africa> >>
-    =config item2 :bullet< E<Hand with Index and Middle Fingers Crossed> >
+    B<=config item2 :bullet< E<Hand with Index and Middle Fingers Crossed> >>

         =item1 solar
         =item1 geothermal
         =item1 fusion
-        =item2 eventually
+        =item2 (eventually)
     =end section
 =end code

 🌍 solar
 🌍 geothermal
 🌍 fusion
-   🤞eventually
+   🤞(eventually)
 =end code
 =end nested

-In the event of a custom bullet cannot be rendered (eg., a specified Unicode glyph is unrecognised),
+In the event that a custom bullet cannot be rendered (e.g. a specified Unicode glyph is unrecognised or unrenderable in the target format),
-a compliant renderer will fallback to its default bullet and generate an error message.
+a compliant renderer will fall back to its default bullet and generate an error message.

     =row
             =cell C<:bullet<CHAR>>
             =cell C<=itemN>
-            =cell Replace the default bullet with a character or an entity specified with C<E< ... >>
+            =cell Replace the default bullet with one or more characters, or entities specified with C<E< ... >>