|
Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki Set by [Coke] on 23 May 2022. |
|||
| wayland | So, in the main channel arkuiat said "even better is the idea that if I can't figure out the doco, I should look at the tests!". My question is, should we be looking at having the reference doco for the classes/roles link to the tests as well (eg. at the bottom, just above the type diagram, or maybe in the sidebar)? | 00:04 | |
|
00:21
arkiuat joined
00:23
arkiuat left
01:44
wayland76 joined,
wayland left
|
|||
| wayland76 | Maybe also something that's just a (hyperlinked) list of all methods on parent classes, so that if someone comes to the reference doco for a class, they can search the page for the methods, and find something that links to the right place. | 04:30 | |
|
04:40
librasteve_ joined
|
|||
| librasteve_ | o/ | 04:41 | |
| wayland76 | o/ | 04:42 | |
| irclogs.raku.org/raku-doc/live.html for recent discussions :) | 04:43 | ||
| librasteve_ | backscrolling | 04:49 | |
| finanalyst: glad to hear you are back! | 04:51 | ||
| be great to do active iteration as a community on the new docs site | 04:54 | ||
| finanalyst: you able to finish the consolidation of Hilite to external module, it should be pretty straightforward and I think that the README on the module gives you most of what you need | 04:56 | ||
| wayland: I have some sympathy with adding links out to the ROAST from every doc page - many languages have a textual dry reference manual and a readable user manual main content that cross link the reference - I think our plan (?) is to have just ROAST (ie never a textual reference manual) and that rakudoc is a very comprehensive user manual that helps avoid any need for non devs to spelunk into ROAST. | 05:23 | ||
| > even better is the idea that if I can't figure out the doco, I should look at the tests! | |||
| ^^ with that in mind the solution has been “ok then, your familar enough to read a test file, please figure it out and add an explanation to the docs” | 05:24 | ||
| sounds like a hard job to winkle out all the cross refs to ROAST - important to get right too since a wholesale change must avoid bing patchy or incomplete | 05:26 | ||
| wayland76 | So the short version is that it's more difficult than I was hoping? | 05:27 | |
| (the idea about the methods on parent classes is a completely separate idea -- the only thing in common is that I think they both belong on the reference docs. | 05:28 | ||
| librasteve_ | rakudoc has a set of auto generation already and tbh I find the compound docs and navigation and search today is very confusing especially for newcomers … | ||
| I would like rakudoc v2 to be an improvement on usability current v1 | 05:30 | ||
| its not that I’m against just really aware of the changes we need to do to the gateway pages that you proposed over on GH since these are the first thing everyone sees and suggest we put our time into getting those knocked into shape so that the content for rakudoc v2 does not hold back the upgrade | 05:35 | ||
| [and thanks to you for lighting a fire under some of this - we can definitely up our game] | 05:37 | ||
| wayland76 | No worries :) | 05:45 | |
| Yeah, I'm thinking I'll jump onto some of that website stuff soonish, but I have an article on the Philosophy of Raku that I'm trying to finish. Which may turn into a series. | 05:54 | ||
|
09:00
librasteve_ left
15:51
arkiuat joined
|
|||
| arkiuat | just wanted to point out that the discussion about looking at roast tests started when I claimed that parametrized roles were tersely documented | 15:52 | |
|
17:57
arkiuat left
18:11
arkiuat joined
18:53
finanalyst joined
20:07
arkiuat left
20:20
arkiuat joined
20:25
arkiuat left
20:32
coleman left,
coleman joined
20:38
arkiuat joined
21:09
finanalyst left
21:43
wayland76 left
21:44
wayland76 joined
|
|||
| [Coke] | linking to roast from the docs has been floated in the past - it's a huge undertaking. | 23:06 | |
| It's also probably not as instructive as we'd hope. | 23:07 | ||
| tbrowder | Hi, continuing my mention of confusion with the docs description of routine 'split', I've put together a gist that I hope will show why I think the docs need one or more examples of a real use case. | 23:11 | |
| see <script src="gist.github.com/tbrowder/198b7c70d...script> | |||
| disregard that^^^. trying again | 23:12 | ||
| <script src="gist.github.com/tbrowder/198b7c70d...script> | 23:13 | ||
| dang! | |||
| Voldenet | IMO most of roast is just too detailed to be useful and pieces of code that are useful can be simply copied to docs without linking to it | 23:15 | |
| arkiuat | yes, it was surprisingly helpful for parametrized roles, but when I tried to learn more about "subset" syntax, the subset tests weren't nearly as helpful. at least not to me | 23:16 | |
| tbrowder | once more, someone kindly remind me which non-obvious-to-dufus selection to make on the github share gist page! | 23:18 | |
| Voldenet | > gist.github.com/tbrowder/198b7c70d...012fa122ab | ||
| without js | 23:19 | ||
| arkiuat | tbrowder, I just went to gist.github.com/tbrowder/ and I think it's right at the top there | ||
| tbrowder | Voldenet, thanks! | 23:20 | |
| arkiuat, thanks, i forget to go back to the page that shows my list of gists | 23:25 | ||
| Voldenet | for reference C# has split method similar to docs.raku.org/type/Str#routine_split | 23:30 | |
| but I'm not sure if the docs are better or worse learn.microsoft.com/en-us/dotnet/a...ring.split | |||
| I think it does better job explaining what RemoveEmptyEntries does | 23:31 | ||
| tbrowder | well, our docs dont | 23:32 | |
| Voldenet | current raku docs only show code snippets with outputs in "examples", so the reader is supposed to figure out what `:skip-empty` does from that | 23:33 | |
| tbrowder | *don't really address the effects of each option. i find it much easier to *always* use the :v option and then remove the odd list.kv key values before further handling | 23:35 | |
| Voldenet | raw `split(",")` is useful in cases where you have tsv/csv output and want empty spaces and no delimiters | 23:38 | |
| :v is more useful when you use multiple delimiters and want to act on them | 23:39 | ||
| tbrowder | as well, the existing delimeter, input order, imho, feels reversed from the gnu operation operand option order | ||
| Voldenet: agree, but my special uses are for those less standard uses. all my typical use cases are better tested and documented and improved and wrapped into my "split-line" routine in my next version of Text::Utils | 23:45 | ||
| as soon as i finish that, i'll finish my PR suggestion for the docs | 23:47 | ||
| Voldenet | `my @words = say "Text usually has punctuation. Getting rid of it can be useful, especially during per-word processing.".split((" ", ",", "."), :skip-empty).lc` something like that explains skip-empty fairly well imo | ||
| erm | 23:48 | ||
| `my @words = "Text usually has punctuation. Getting rid of it can be useful, especially during per-word processing.".split((" ", ",", "."), :skip-empty).lc` | |||
| parsing trivial configs can be described with it too | 23:51 | ||
| my @lines = "config".IO.slurp.split("\n", :skip-empty); for @lines.split(("=", " "), :skip-empty) -> $k, $v { say $k, $v } | 23:52 | ||
| it's not the best config format in the world, but it'd work as an example :) | 23:55 | ||