Modules rewrite

[wayland]

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]

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]

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]

@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]

@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]

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]

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.

[wayland]

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]

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

[wayland]

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?

[ugexe]

I meant .raku or .gist aren’t deprecated

[wayland]

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

1. I wasn't sure of their status
2. 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]

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.

[wayland]

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

[wayland]

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