Language page categories

Makefile

@@ -7,6 +7,8 @@ COLON_Z              := :Z
 SELINUX_OPT          := $(shell [ $(DOCKER_SELINUX_LABEL) -eq 1 ] && echo "$(COLON_Z)" || echo '' )
 # dependencies for a new doc/Language build:
 LANG_POD6_SOURCE     := $(wildcard doc/Language/*.pod6)
+# set to True if the language index page is to be managed
+USE_CATEGORIES := False
 
 .PHONY: html init-highlights html-nohighlight sparse assets webdev-build \
 	bigpage test xtest ctest help run clean-html clean-images \
@@ -17,10 +19,10 @@ LANG_POD6_SOURCE     := $(wildcard doc/Language/*.pod6)
 html: gen-pod6-source bigpage htmlify
 
 htmlify: gen-pod6-source init-highlights assets
-	perl6 htmlify.p6
+	perl6 htmlify.p6 --manage=$(USE_CATEGORIES)
 
 gen-pod6-source: $(LANG_POD6_SOURCE) doc/Language/00-POD6-CONTROL
-	perl6 util/manage-page-order.p6 update
+	perl6 util/manage-page-order.p6 update --manage=$(USE_CATEGORIES)
 
 init-highlights:
 	ATOMDIR="./highlights/atom-language-perl6";  \

doc/Language/00-POD6-CONTROL

@@ -3,7 +3,9 @@
 #
 # DO NOT REMOVE OR MODIFY THE FILE NAME AT THE END OF EACH LINE
 
+section: AT THE BEGINNING
 
+Brief Introduction FILE: intro
 Perl 6 Example P6-101 FILE: 101-basics
 
 section: MIGRATION GUIDES

doc/Language/intro.pod6

@@ -0,0 +1,46 @@
+=begin pod
+
+=TITLE Brief Introduction
+
+=SUBTITLE Using the Perl6 Documentation
+
+Documenting a large language like Perl6 has to balance several contradictory goals, such as being brief
+whilst being comprehensive, catering to professional developers with wide experience whilst also being accessible to
+newcomers to the language.
+
+For a quick hands-on introduction, there is a short L<C<annotated programming example>|/language/101-basics>.
+
+For programmers with experience in other languages, there are a number of B<Migration> guides that compare and
+contrast the features of Perl6 with other languages.
+
+A number of B<Tutorials> cover several areas in which Perl6 is particularly innovative. The section headers should help navigate
+the remaining documents.
+
+There are a number of L<C<useful resources>|https://perl6.org/resources> listed elsewhere on the perl6.org site.
+These include articles, books, slide presentations, and videos.
+
+It has been found that newcommers to Perl6 often ask questions that indicate assumptions carried over from other
+programming paradigms. It is suggested that the following sections in the FUNDAMENTAL TOPICS section
+should be reviewed first.
+
+=item L<C<Signatures>|/type/Signature> - each routine, which includes subroutines and methods, has a signature.
+Understanding the information given in the signature of a C<sub> or C<method> provides a quick way to
+grasp the operation and effect of the routine.
+
+=item L<C<Containers>|/language/containers> - variables, which are like the nouns of a computer language, are
+containers in which information is stored. The first letter in the formal
+name of a container, such as the '$' of $my-variable, or '@' of @an-array-of-things, or '%' of %the-scores-in-the-competition,
+conveys information about the container. However, Perl6 is more abstract than other languages about what can be stored
+in a container. So, for example, a $scaler container can contain an object that is in fact an array.
+
+=item L<C<Classes and Roles>|/language/classtut> - Perl6 is fundamentally based on objects, which are described
+in terms of classes and roles. Perl6, unlike some languages, does not
+B<impose> object-oriented programming practices, and useful programs can be written as if Perl6 was purely procedural in
+nature. However, complex software, such as the Perl6 compiler itself, is made much simpler by writing in object-oriented idioms,
+which is why the Perl6 documentation is more easily understood by reviewing what a class is and what a role is. Without understanding
+about Classes and Roles, it would be difficult to understand Types, to which a whole section of the documentation is devoted.
+
+=item L<C<Traps to Avoid>|/language/traps> - Several common assumptions lead to code that does not work
+as the programmer intended. This section identifies some. It is worth reviewing when something doesn't quite work out.
+
+=end pod

htmlify.p6

@@ -178,6 +178,7 @@ sub MAIN(
     Bool :$search-file = True,
     Bool :$no-highlight = False,
     Int  :$parallel = 1,
+    Bool :$manage = False,
 ) {
     if !$no-highlight {
         if ! $coffee-exe.IO.f {
@@ -215,19 +216,22 @@ sub MAIN(
         spurt "html{$doc.url}.html",
             p2h($doc.pod, 'programs', pod-path => $pod-path);
     }
+
     for $*DR.lookup("language", :by<kind>).list -> $doc {
         say "Writing language document for {$doc.name} ...";
         my $pod-path = pod-path-from-url($doc.url);
         spurt "html{$doc.url}.html",
             p2h($doc.pod, 'language', pod-path => $pod-path);
     }
+
     for $*DR.lookup("type", :by<kind>).list {
         write-type-source $_;
     }
 
+
     write-disambiguation-files if $disambiguation;
     write-search-file          if $search-file;
-    write-index-files;
+    write-index-files($manage);
 
     for (set(<routine syntax>) (&) set($*DR.get-kinds)).keys -> $kind {
         write-kind $kind;
@@ -239,6 +243,7 @@ sub MAIN(
     }
 
     spurt('links.txt', $url-log.URLS.sort.unique.join("\n"));
+
 }
 
 sub process-pod-dir(:$topdir, :$dir, :&sorted-by = &[cmp], :$sparse, :$parallel) {
@@ -309,6 +314,8 @@ sub process-pod-dir(:$topdir, :$dir, :&sorted-by = &[cmp], :$sparse, :$parallel)
 sub process-pod-source(:$kind, :$pod, :$filename, :$pod-is-complete) {
     my $summary = '';
     my $name = $filename;
+    my Bool $section = ($pod.config<class>:exists and $pod.config<class> eq 'section-start');
+    my Str $link = $pod.config<link> // $filename;
     my $first = $pod.contents[0];
     if $first ~~ Pod::Block::Named && $first.name eq "TITLE" {
         $name = $pod.contents[0].contents[0].contents[0];
@@ -319,6 +326,15 @@ sub process-pod-source(:$kind, :$pod, :$filename, :$pod-is-complete) {
     else {
         note "$filename does not have a =TITLE";
     }
+    if $first ~~ Pod::Block::Named && $first.name eq "TITLE" {
+        $name = $pod.contents[0].contents[0].contents[0];
+        if $kind eq "type" {
+            $name = $name.split(/\s+/)[*-1];
+        }
+    }
+    else {
+        note "$filename does not have a =TITLE";
+    }
     if $pod.contents[1] ~~ {$_ ~~ Pod::Block::Named and .name eq "SUBTITLE"} {
         $summary = $pod.contents[1].contents[0].contents[0];
     }
@@ -340,10 +356,11 @@ sub process-pod-source(:$kind, :$pod, :$filename, :$pod-is-complete) {
         :$kind,
         :$name,
         :$pod,
-        :url("/$kind/$filename"),
+        :url("/$kind/$link"),
         :$summary,
         :$pod-is-complete,
         :subkinds($kind),
+        :$section,
         |%type-info,
     );
 
@@ -862,7 +879,7 @@ sub write-disambiguation-files() {
     say '';
 }
 
-sub write-index-files() {
+sub write-index-files($manage) {
     say 'Writing html/index.html and html/404.html...';
     spurt 'html/index.html',
         p2h(extract-pod('doc/HomePage.pod6'),
@@ -884,14 +901,40 @@ sub write-index-files() {
 
     # sort language index by file name to allow author control of order
     say 'Writing html/language.html ...';
-    spurt 'html/language.html', p2h(pod-with-title(
-        'Perl 6 Language Documentation',
-        pod-block("Tutorials, general reference, migration guides and meta pages for the Perl 6 language."),
-        pod-table($*DR.lookup('language', :by<kind>).map({[
+    if $manage {
+        my @p-chunks;
+        my @end;
+        for $*DR.lookup('language', :by<kind>).list {
+            if .section {
+                @p-chunks.push( pod-table(@end.map({[
+                    pod-link(.name, .url),
+                    .summary
+                ]})) ) if +@end;
+                @p-chunks.push: pod-heading( .name, :level(2) );
+                @end = ();
+            } else {
+                @end.push: $_;
+            }
+        }
+        @p-chunks.push( pod-table(@end.map({[
             pod-link(.name, .url),
             .summary
-        ]}))
-    ), 'language');
+            ]})) ) if +@end;
+        spurt 'html/language.html', p2h(pod-with-title(
+            'Perl 6 Language Documentation',
+            pod-block("Tutorials, general reference, migration guides and meta pages for the Perl 6 language."),
+            @p-chunks
+        ), 'language');
+    } else {
+        spurt 'html/language.html', p2h(pod-with-title(
+            'Perl 6 Language Documentation',
+            pod-block("Tutorials, general reference, migration guides and meta pages for the Perl 6 language."),
+            pod-table($*DR.lookup('language', :by<kind>).map({[
+                pod-link(.name, .url),
+                .summary
+            ]}))
+        ), 'language');
+    }
 
     my &summary;
     &summary = {

lib/Perl6/Documentable.pm6

@@ -1,7 +1,7 @@
 use URI::Escape;
 class Perl6::Documentable {
     has Str $.kind;        # type, language doc, routine, module
-    has Str $.section;     # for Language doc list breakdown by sections
+    has Bool $.section;     # for Language doc list breakdown by sections
     has Str @.subkinds;    # class/role/enum, sub/method, prefix/infix/...
     has Str @.categories;  # basic type, exception, operator...
 

util/manage-page-order.p6

@@ -30,13 +30,14 @@ constant $TITLE    = '=TITLE';
 constant $SUBTITLE = '=SUBTITLE';
 constant $NBSPACE  = "\x[A0]";
 
-my $usage = "Usage: $*PROGRAM-NAME update | control [--debug --help]";
+my $usage = "Usage: $*PROGRAM-NAME update [--manage ] | control [--debug --help]";
 sub USAGE { say $usage }
 my %*SUB-MAIN-OPTS = named-anywhere => 1;
 unit sub MAIN(
     $mode = '',
     Bool :d(:$debug)   = False,
     Bool :h(:$help)    = False,
+    Bool :m(:$manage) = False,
     # special options for control:
     Bool :r(:$refresh) = False,
     Bool :n(:$new)     = False,
@@ -51,11 +52,13 @@ given $mode {
         do-control();
     }
     when /^u/ {
-        =begin comment
         EXIT("Options 'refresh' and 'new' are not used with 'update'.")
             if ($new || $refresh);
-        =end comment
-        do-update();
+        if $manage {
+            do-update()
+        } else {
+            copy-dir-tree :fromdir('doc'), :todir('build')
+        };
     }
     default {
         EXIT("\$mode '$mode' is unknown");
@@ -67,23 +70,20 @@ sub do-update () {
 
     # FIRST
     # write the auto-generated pod6 files used for the Language page
-    =begin comment
+
     # visit later
     write-Language-files();
-    =end comment
 
     # THEN
     # copy all under the doc dir to the build dir
     # NOTE this assumes the sort order is alpha by file name
     # NOTE we exclude the Language dir
-    =begin comment
     # visit later
     copy-dir-tree(:fromdir('doc'), :todir('build'), :exclude('Language'));
-    =end comment
-    copy-dir-tree :fromdir('doc'), :todir('build');
+    #copy-dir-tree :fromdir('doc'), :todir('build');
 }
 
-sub copy-dir-tree(:$fromdir, :$todir, :$exclude) {
+sub copy-dir-tree(:$fromdir, :$todir, :$exclude = '' ) {
     # recursively copy tree to another tree
     return if !$fromdir.IO.d;
 
@@ -142,7 +142,7 @@ sub write-Language-files() {
         next if $line !~~ /\S/;
 
         # line may be a group line or a pod6 data line
-        if $line ~~ /:i ^ \h* 'group:' (.*) / {
+        if $line ~~ /:i ^ \h* 'section:' (.*) / {
             # a new group
             my $group-char = shift @a;
 
@@ -188,7 +188,7 @@ sub write-Language-files() {
                     else {
                         #$fh.say: "$line :page-order<{$page-order}>";
                         $fh.say: "# THIS FILE IS AUTO-GENERATED--ALL EDITS WILL BE LOST";
-                        $fh.say: $line;
+                        $fh.say: $line ~ " :link<$key-fname>";
                         #$fh.say: "=comment THIS FILE IS AUTO-GENERATED--ALL EDITS WILL BE LOST";
                     }
                     next;
@@ -450,6 +450,7 @@ sub help {
         -n      - create  (for mode 'control')
         -h      - extended help
         -d      - debug
+        -m    - manage (include the categories)
 
     Note: The modes are selected by entering either the first letter
           of the mode name or its complete name.
@@ -472,7 +473,7 @@ sub write-group-page($group-char, $title, $page-order) {
     # note no SUBTITLE
     $fh.print: qq:to/HERE/;
         # THIS FILE IS AUTO-GENERATED--ALL EDITS WILL BE LOST
-        =begin pod
+        =begin pod :class<section-start>
         =TITLE $title
         =SUBTITLE ~
         =end pod