Parse and format Multimarkdown at release time

Instead of shipping the .mmd files, ship .html files generated by the `multimarkdown` CLI. Requires a bit of tweaking of the markdown files, but allows the use of fenced code blocks and eliminates a build-time dependency. Also tweak the CSS to open up some space in definition lists, though not in the meta section of a distribution page. Looks nicer, and should be easier to read.
pgxn · Feb 21, 2024 · a65227d · a65227d
1 parent be978d5
commit a65227d
Show file tree

Hide file tree

Showing 13 changed files with 474 additions and 93 deletions.
diff --git a/Build.PL b/Build.PL
@@ -6,32 +6,6 @@ my $class = Module::Build->subclass(
     class => 'PGXN::Build',
     code => q{
         sub valid_licenses { { postgresql => 'PostgreSQL' } }
-        sub process_mmd_files {
-            require Text::MultiMarkdown;
-            my $self  = shift;
-            my $m     = Text::MultiMarkdown->new(
-                img_ids     => 0,
-                heading_ids => 0,
-            );
-            my $files = $self->_find_file_by_type('mmd', 'lib');
-
-            while (my ($file, $to) = each %$files) {
-                $to =~ s{[.]mmd$}{.html};
-                $to = File::Spec->catfile($self->blib, $to);
-                unless ($self->up_to_date( $file, $to )) {
-                    File::Path::mkpath(File::Basename::dirname($to), 0, oct(777));
-                    $self->log_verbose("Converting $file -> $to\n");
-                    open my $in,  '<:utf8', $file or die "Cannot open $file: $!\n";
-                    chmod 0666, $to;
-                    open my $out, '>:utf8', $to   or die "Cannot open $to: $!\n";
-                    local $/;
-                    print $out $m->markdown(<$in>);
-                    close $in;
-                    chmod 0444, $to;
-
-                }
-            }
-        }
         sub ACTION_tarball_name { print shift->dist_dir . ".tar.gz\n" }
         sub ACTION_latest_changes {
             my $self = shift;
@@ -60,10 +34,6 @@ my $build = $class->new(
     license            => 'postgresql',
     script_files       => 'bin',
     configure_requires => { 'Module::Build' => '0.4209' },
-    build_requires     => {
-        'Module::Build'       => '0.4209',
-        'Text::MultiMarkdown' => 0,
-    },
     requires => {
         'Carp'                         => 0,
         'Data::Dump'                   => '1.17',
@@ -121,5 +91,5 @@ my $build = $class->new(
     },
 );
 
-$build->add_build_element($_) for qw(css gif png jpg js mmd eps svg json ico);
+$build->add_build_element($_) for qw(css gif png jpg js html eps svg json ico);
 $build->create_build_script;
diff --git a/Changes b/Changes
@@ -2,6 +2,11 @@ Revision history for Perl extension PGXN::Site
 
 0.23.7
       - Removed duplicate CC license image and link on the /art page.
+      - Moved the generation of HTML from Multimarkdown files from build
+        time to release time, and switched from Text::Multimarkdown to
+        the `multimarkdown` CLI.
+      - Tweaked the CSS for definition lists to open up space a bit more
+        between terms and definitions.
 
 0.23.6 2024-02-20T20:56:52Z
       - Tweaked the indentation of list items in the documentation "Contents"

diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP
@@ -5,7 +5,7 @@
 \B\.svn\b
 \B\.git
 
-# Avoid Makemaker generated and utility files.
+# Avoid MakeMaker generated and utility files.
 \bMakefile$
 \bblib
 \bMakeMaker-\d
@@ -30,6 +30,7 @@
 ^Capfile
 ^www
 ^assets
+^bin/format_l10n_docs
 
 # Avoid Pod tests.
 t/pod.+

diff --git a/bin/format_l10n_docs b/bin/format_l10n_docs
@@ -0,0 +1,24 @@
+#!/usr/bin/env perl -w
+
+# Find all .mm?d files in lib, run them through multimarkdown, and write
+# to .html.
+#
+# brew install multimarkdown
+
+use 5.10.0;
+use strict;
+use warnings;
+use utf8;
+use File::Find;
+use File::Basename qw(basename);
+
+find({
+    no_chdir => 1,
+    wanted => sub {
+        return unless /\.mm?d$/;
+        my $src = $File::Find::name;
+        my $dst = $src =~ s/\.mm?d$/.html/r;
+        my @cmd = ('multimarkdown', $src, '-o', $dst);
+        system(@cmd) == 0  or die "system @cmd failed: $?\n"
+    },
+}, 'lib');
diff --git a/lib/PGXN/Site/Locale/en/about.html b/lib/PGXN/Site/Locale/en/about.html
@@ -0,0 +1,71 @@
+<h1 id="aboutpgxn">About PGXN</h1>
+
+<p>PGXN, the PostgreSQL Extension network, is a central distribution system for
+open-source PostgreSQL extension libraries. It consists of four basic parts:</p>
+
+<dl>
+<dt><a href="https://manager.pgxn.org/">PGXN Manager</a></dt>
+<dd>An upload and distribution infrastructure for extension developers.</dd>
+
+<dt><a href="https://github.com/pgxn/pgxn-api/wiki/">PGXN API</a></dt>
+<dd>A centralized index and API of distribution metadata.</dd>
+
+<dt><a href="https://pgxn.org/">PGXN Search</a></dt>
+<dd>This site, for searching extensions and perusing their documentation.</dd>
+
+<dt><a href="https://pgxn.github.io/pgxnclient/">PGXN Client</a></dt>
+<dd>A command-line client for downloading, testing, and installing extensions.</dd>
+</dl>
+
+<p>The network currently consists of:</p>
+
+<ul>
+<li>[_1] Extensions</li>
+<li>[_2] Distributions</li>
+<li>[_3] Releases</li>
+<li>[_4] Users</li>
+<li>[_5] Tags</li>
+<li>[_6] Mirrors</li>
+</ul>
+
+<h3 id="why">Why?</h3>
+
+<p>One of the primary distinguishing features of <a href="https://www.postgresql.org/">PostgreSQL</a>—and perhaps the
+number one reason to use it instead of another DBMS—is its extensibility and the
+large number of database extensions already available: <a href="https://postgis.net/">PostGIS</a>, <a href="https://www.postgresql.org/docs/current/isn.html">ISN</a>,
+<a href="https://www.postgresql.org/docs/current/hstore.html">hstore</a>, <a href="https://pgtap.org/">pgTAP</a>, <a href="https://github.com/postgres-plr/plr">PL/R</a>, <a href="https://plproxy.github.io">PL/Proxy</a>, and more. Especially with the formal
+support for <a href="https://www.postgresql.org/docs/current/extend-extensions.html" title="PostgreSQL Documentation: “Packaging Related Objects into an Extension”">extensions</a>, PostgreSQL today is not merely a database, it’s an
+application development platform. However, many of these extensions are
+virtually unknown even among experienced users because they are hard to find.</p>
+
+<p>PGXN solves the “hard to find” issue by providing centralized listings and
+searchable documentation for PostgreSQL extensions. Here you can easily search
+through extensions, browse their documentation, and download and install those
+that fill your needs. The site is structured to maximize the ability to find
+appropriate extensions and their documentation through search engines. Our hope
+is that the high visibility of PostgreSQL’s extensibility and the array of
+available extensions will drive PostgreSQL adoption by new users and application
+developers, expanding our community and ensuring another 10 years of the
+PostgreSQL Project.</p>
+
+<h3 id="who’sresponsibleforthis">Who’s Responsible for This?</h3>
+
+<p>Thanks to our <a href="https://pgxn.org/donors/">terrific donors</a>, <a href="https://justatheory.com/" title="Just a Theory">I am</a>. I’m David Wheeler, inveterate Perl and
+PostgreSQL hacker. I love the <a href="https://www.postgresql.org/docs/current/static/extend.html" title="PostgreSQL Documentation: Extending SQL”">extensibility of PostgreSQL</a> and have long been a
+fan of <a href="https://www.cpan.org/">CPAN</a>, the Perl community’s distributed collection of Perl software and
+documentation. But PostgreSQL’s extensibility is not well-known, and it’s
+difficult to find the extensions that do exist. PGXN is my attempt to solve that
+problem.</p>
+
+<h3 id="wanttohelp">Want to Help?</h3>
+
+<p>The source code for all the parts of PGXN are on <a href="https://github.com/pgxn/" title="PGXN on GitHub">GitHub</a>. Please feel free to
+fork and send merge requests! And join the discussion in the <a href="https://groups.google.com/group/pgxn-users" title="PGXN Users Group">Google Group</a>.</p>
+
+<h3 id="colophon">Colophon</h3>
+
+<p>The pgxn.org design is based on <a href="https://fullahead.org/projects/lazydays/">LazyDays</a> by <a href="https://fullahead.org/">Fullahead</a>, set in
+<a href="https://docs.microsoft.com/en-us/typography/font-list/trebuchet-ms">Trebuchet MS</a>, and features icons by <a href="https://icons8.github.io/flat-color-icons/" title="Flat Color Icons by Icons8">Icons8</a>. Strongrrl designed the
+<a href="https://pgxn.org/art/">graphic identity</a>.</p>
+
+<p>This site eschews JavaScript, and uses no tracking or analytics services.</p>
diff --git a/lib/PGXN/Site/Locale/en/art.html b/lib/PGXN/Site/Locale/en/art.html
@@ -0,0 +1,48 @@
+<h1 id="pgxngraphicidentity">PGXN Graphic Identity</h1>
+
+<figure>
+<img src="https://licensebuttons.net/l/by/4.0/88x31.png" alt="Creative Commons License" />
+<figcaption>Creative Commons License</figcaption>
+</figure>
+
+<a rel="license" href="https://creativecommons.org/licenses/by/4.0/">
+<img alt="Creative Commons License" src="https://licensebuttons.net/l/by/4.0/88x31.png" />
+</a>
+<br />
+The <span xmlns:dct="https://purl.org/dc/terms/" href="https://purl.org/dc/dcmitype/StillImage" property="dct:title" rel="dct:type">PGXN Graphic Identity</span>
+by <a xmlns:cc="https://creativecommons.org/ns" href="https://justatheory.com/" property="cc:attributionName" rel="cc:attributionURL">David E. Wheeler</a>,
+including the type treatments of the word "PGXN" and the phrase "PostgreSQL
+Extension Network", as well as the gear logo, is licensed under a
+<a rel="license" href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
+Based on a work at <a xmlns:dct="https://purl.org/dc/terms/" href="https://pgxn.org/art/" rel="dct:source">pgxn.org</a>.
+Design by Strongrrl.
+
+<h3 id="logotype">Logo Type</h3>
+
+<ul>
+<li>The text &#8220;PGXN&#8221; is composed in
+<a href="https://www.myfonts.com/collections/bank-gothic-font-bitstream">Bank Gothic BT</a></li>
+<li>The text &#8220;PostgreSQL Extension Network&#8221; is rendered in
+<a href="https://www.myfonts.com/collections/myriad-font-adobe">Myriad</a> 215 LT condensed</li>
+</ul>
+
+<h3 id="logoart">Logo Art</h3>
+
+<ul>
+<li>PGXN Logo Type:
+<a href="/ui/img/pgxn.eps">EPS</a> |
+<a href="/ui/img/pgxn.svg">SVG</a> |
+<a href="/ui/img/pgxn.png">PNG</a></li>
+<li>PGXN Logo White Gear:
+<a href="/ui/img/gear.eps">EPS</a> |
+<a href="/ui/img/gear.svg">SVG</a> |
+<a href="/ui/img/gear-512.png">PNG</a></li>
+<li>PGXN Logo White Gear on Blue:
+<a href="/ui/img/icon.eps">EPS</a> |
+<a href="/ui/img/icon.svg">SVG</a> |
+<a href="/ui/img/icon-512.png">PNG</a></li>
+<li>PGXN Logo Black Gear:
+<a href="/ui/img/gear-black.eps">EPS</a> |
+<a href="/ui/img/gear-black.svg">SVG</a> |
+<a href="/ui/img/gear-black-512.png">PNG</a></li>
+</ul>