Raku
RakuDoc V1 description can be improved
I am working on a project using RakuDoc V1 and see some problems in the current docs that need some rework to improve definitions and examples.
In addition, some new examples should be added.
Note I am the guilty party since I did much of the transcription of S26 to the current structure, and I should have continued to improve them but didn't.
As one example, the configuration description and examples do not state how to separate multiple keys:
spaces?
commas?
semicolons?
other?
all of the above?
I'll ignore the more general issue but comment on this bit:
the configuration description and examples do not state how to separate multiple keys:
spaces?
commas?
semicolons?
other?
all of the above?
FWIW I would guess that the options in the RakuDoc slang are consistent with the MAIN slang. Even if that's not so, my guess is that it would work well to say that they are, and link to / transclude some description of those options in the doc, and then just describe any exceptions that apply to the RakudDoc slang (preferably ignoring any inadequacies that are due to a lack of implementation tuits).
I'll clarify what I mean by "consistent" after first noting that all but the last of the following say .rakus returns the same expected result, (:a, :b, :c), using a 2024 Rakudo:
say $*RAKU.compiler.version;
say .raku for
( #`α CC aka comptime constants α :a, :b, :c ),
( #`α RE aka runtime expressions α :a({True}()), :b({True}()), :c({True}()) ),
( #`α CCα :a, :b, :c ), # comma
( #`α CCα :a :b :c ), # space
( #`α CCα :a, :b :c ), # comma then space
( #`α CCα :a :b, :c ), # space then comma
( #`α REα :a({True}()), :b({True}()), :c({True}()) ), # comma
( #`α REα :a({True}()) :b({True}()) :c({True}()) ), # space
( #`α REα :a({True}()), :b({True}()) :c({True}()) ), # comma then space
( #`α REα :a({True}()) :b({True}()), :c({True}()) ), # space then comma
( #`α REα :a({True}()), |(:b({True}()), :c({True}())) ), # comma then slip/comma
( #`α REα :a({True}()), |(:b({True}()) :c({True}())) ), # comma then slip/space
( #`α REα :a({True}()), |(:b({True}()); :c({True}())) ), # comma then slip/semi
( #`α REα :a({True}()) |(:b({True}()); :c({True}())) ), # FAIL! any(:a, (:b, :c))
My guess is that, if there are differences or other fails in Rakudo's current behavior for configuration data of RakuDoc commands (or whatever they're called), those differences/fails are to do with the CC vs RE distinction, and some or all of those differences/fails may be resolvable by either just switching to use of RakuAST, or devs doing further RakuAST work. (Though I could also well imagine that some or all use of RE is just not resolvable for configuration that must become constant at compile time, which may be all of it.)
Finally, what I meant by "consistent" in my guess is that I'm guessing the RakuDoc slang supports either exactly the same options that the MAIN slang supports, or a strict subset of them (perhaps only CC, not RE, or all CC but not all RE).
Here is the lead-in text in the current main branch:
Rakudoc is an easy-to-use markup language. It can be used for
writing language documentation, for documenting programs and modules, as
well as for other types of document composition.
Every Rakudoc document has to begin with C<=begin pod> and end with C<=end pod>.
Everything between these two delimiters will be processed and used to generate
documentation.
What I would like Raku users to consider instead is something like this:
RakuDoc V1 is an easy-to-use markup language. It can be used for
writing language documentation, documenting programs and modules, as
well as for other types of document composition.
A Raku program can have segments of RakuDoc markup with appropriate RakuDoc
directives, but that use is not recommended, especially considering future RakuAST handling which should be a bit more restrictive.
A better practice for stand-alone RakuDoc documents is to begin them with a C<=begin pod>
and end with C<=end pod>. Everything between those two delimiters will be
processed and used to generate documentation.
@raiph, I think you're correct about the great flexibility of the configuration keys, but I do think the docs could be clearer about them. I submit that the reader of our docs should not have to be experts on the totality of our huge language, especially elder members of our aging Raku community.
@tbrowder
I do think the docs could be clearer about them.
Sure.
I submit that the reader of our docs should not have to be experts on the totality of our huge language, especially elder members of our aging Raku community.
Sure.
What I'm not sure about is why you've written those two points.
I wasn't saying anything about those two points.
I was saying that afaik the configuration syntax for RakuDoc is either exactly the same as, or is exactly the same as a precise subset of, the argument list syntax of the main language.
Either I'm wrong, in which case I think it would be useful to nail down how I'm wrong, or I'm right, in which case we should do our best to not document this aspect by doing what amounts to a cut/paste (or worse) duplication of part of the doc, given how bad it is to do that.
I thought that by writing my comment I would help us toward fixing that part of the RakuDoc doc. I hope you have found my contribution useful!
On Thu, May 29, 2025 at 20:33 raiph @.***> wrote:
raiph left a comment (Raku/doc#4585) ... What I'm not sure about is why you've written those two points. I wasn't saying anything about those two points. I was saying that afaik the configuration syntax for RakuDoc is either exactly the same as, or is exactly the same as a precise subset of, the argument list syntax of the main language.
@raiph, you are right of course, but I haven't been able to pin that entire situation down in our current docs. I looked at them and found words about the export items are lists of "colon pairs" and they can be converted to a list by spaces. Actual usage then can be complicated with other ways to make a list with them.
I think the reason I didn't try to specify the several ways that are possible is that no one else then was very interested in pod and I just just stuck with something that worked without my complete understanding. I have looked again at many of the tests in roast and am not much wiser.
What do you think of saying something like this:
Configuration data are entered as a list of one or more colon pairs of
varying format. Lists of colon pairs are usually separated by whitespace,
similar to the use of export keys for module routines.
I thought that by writing my comment I would help us toward fixing that part. I hope you have found my contribution useful!
You have, and I appreciate it!
I'm not sure we should spend any more effort on what once was related to as Pod6.
But if one would like to spend time on that, I think it would get very confusing calling it RakuDoc v1. Yes, we've come up with a RakuDoc V2.0 definition. But most people who have worked with its previous incarnation, know it as Pod6. Renaming that now, feels like adding unnecessary confusion.
If documentation about RakuDoc needs to be improved, specifically about the explanation of specifying configurations, then I think that effort should be focused on that.
