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.

* 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.

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!

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

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.

coke · 2025-05-02T13:10:56Z

doc/Language/distributions/configuration-structure.rakudoc

+
+...and then to use it in your code:
+
+=begin code


This code can't be compiled because it depends on a non-standard module. please add to the =begin directive here:

:skip-test<needs dummy module>

also, please remove the extra whitespace before TOP.

coke · 2025-05-02T13:12:49Z

xt/01-raku-version.rakutest


 {
-    my $web = run('curl', '-L', '-H', "Accept: application/vnd.github+json", '-H', "X-GitHub-Api-Version: 2022-11-28", "https://api.github.com/repos/rakudo/rakudo/releases?per_page=1", :out, :err);
+    my $web = run('curl', '-L', '-H', "Accept: application/vnd.github+json", '-H', "X-GitHub-Api-Version: 2022-11-28", "https://api.github.com/repos/rakudo/rakudo/releases?per_page=1", :out);


Add '-s' here to make the curl silent itself (without needing raku to grab the STDERR and ignore it)

coke · 2025-05-02T13:14:29Z

doc/Language/variables.rakudoc

 =begin code
 my $foo-IO = %?RESOURCES<images/foo.jpg>;          # gets an object you can slurp
-my $foo-IO = %?RESOURCES<images/foo.jpg>.absolute; # gets an absolute path to a file
+my $foo-IO = %?RESOURCES<images/foo.jpg>.absolute; # gets an absolute path to a file; deprecated


Does the deprecation in rakudo indicate when it will be removed?

coke · 2025-05-02T13:16:35Z

doc/Language/distributions/configuration-structure.rakudoc

+                # Just some error-checking code
+                if $resource !~~ Distribution::Resource {
+                        note "Could not find resource '$resource-filename' in distribution";
+                        say qx{ls -laF ; ls -laF resources ; cat META6.json};


Found by the aspell test - add 'laf' to xt/pws/code.pws - lowercase, and sorted -

xt/words.rakutest will test the PWS files

util/sort-words.raku will sort them (helpful when there's non ASCII involved, less so here)

coke · 2025-10-09T17:41:00Z

CREDITS


+N: Tim Nelson
+E: [email protected]
+


coke · 2025-10-09T17:41:17Z

Makefile

@@ -1,20 +1,34 @@
-.PHONY: test xtest push help
+.PHONY: test xtest push help test-mine xtest-mine


Shouldn’t be any changes to this file

coke · 2025-10-09T17:45:51Z

doc/Language/modules-extra.rakudoc

-or skeletons.
-
-=item L<Foo|https://raku.land/github:ugexe/Foo> A module with two distributions of different versions
+Moved to L<Making Modules: The Tools|/language/distributions/tools>


Instead of Moved to, say “See”, same in the other locations. Thanks

coke · 2025-10-09T17:46:15Z

writing-docs/TESTING.md


 Every commit should run a basic set of tests with `make xtest`. As of Feb 2023, we
-are updating our CI, so this is currently disabled. C<NOTE> The author tests in `xt/`
+are updating our CI, so this is currently disabled. **NOTE** The author tests in `xt/`


Good catch.

coke · 2025-10-09T17:46:59Z

xt/01-raku-version.rakutest

+    my $web = run(
+        'curl', '--silent', '-L', '-H', "Accept: application/vnd.github+json", '-H', "X-GitHub-Api-Version: 2022-11-28",
+            "https://api.github.com/repos/rakudo/rakudo/releases?per_page=1",
+        :out);


Probably should be in a separate PR, but this looks like a fine cleanup and can stay

wayland added 5 commits May 2, 2025 08:45

Final doc changes

83ef11a

Ignoring a couple more items

231f083

Changes:

77062f3

* 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.…

908d61f

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

Merge branch 'Raku:main' into modules-rewrite

a4cd652

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 added 3 commits May 3, 2025 07:34

Requested changes to Makefile and curl call

e7d9e6d

Merge branch 'Raku:main' into modules-rewrite

6e41bbd

Added myself to CREDITS

b1b36f0

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

ugexe reviewed May 3, 2025

View reviewed changes

wayland added 5 commits May 3, 2025 14:44

Adjusted paragraph in line with ugexe's recommendations

860010f

Added one more line from the old doco that I spotted

0d26977

Removed deprecated code

9fec3bb

Edited according to "make xtest"

b8acf22

Regularised subkind

60e86f5

ugexe reviewed Jul 19, 2025

View reviewed changes

As per comments from @ugexe, I have:

ca92f0d

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

coke requested changes Oct 9, 2025

View reviewed changes

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

		=TITLE Distributions: An Introduction

		@@ -1,20 +1,34 @@
		.PHONY: test xtest push help
		.PHONY: test xtest push help test-mine xtest-mine

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ugexe May 3, 2025 •

edited

Loading

ugexe Jul 19, 2025 •

edited

Loading