Skip to content

Tidy up pages about modules#4796

Merged
arkiuat merged 6 commits intoRaku:mainfrom
schultzdavid:main
Mar 26, 2026
Merged

Tidy up pages about modules#4796
arkiuat merged 6 commits intoRaku:mainfrom
schultzdavid:main

Conversation

@schultzdavid
Copy link
Copy Markdown
Collaborator

@schultzdavid schultzdavid commented Mar 15, 2026

  • A number of links have become dead, probably through the great organization overhaul (PR 4570 in response to Module / Package documentation is structured suboptimally #3714). This should fix most if not all of them.

  • While looking at any individual page, it's hard to tell where it fits in the overall context, or where to find what one is looking for if it isn't there. That's why I've copied the overview section from the bottom of using-modules/introduction (with fixed links, of course) to every other page. That's the big block starting with =head1 Documentation about Modules added to the bottom of most files.

Furthermore, I have

  • added some cross-references where it seems useful
  • replicated the section about non-core testing tools from distributions/tools to distributions/testing
  • modified some page titles or subtitles to better fit the content

There's still a lot to do, but I'd like to get this "structure cleanup" merged first. It's good to go from my side.


Some Todos for later:

  • Put use first, above the more technical need, in using-modules/code, and add a section on import. In the section about require, briefly state how to a conditionally load a module into the right scope, along the lines of this SO question and e.g. raiph's reply.
  • Also in using-modules/code, at the bottom, keep only the parts about selective importing and introspection, while moving the contents about exporting to language/making-modules/code
  • Decide what to do with pages like language/module-packages and language/modules-extra, which consist merely of one or more links to other module pages. My preference would be to remove them altogether, in favor of making language/modules the single, polished table of contents for everything modules. (To keep old incoming links functional, use HTTP redirects wherever possible. Only for obsolete URLs with multiple successor documents should there be—at the website level, not the Rakudoc level, or at least well-distinguished from the actual documentation—pages with links to the several successor pages; these linklist pages should not, however, be referenced from within the Rakudocs and in particular not be listed on docs.raku.org/introduction—as is currently the case for the given two examples.)

Also, the alphabetic ordering of the index of Tutorials is suboptimal for the modules pages, since it makes the advanced topics Distributions and Making Modules come first and the beginner topics Using Modules at the end, with the beginner introduction page sitting very inconspicuously in the middle (using-modules/introduction, listed there as "Modules"). Also, I'd say that all the pages about modules (whatever their internal arrangement) are definitely worth their own subsection in or beside this Tutorials index.

@arkiuat arkiuat merged commit 4eb1cc1 into Raku:main Mar 26, 2026
1 check passed
@wayland
Copy link
Copy Markdown
Contributor

wayland commented Mar 28, 2026

@schultzdavid Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants