Modules rewrite

[wayland]

The problem

The module/package documentation was suboptimally organised, as per https://github.com/Raku/doc/issues/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 :) .

[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,

[wayland]

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

[wayland]

Hi @ugexe , are you happy with this now?

[wayland]

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!

[wayland]

Hi @ugexe ,

I've addressed your points, thanks very much.

Any more objections?

Thanks

[coke]

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

[coke]

Please also (sorry!) resolve the conflicts.

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