Modules rewrite #4570

wayland · 2025-05-02T10:55:03Z

The problem

The module/package documentation was suboptimally organised, as per #3714

Solution provided

Organised documentation less suboptimally.

Things to note:

Put the first subdirectories under "Tutorials", specifically:
- Using Modules: How to use raku.land and zef to get modules to use in your projects
- Making Modules: How to code modules in your projects
- Making distributions: How to wrap your code up in a distribution
Each of those has a few pages in it. I'm not sure whether this was a good idea or not. Ideas I like are:
- More subdirectories (but upon what grounds?)
- Series of tutorials, rather than everything in doc/Language being standalone
Tweaked the Makefile (for ease of use and readability) and one of the tests (because otherwise it was hanging on that test; the outcome of the test should be unaffected though)

I'm expecting feedback on things I need to change.

Hope this helps.

wayland · 2025-05-02T10:57:01Z

I guess my main point is that it's better than it was before :) .

coke

Is there a curl option to hide the output instead?

coke

RAKULIB should be . (current directory's META6.json), not lib

finanalyst · 2025-05-02T12:23:05Z

This seems to be a good start. I absolutely agree the modules part needed restructuring.
We should also include something about documentation.

From the site building point of view, it does not matter which directory the files are placed, so long as the meta date at the top of the file (in the line with =begin rakudoc) matches existing categories. The pages (introduction, etc) that pull in the separate pages use the meta data.

Richard

wayland · 2025-05-02T12:48:26Z

@finanalyst :

Not sure what you mean by "We should also include something about documentation" unless you mean that we should have a page on documenting your distribution, in which case, I agree, but...
Nearly everything here is a copy-paste from somewhere else in the documentation (with the exception of some bits about $?DISTRIBUTION and %?RESOURCES). For context, my main role on Wikipedia seems to be to add headings to pages that don't have them, and that's functionally what I'm doing here: taking existing information and grouping it better.
- My hope is that, with the better grouping, and people being able to find things more easily, we'll also get more contributions, such as the one you suggested about documentation. I could put in a crosslink to the Rakudoc page, though

finanalyst · 2025-05-02T12:53:28Z

@wayland Ok understood that the main work currently is about regrouping, and that's definitely important.

I do mean a page on documenting a module. I agree more needs writing - its a TODO of mine.

wayland · 2025-05-02T21:45:24Z

Hi! I've made the following updates:

Added the --silent option to curl, which should at least reduce the amount of output
Changed RAKULIB, as requested
Added the following targets to the Makefile
- test-mine: Tests with just the appropriate git files
- xtest-mine: Like test-mine, but with xtest
- prep: Runs zef install

HTH,

ugexe · 2025-05-03T00:45:53Z

doc/Type/Distribution/Resource.rakudoc


-However, this is I<not> because it returns an L<C<IO::Path>|/type/IO::Path>, but because it
-shares many method with it: C<Str, gist, raku, absolute, is-absolute,
+However, this was found to be problematic due to the fact that the path can


I'm not sure it makes sense to talk about what why things are implemented the way they are in the docs e.g. "was found to be problematic". Someone looking at the docs presumably wants to know how to use something and not necessarily the history or implementation details.

OK, I've rewritten this section so that it:

Keeps most of the old material (but updates the deprecation list

Adds a paragraph on what not to do (which was what I was trying to achieve), but without listing the deprecated methods

Would very much appreciate your feedback, since I seem to get this wrong on the regular.

Thanks!

ugexe · 2025-05-03T00:47:15Z

doc/Type/Distribution/Resource.rakudoc

+get compiled into the library at compile time, which means that it can end
+up pointing to the wrong place at runtime.  Thus, many of the methods that
+were shared with L<C<IO::Path>|/type/IO::Path> are now deprecated; this
+includes C<Str, gist, raku, absolute, is-absolute,


If Str or gist is giving a deprecation message then that is a bug

I was looking at https://github.com/rakudo/rakudo/blob/b527cefcb29789120f32d5e4003913e53c47476f/src/core.c/Distribution/Resource.rakumod#L50 when compiling this list; was that incorrect?

I meant .raku or .gist aren’t deprecated

Oh! Right. Well, I've completely left them out this time around because

I wasn't sure of their status

They're not specific to mirroring IO::Path, they're on just about everything, so I figured they didn't need a mention.

HTH,

ugexe · 2025-05-03T00:49:09Z

doc/Type/Distribution/Resource.rakudoc

 relative, is-relative, parts, volume, dirname, basename, extension, open,
-resolve, slurp, lines, comb, split, words, copy>; above we use C<.lines>, for
-instance.
+resolve, slurp, lines, comb, split, words, copy>.


This list is not accurate. You can see the deprecations explicitly defined in the source. Notably slurp, lines, and other methods that don't return a string representation of a path or path part.

I also think listing all the deprecated methods is rather distracting, and that listing the methods that are actually allowed (similar to the original description) makes the most sense.

OK, I'll be rewriting this section in line with your recommendations.

Just my notes on the old version of the list as to what's still current and what isn't. I'm mainly posting it here for feedback on .gist and .raku (given that .Str is deprecated).

Deprecated: Str, absolute, is-absolute, resolve

Not sure: gist, raku

Still good: slurp, lines, comb, split, words, copy

Str is deprecated?

wayland · 2025-05-04T11:51:52Z

Also regularised use of subkind across the new pages (to "Modules").

wayland · 2025-05-23T07:55:23Z

Hi @ugexe , are you happy with this now?

wayland · 2025-07-18T22:24:39Z

Hi @ugexe , let me ask a different question: Can you have a look at your previous comments, and mark them "resolved" if you're satisfied with my changes?

Thanks!

ugexe · 2025-07-19T15:31:30Z

doc/Language/distributions/introduction.rakudoc

+names in all distributions available.
+
+Given this arrangement, the B<rakudo> compiler, or a package manager such as
+B<zef>, can obtain all the information needed about each C<compunit> from a


I think this PR is incorrectly using the term compunit in a lot of places. See this doc and note there are separate definitions for compunit and module. Many places this references compunit I would have expected module.

Thanks! Definitely the best explanation I've seen of the terms. I have:

Redone the doc to use "module" instead of "compunit"

Added some of the definitions from your link to the documentation.

ugexe · 2025-07-19T15:36:07Z

doc/Language/distributions/uploading.rakudoc

+Currently, there are three ways to distribute a module. No matter which method
+you choose, your module will be indexed on the L<raku.land|https://raku.land>
+and L<raku.land|https://raku.land> websites. The three module
+distribution networks, or ecosystems, are:


I'm not sure it is useful to mention anything other than the zef ecosystem, particularly in the context of a user "choosing" one. See https://github.com/Raku/problem-solving/blob/main/solutions/meta/sunsetting-p6c-cpan.md

OK, I was just copy-pasting what was elsewhere in the docs. I've removed references to CPAN and P6C.

Thanks!

wayland · 2025-07-25T10:40:33Z

Hi @ugexe ,

I've addressed your points, thanks very much.

Any more objections?

Thanks

coke · 2025-10-04T00:12:07Z

Hey, sorry I got very derailed in July (!) and lost track of a bunch of stuff. What’s left to get this merged?

coke · 2025-10-04T20:49:13Z

Please also (sorry!) resolve the conflicts.

Very sorry. Once that’s passed, would love to merge in next few days. Thanks!

coke

In general, content all looks great, I just have a few minor requests just added.

coke · 2025-05-02T12:15:41Z

doc/Language/distributions/introduction.rakudoc

@@ -0,0 +1,75 @@
+=begin pod :kind("Language") :subkind("Modules") :category("tutorial")
+
+=TITLE Distributions: An Introduction


As you know, xt/headings.rakutest is failing on most of these changes: I added some comments to the rakudoc overview on that test file on main that should help pass. This one should be

Distributions: an introduction

When you resubmit, you’ll see we’ve added some CI tests - please make sure those pass.

I didn't see any CI tests, but I made sure all the tests passed on my local.

doc/Language/distributions/configuration-structure.rakudoc

xt/01-raku-version.rakutest

doc/Language/variables.rakudoc

doc/Language/distributions/configuration-structure.rakudoc

CREDITS

Makefile

doc/Language/modules-extra.rakudoc

writing-docs/TESTING.md

xt/01-raku-version.rakutest

* Pulled out testlist variable to simplify later code * Move "if" statement from Bash to Makefile * Added RAKULIB=lib because it was failing without this for me

… On the downside, the output is uglier. On the upside, it doesn't hang.

- Removed references to P6C and CPAN - Changed compunit to module where appropriate

wayland · 2025-12-17T11:22:34Z

Hi @coke

How now?

:)

coke

partial review, didn’t go through everything.

coke · 2025-12-17T18:44:16Z

doc/Language/distributions/configuration-structure.rakudoc

+obligation to use it.
+
+Create a project directory named after your module. For
+    example, if your module is C<Vortex::TotalPerspective>, then create a


Accidental indent?

coke · 2025-12-17T19:12:10Z

doc/Language/distributions/testing.rakudoc

+the C<lib/> directory, then it is possible to use
+
+=for code :lang<shell>
+prove6 -Ilib


I would consider removing this whole section, or perhaps replace with just one sentence explanation that explains why the previous is better.

This is pre-existing (just moving stuff around).

coke · 2025-12-17T19:18:11Z

doc/Language/distributions/uploading.rakudoc

+There have been three ways to distribute a module, but the CPAN and P6C ways
+have been deprecated; please use the zef/fez method instead.  However, no
+matter the method, all modules will be indexed on the L<raku.land|https://raku.land> website.
+


Let’s not lead with history, but with the current standard; leave the history as the last (small) entry on the page.

coke · 2025-12-17T19:18:28Z

doc/Language/distributions/uploading.rakudoc

+If you want to use the I<zef> ecosystem then you need to register your username
+using I<fez>.
+
+=item Install fez if you haven't done so already


coke · 2025-12-17T19:21:57Z

doc/Language/using-modules/code.rakudoc

+
+You can combine C<EXPORT> with type captures for interesting effect. This
+example creates a C<?> postfix which will only work on L<C<Cool>|/type/Cool>s;
+please note that, by using C<$_> as an argument, we don't need to use a


Do we need to introduce the topic topic here?

This is pre-existing (just moving stuff around).

wayland · 2025-12-17T23:16:11Z

@coke do you mind if we keep this PR focussed on the existing changes, and not rewriting things that are just moving things around? What I'm worried about is that this will again get pushed on to the back burner by one of us, and then there will be more moerge conflicts to overcome, and it could take ... a long time. Really all I'm asking is permission to say "Let's not worry about that now" if it's sub-optimal, but a) pre-existing, and b) not actually wrong.

coke · 2025-12-17T23:27:02Z

Can you describe which stuff is new and which is just moved? That would help with the review.

wayland mentioned this pull request May 2, 2025

Module / Package documentation is structured suboptimally #3714

Open

coke self-assigned this May 2, 2025

coke requested changes May 2, 2025

View reviewed changes

coke assigned ugexe May 2, 2025

wayland requested a review from coke May 2, 2025 21:45

ugexe reviewed May 3, 2025

View reviewed changes

ugexe reviewed Jul 19, 2025

View reviewed changes

coke requested changes Oct 9, 2025

View reviewed changes

wayland added 7 commits December 17, 2025 11:31

Final doc changes

c54f234

Ignoring a couple more items

3548812

Changes:

1e728c2

* Pulled out testlist variable to simplify later code * Move "if" statement from Bash to Makefile * Added RAKULIB=lib because it was failing without this for me

Removed :err because it was causing hangs for me in the test process.…

6bce05d

… On the downside, the output is uglier. On the upside, it doesn't hang.

Requested changes to Makefile and curl call

90e8649

Added myself to CREDITS

07ad0e1

Adjusted paragraph in line with ugexe's recommendations

82e056a

wayland added 11 commits December 17, 2025 11:32

Added one more line from the old doco that I spotted

8ea5b1c

Removed deprecated code

e6194f1

Edited according to "make xtest"

89c5a0a

Regularised subkind

f193526

As per comments from @ugexe, I have:

b6721d3

- Removed references to P6C and CPAN - Changed compunit to module where appropriate

Fixes, mostly whitespace

ebcdd6c

Whitespace corrections

95fd884

Removed .precomp as requested by coke

321f5fc

Reverted changes to Makefile, as requested by coke

7917a7a

Changed "Moved to" to "See", as requested by coke

220d6ca

Changed "Moved to" to "See", as requested by coke

0100739

wayland force-pushed the modules-rewrite branch from ca92f0d to 0100739 Compare December 17, 2025 10:59

Reverted changes as requested by coke

04bbc55

coke requested changes Dec 17, 2025

View reviewed changes

		@@ -0,0 +1,75 @@
		=begin pod :kind("Language") :subkind("Modules") :category("tutorial")

		=TITLE Distributions: An Introduction

Modules rewrite #4570

Are you sure you want to change the base?

Modules rewrite #4570

Uh oh!

Conversation

wayland commented May 2, 2025

The problem

Solution provided

Uh oh!

wayland commented May 2, 2025

Uh oh!

coke left a comment

Choose a reason for hiding this comment

Uh oh!

coke left a comment

Choose a reason for hiding this comment

Uh oh!

finanalyst commented May 2, 2025

Uh oh!

wayland commented May 2, 2025

Uh oh!

finanalyst commented May 2, 2025

Uh oh!

wayland commented May 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ugexe May 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wayland commented May 4, 2025

Uh oh!

wayland commented May 23, 2025

Uh oh!

wayland commented Jul 18, 2025

Uh oh!

ugexe Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wayland commented Jul 25, 2025

Uh oh!

coke commented Oct 4, 2025

Uh oh!

coke commented Oct 4, 2025

Uh oh!

coke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ugexe May 3, 2025 •

edited

Loading

ugexe Jul 19, 2025 •

edited

Loading