categories on language page

Author: finanalyst

.gitignore

@@ -29,3 +29,4 @@ highlights/package-lock.json
 .pod-cache
 retest
 build/
+notesOnInstalling.md

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,7 @@ 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 $first = $pod.contents[0];
     if $first ~~ Pod::Block::Named && $first.name eq "TITLE" {
         $name = $pod.contents[0].contents[0].contents[0];
@@ -319,6 +325,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];
     }
@@ -344,6 +359,7 @@ sub process-pod-source(:$kind, :$pod, :$filename, :$pod-is-complete) {
         :$summary,
         :$pod-is-complete,
         :subkinds($kind),
+        :$section,
         |%type-info,
     );
 
@@ -862,7 +878,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 +900,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 = {