Merge branch 'doc-reorg'

Author: AlexDaniel

Makefile

@@ -9,15 +9,16 @@ SELINUX_OPT          := $(shell [ $(DOCKER_SELINUX_LABEL) -eq 1 ] && echo "$(COL
 .PHONY: html init-highlights html-nohighlight sparse assets webdev-build \
 	bigpage test xtest ctest help run clean-html clean-images \
 	clean-search clean test-links push \
+        gen-pod6-source clean-build \
 	docker-image docker-htmlify docker-test docker-xtest docker-ctest docker-testall docker-run
 
-html: bigpage htmlify
+html: gen-pod6-source bigpage htmlify
 
-htmlify: init-highlights assets gen-pod6-source
+htmlify: init-highlights assets
 	perl6 htmlify.p6
 
 gen-pod6-source:
-	perl6 manage-page-order.p6 update
+	perl6 util/manage-page-order.p6 update
 
 init-highlights:
 	ATOMDIR="./highlights/atom-language-perl6";  \
@@ -38,7 +39,7 @@ webdev-build:
 	perl6 htmlify.p6 --no-highlight --sparse=200
 
 bigpage:
-	pod2onepage --html -v --source-path=./doc --exclude=404.pod6 > html/perl6.html
+	pod2onepage --html -v --source-path=./build --exclude=404.pod6 > html/perl6.html
 
 # Common tests that are run by travis with every commit
 test:
@@ -75,6 +76,8 @@ help:
 	@echo "docker-testall:      run all tests (in container)"
 	@echo "docker-run:          run the development webserver (in container)"
 
+start: run
+
 run:
 	@echo "Starting local server…"
 	./app-start
@@ -121,6 +124,9 @@ clean-images:
 clean-search:
 	rm -f html/js/search.js
 
+clean-build:
+	find build -name "*.pod6" -exec rm -f {} \;
+
 clean: clean-html clean-images clean-search
 
 distclean: clean

doc/Language/0-html-source/README

@@ -195,9 +195,9 @@ sub MAIN(
     my %h = $type-graph.sorted.kv.flat.reverse;
     write-type-graph-images(:force($typegraph), :$parallel);
 
-    process-pod-dir 'Programs', :$sparse, :$parallel;
-    process-pod-dir 'Language', :$sparse, :$parallel;
-    process-pod-dir 'Type', :sorted-by{ %h{.key} // -1 }, :$sparse, :$parallel;
+    process-pod-dir :topdir('build'), :dir('Programs'), :$sparse, :$parallel;
+    process-pod-dir :topdir('build'), :dir('Language'), :$sparse, :$parallel;
+    process-pod-dir :topdir('build'), :dir('Type'), :sorted-by{ %h{.key} // -1 }, :$sparse, :$parallel;
 
     highlight-code-blocks unless $no-highlight;
 
@@ -236,8 +236,9 @@ sub MAIN(
     spurt('links.txt', $url-log.URLS.sort.unique.join("\n"));
 }
 
-sub process-pod-dir($dir, :&sorted-by = &[cmp], :$sparse, :$parallel) {
-    say "Reading doc/$dir ...";
+sub process-pod-dir(:$topdir, :$dir, :&sorted-by = &[cmp], :$sparse, :$parallel) {
+    #say "Reading doc/$dir ...";
+    say "Reading $topdir/$dir ...";
 
     # What does this array look like?
     #
@@ -251,35 +252,27 @@ sub process-pod-dir($dir, :&sorted-by = &[cmp], :$sparse, :$parallel) {
     #     value: filename relative to the "doc/$dir" directory
     my @pod-sources;
 
-    if $dir eq 'Language' {
-        # uses a special sort order by :page-order<id> as a %config hash entry
-        # TODO treat the Programs directory the same way
-        # use the target files auto-generated:
-        @pod-sources = get-pod6-page-order(:dir("$dir/0-html-source"));
-    }
-    else {
-        # default sort is by name {%hash{.key} => file basename w/o extension
-        @pod-sources =
-            recursive-dir("doc/$dir/")
-            .grep({.path ~~ / '.pod6' $/})
-            .map({
-                .path.subst("doc/$dir/", '')
-                     .subst(rx{\.pod6$},  '')
-                     .subst(:g,    '/',  '::')
-                 => $_
+    # default sort is by name {%hash{.key} => file basename w/o extension
+    @pod-sources =
+    recursive-dir("$topdir/$dir/")
+        .grep({.path ~~ / '.pod6' $/})
+        .map({
+               .path.subst("$topdir/$dir/", '')
+               .subst(rx{\.pod6$},  '')
+               .subst(:g,    '/',  '::')
+               => $_
             }).sort(&sorted-by);
-     }
 
     =begin comment
     # PLEASE LEAVE THIS DEBUG CODE IN UNTIL WE'RE HAPPY
     # WITH LANGUAGE PAGE SORTING AND DISPLAY
-    if 0 && $dir eq 'Language' {
+    #if 1 && $dir eq 'Language' {
     #if 1 && $dir eq 'Programs' {
         say "\@pod-sources:";
         for @pod-sources.kv -> $num, (:key($filename), :value($file)) {
             say "num: $num; key: |$filename|; value : |$file|";
         }
-        #die "debug exit";
+        die "debug exit";
     }
     =end comment
 
@@ -288,7 +281,7 @@ sub process-pod-dir($dir, :&sorted-by = &[cmp], :$sparse, :$parallel) {
         @pod-sources = @pod-sources[^(@pod-sources / $sparse).ceiling];
     }
 
-    say "Processing $dir Pod files ...";
+    say "Processing $topdir/$dir Pod files ...";
     my $total = +@pod-sources;
     my $kind  = $dir.lc;
     for @pod-sources.kv -> $num, (:key($filename), :value($file)) {

htmlify.p6

@@ -127,56 +127,4 @@ sub get-page-order-value($fname) is export {
     return $sortid;
 }
 
-#| Return an array of pod6 page file name data sorted by :page-order value
-sub get-pod6-page-order(:$dir) is export {
-    # caller: process-pod-dir
-    #
-    # Return the .pod6 files found in $dir with :page-order values
-    # as an array of pairs of file basename (stripped of 'pod6')
-    # as key, and file names (relative to 'doc') as values.
-    # The array of such pairs is sorted in :page-order value
-    # alphabetical order.
-    #
-    # Note any .pod6 not having a :page-order entry is not
-    # included in the outout array.
-    #
-    # An exception is thrown if a duplicate :page-order key is found.
-    #
-
-    my $d = "doc/$dir";
-    die "FATAL: '$d' is NOT a known directory'" if !$d.IO.d;
-
-    my %h;
-    for (dir $d) -> $f {
-        next if !$f.IO.f;
-        next if $f !~~ /'.pod6' $/;
-
-        my $sortid = get-page-order-value $f;
-        next if !$sortid;
-
-        # the sortid must be unique for each file in this directory
-        die "FATAL: Duplicate :page-order key '$sortid' in file '$f'"
-            if %h{$sortid};
-
-        my $key = $f.basename;
-        # remove the pod6 extension
-        $key ~~ s/'.pod6'//;
-        my $value = $f;
-        # pack it all up
-        %h{$sortid} = ($key, $value);
-    }
-
-    # turn the hash into a sorted array
-    my @keys = %h.keys.sort;
-    my @arr;
-    # TODO below can be improved after all else is satisfactory
-    for @keys -> $k {
-        my @a = @(%h{$k});
-        my $hk = @a.shift;
-        my $hv = @a.shift;
-        push @arr, ($hk => $hv);
-    }
-    return @arr;
-}
-
 # vim: expandtab shiftwidth=4 ft=perl6