Skip to content

Commit 23fdf34

Browse files
theorytheory
committedFeb 22, 2024
Use headers for questions in the FAQ
As well as custom IDs in the MultiMarkdown syntax, instead of embedding HTML `<spans>`. This lets the IDs remain the same as before.
1 parent a4256ed commit 23fdf34

File tree

3 files changed

+270
-289
lines changed

3 files changed

+270
-289
lines changed
 

‎Changes

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ Revision history for Perl extension PGXN::Site
22

33
0.23.8
44
- Fixed formatting of the image and first paragraph of the /art page.
5+
- Updated the formatting of the FAQ to use headers for questions
6+
instead of definition lists and HTML `<span>`s for IDs.
57

68
0.23.7 2024-02-22T20:50:06Z
79
- Removed duplicate CC license image and link on the /art page.

‎lib/PGXN/Site/Locale/en/faq.html

+129-143
Original file line numberDiff line numberDiff line change
@@ -2,95 +2,86 @@ <h1 id="frequentlyaskedquestions">Frequently Asked Questions</h1>
22

33
<h2 id="releasingonpgxn">Releasing on PGXN</h2>
44

5-
<dl>
6-
<dt><span id="extension"></span></dt>
7-
<dt>WTF is an “extension”?</dt>
8-
<dd>An extension is a piece of software that adds functionality to PostgreSQL
5+
<h3 id="extension">WTF is an “extension”?</h3>
6+
7+
<p>An extension is a piece of software that adds functionality to PostgreSQL
98
itself. Examples are data types (<a href="https://www.postgresql.org/docs/current/citext.html">citext</a>, <a href="https://www.postgresql.org/docs/current/hstore.html">hstore</a>), utilities (<a href="https://www.postgresql.org/docs/current/dblink.html">dblink</a>,
109
<a href="https://pgxn.org/extension/pgtap">pgTAP</a>), and procedural languages (<a href="https://www.postgresql.org/docs/current/plperl.html">PL/Perl</a>, <a href="https://github.com/postgres-plr/plr">PL/R</a>), among others. See
11-
<a href="https://www.postgresql.org/docs/current/extend.html">Extending SQL</a> for details.</dd>
12-
13-
<dt><span id="allowed"></span></dt>
14-
<dt>What’s allowed to be released on PGXN?</dt>
15-
<dd>Open-source PostgreSQL extension release packages. The <a href="https://manager.pgxn.org/howto">How To</a> documents
16-
the contents of such packages. Following the <a href="https://www.cpan.org/misc/ZCAN.html">CPAN example</a>, “no commercial
17-
software of any kind, not even share/guilt/donateware, will be allowed…any
18-
other policy would be open to nitpicking, or maybe even legal challenges.”</dd>
19-
20-
<dt><span id="notallowed"></span></dt>
21-
<dt>What’s not allowed to be released on PGXN?</dt>
22-
<dd>Non-package files (that is, files that are not tarballs, bzip-balls, or zip
23-
archives), closed-source distributions, and distributions with no license.</dd>
24-
25-
<dt><span id="whocanrelease"></span></dt>
26-
<dt>Who can release on PGXN?</dt>
27-
<dd>Any registered user.</dd>
28-
29-
<dt><span id="whocanregister"></span></dt>
30-
<dt>Who can register for PGXN?</dt>
31-
<dd>Anyone who applies. Such registrations will be approved by volunteers, but
32-
we’re usually pretty quick to respond to requests.</dd>
33-
34-
<dt><span id="howtoapply"></span></dt>
35-
<dt>So how do I apply?</dt>
36-
<dd>Head on over to <a href="https://manager.pgxn.org/">PGXN Manager</a> and hit the “<a href="https://manager.pgxn.org/account/register">Request Account</a>” link. Once
37-
you’ve signed up, unless you’re obviously a <a href="https://en.wikipedia.org/wiki/Troll_(slang)">troll</a>, your account will be
38-
quickly approved.</dd>
39-
40-
<dt><span id="releaseapproval"></span></dt>
41-
<dt>Okay, I have an account and want to release an extension. Is there a release</dt>
42-
<dt>approval process?</dt>
43-
<dd>Short answer: No, because PGXN needs to <a href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a>. Longer answer: No. Again
10+
<a href="https://www.postgresql.org/docs/current/extend.html">Extending SQL</a> for details.</p>
11+
12+
<h3 id="allowed">What’s allowed to be released on PGXN?</h3>
13+
14+
<p>Open-source PostgreSQL extension release packages. The <a href="https://manager.pgxn.org/howto">How To</a> documents the
15+
contents of such packages. Following the <a href="https://www.cpan.org/misc/ZCAN.html">CPAN example</a>, “no commercial software
16+
of any kind, not even share/guilt/donateware, will be allowed…any other policy
17+
would be open to nitpicking, or maybe even legal challenges.”</p>
18+
19+
<h3 id="notallowed">What’s not allowed to be released on PGXN?</h3>
20+
21+
<p>Non-package files (that is, files that are not tarballs, bzip-balls, or zip
22+
archives), closed-source distributions, and distributions with no license.</p>
23+
24+
<h3 id="whocanrelease">Who can release on PGXN?</h3>
25+
26+
<p>Any registered user.</p>
27+
28+
<h3 id="whocanregister">Who can register for PGXN?</h3>
29+
30+
<p>Anyone who applies. Such registrations will be approved by volunteers, but we’re
31+
usually pretty quick to respond to requests.</p>
32+
33+
<h3 id="howtoapply">So how do I apply?</h3>
34+
35+
<p>Head on over to <a href="https://manager.pgxn.org/">PGXN Manager</a> and hit the “<a href="https://manager.pgxn.org/account/register">Request Account</a>” link. Once you’ve
36+
signed up, unless you’re obviously a <a href="https://en.wikipedia.org/wiki/Troll_(slang)">troll</a>, your account will be quickly
37+
approved.</p>
38+
39+
<h3 id="releaseapproval">Okay, I have an account and want to release an extension. Is there a release approval process?</h3>
40+
41+
<p>Short answer: No, because PGXN needs to <a href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a>. Longer answer: No. Again
4442
following the <a href="https://www.cpan.org/misc/ZCAN.html">CPAN example</a>, PGXN “is and will stay an open and free forum,
4543
where the authors decide what they upload. Any further selection belongs to
46-
different fora.” This is because “the first goal of PGXN is to make it easy
47-
to submit code and redistribute it. Ease of use and quality control are not
48-
the central problems ~[it~] tries to solve.” (Original quotation lost to
49-
time and internet entropy.) Frankly, moderation of releases is a significant
50-
reason that other communities have failed to duplicate the success of CPAN.</dd>
51-
52-
<dt><span id="howto"></span></dt>
53-
<dt>Great, so how do I create an extension distribution and release it?</dt>
54-
<dd>Basically, you upload an archive file with a <a href="https://pgxn.org/spec/">META.json</a> file describing the
55-
distribution. Have a look at the <a href="https://manager.pgxn.org/howto">How To</a> for all the details.</dd>
56-
57-
<dt><span id="github"></span></dt>
58-
<dt>I read that, but it seems like an awful lot of work for something that should be</dt>
59-
<dt>automated. Is there any way I can automatically have my extension appear on PGXN</dt>
60-
<dt>when I make a release on GitHub?</dt>
61-
<dd><p>Yes! You can use the <a href="https://github.com/pgxn/docker-pgxn-tools">pgxn-tools</a> Docker image as part of your release
44+
different fora.” This is because “the first goal of PGXN is to make it easy to
45+
submit code and redistribute it. Ease of use and quality control are not the
46+
central problems ~[it~] tries to solve.” (Original quotation lost to time and
47+
internet entropy.) Frankly, moderation of releases is a significant reason that
48+
other communities have failed to duplicate the success of CPAN.</p>
49+
50+
<h3 id="howto">Great, so how do I create an extension distribution and release it?</h3>
51+
52+
<p>Basically, you upload an archive file with a <a href="https://pgxn.org/spec/">META.json</a> file describing the
53+
distribution. Have a look at the <a href="https://manager.pgxn.org/howto">How To</a> for all the details.</p>
54+
55+
<h3 id="github">I read that, but it seems like an awful lot of work for something that should be automated. Is there any way I can automatically have my extension appear on PGXN when I make a release on GitHub?</h3>
56+
57+
<p>Yes! You can use the <a href="https://github.com/pgxn/docker-pgxn-tools">pgxn-tools</a> Docker image as part of your release
6258
workflows. It supports both testing an extension with multiple versions of
63-
Postgres, as well as releasing extensions on GitHub and PGXN. For details,
64-
check out these blog posts:</p>
59+
Postgres, as well as releasing extensions on GitHub and PGXN. For details, check
60+
out these blog posts:</p>
6561

6662
<ul>
6763
<li><a href="https://justatheory.com/2020/06/test-extensions-with-github-actions/">Test Postgres Extensions With GitHub Actions</a></li>
6864
<li><a href="https://justatheory.com/2020/10/release-postgres-extensions-with-github-actions/">Automate Postgres Extension Releases on GitHub and PGXN</a></li>
69-
</ul></dd>
70-
71-
<dt><span id="maillist"></dt>
72-
<dt>Is there some place I can go to ask questions and get help from like-minded PGXN</dt>
73-
<dt>contributors?</dt>
74-
<dd>Yes, there is a <a href="https://groups.google.com/group/pgxn-users">Google Group</a> for this very purpose. Join us!</dd>
75-
76-
<dt><span id="goodbadugly"></span></dt>
77-
<dt>How does PGXN make it easy to distinguish the garbage from the viable</dt>
78-
<dt>extensions?</dt>
79-
<dd>The first step is the PGXN search engine, accessible via the <a href="https://pgxn.org/">home page</a>,
80-
which will allow you to find extensions relevant to you and to read their
81-
documentation. This will “often ~[be~] enough to distinguish the good stuff
82-
from the crap,” as <a href="https://www.postgresql.org/message-id/603c8f071001061718t40e42609y59a26165bb72ff01@mail.gmail.com">Robert Haas says</a>. As more extensions are released on
83-
PGXN with competing features and functionality, the addition of ratings
84-
features and dedicated testing will also make it easier to evaluate
85-
competing options.</dd>
86-
</dl>
65+
</ul>
66+
67+
<h3 id="maillist">Is there some place I can go to ask questions and get help from like-minded PGXN contributors?</h3>
68+
69+
<p>Yes, there is a <a href="https://groups.google.com/group/pgxn-users">Google Group</a> for this very purpose. Join us!</p>
70+
71+
<h3 id="goodbadugly">How does PGXN make it easy to distinguish the garbage from the viable extensions?</h3>
72+
73+
<p>The first step is the PGXN search engine, accessible via the <a href="https://pgxn.org/">home page</a>, which
74+
will allow you to find extensions relevant to you and to read their
75+
documentation. This will “often ~[be~] enough to distinguish the good stuff from
76+
the crap,” as <a href="https://www.postgresql.org/message-id/603c8f071001061718t40e42609y59a26165bb72ff01@mail.gmail.com">Robert Haas says</a>. As more extensions are released on PGXN with
77+
competing features and functionality, the addition of ratings features and
78+
dedicated testing will also make it easier to evaluate competing options.</p>
8779

8880
<h2 id="pgxnclient">PGXN Client</h2>
8981

90-
<dl>
91-
<dt><span id="commandlineclient"></span></dt>
92-
<dt>Is there a command-line client for installing extensions from PGXN?</dt>
93-
<dd><p>There is! Install it with this command:</p>
82+
<h3 id="commandlineclient">Is there a command-line client for installing extensions from PGXN?</h3>
83+
84+
<p>There is! Install it with this command:</p>
9485

9586
<pre><code class="sh">sudo easy_install pgxnclient
9687
</code></pre>
@@ -107,73 +98,68 @@ <h2 id="pgxnclient">PGXN Client</h2>
10798

10899
<p>Run <code>pgxn help</code> to get a list of supported commands; or check out the
109100
introductory <a href="https://blog.pgxn.org/post/5026314153/writing-a-client-for-pgxn">blog</a> <a href="https://blog.pgxn.org/post/5118152273/new-release-for-the-pgxn-client">posts</a>, the <a href="https://pgxn.github.io/pgxnclient/">complete documentation</a> or the <a href="https://github.com/pgxn/pgxnclient">source
110-
code</a>.</p></dd>
111-
112-
<dt><span id="howclientworks"></span></dt>
113-
<dt>How does the command-line client work?</dt>
114-
<dd>It uses JSON-based API available on every PGXN mirror to find, download,
115-
build, and install extensions. It relies on <a href="https://www.postgresql.org/docs/current/extend-pgxs.html">PGXS</a> to do the heavy lifting
116-
to build extensions.</dd>
117-
118-
<dt><span id="clientwindows"></span></dt>
119-
<dt>What about Windows?</dt>
120-
<dd>The PGXN client follows the lead of the PostgreSQL core on installing
121-
extensions. If support for installing extensions on Windows improves such
122-
that a compiler is no longer required, the PGXN client will be modified as
123-
appropriate to take advantage of it. This applies not specifically to
124-
Windows, but to the ability of the core installer (or any future
125-
community-supported installer) to work on <em>any</em> platform.</dd>
126-
127-
<dt><span id="clientsecurity"></span></dt>
128-
<dt>What kind of security does PGXN have?</dt>
129-
<dd>Each release package has an accompanying SHA1 hash that the PGXN client
130-
verifies before installing an extension.</dd>
131-
</dl>
101+
code</a>.</p>
102+
103+
<h3 id="howclientworks">How does the command-line client work?</h3>
104+
105+
<p>It uses JSON-based API available on every PGXN mirror to find, download, build,
106+
and install extensions. It relies on <a href="https://www.postgresql.org/docs/current/extend-pgxs.html">PGXS</a> to do the heavy lifting to build
107+
extensions.</p>
108+
109+
<h3 id="clientwindows">What about Windows?</h3>
110+
111+
<p>The PGXN client follows the lead of the PostgreSQL core on installing
112+
extensions. If support for installing extensions on Windows improves such that a
113+
compiler is no longer required, the PGXN client will be modified as appropriate
114+
to take advantage of it. This applies not specifically to Windows, but to the
115+
ability of the core installer (or any future community-supported installer) to
116+
work on <em>any</em> platform.</p>
117+
118+
<h3 id="clientsecurity">What kind of security does PGXN have?</h3>
119+
120+
<p>Each release package has an accompanying SHA1 hash that the PGXN client verifies
121+
before installing an extension.</p>
132122

133123
<h2 id="contributingtopgxn">Contributing to PGXN</h2>
134124

135-
<dl>
136-
<dt><span id="license"></span></dt>
137-
<dt>Under what license is PGXN’s source code distributed?</dt>
138-
<dd><a href="https://www.postgresql.org/about/licence/">The PostgreSQL License</a>. Note that the actual extensions themselves may be
139-
under any open source license, determined by their authors.</dd>
140-
141-
<dt><span id="contribute"></span></dt>
142-
<dt>Can other people contribute to PGXN?</dt>
143-
<dd>Definitely! Contributions and help with refining the specification are very
144-
welcome. Major code contributions may be funded out of the PGXN fund based
145-
on circumstances. Any contributions must be submitted under The PostgreSQL
146-
License.</dd>
147-
148-
<dt><span id="mirroring"></span></dt>
149-
<dt>What about mirroring? Can I create a PGXN mirror?</dt>
150-
<dd>Absolutely! See <a href="https://pgxn.org/mirroring/">mirroring</a> for the details.</dd>
151-
152-
<dt><span id="owners"></span></dt>
153-
<dt>Who owns and runs PGXN?</dt>
154-
<dd>Currently, PGXN is hosted on a box owned by <a href="https://www.depesz.com">depesz</a>. Eventually it may run
155-
on community servers, as the PostgreSQL.org Web Team determines. Or it may
156-
end up on one or more servers to be contributed to the <a href="https://www.postgresql.org/about/policies/funds-group/">PostgreSQL Funds
157-
Group</a>. In any case, the PGXN master index and server will always be
158-
contributed to the PostgreSQL community.</dd>
159-
160-
<dt><span id="source"></span></dt>
161-
<dt>Where is the PGXN source code hosted?</dt>
162-
<dd><a href="https://github.com/pgxn/">On GitHub</a>. Please feel free to fork and send pull requests!</dd>
163-
164-
<dt><span id="language"></span></dt>
165-
<dt>What language is PGXN written in?</dt>
166-
<dd>Mostly Perl. The database used by <a href="https://manager.pgxn.org/">PGXN Manager</a> is written in SQL,
167-
PL/pgSQL, and PL/Perl — and even uses <a href="https://pgxn.org/extension/semver">semver</a>, a <a href="https://semver.org/">semantic version</a> data
168-
type written in C and distributed right here on PGXN!</dd>
169-
170-
<dt><span id="api"></span></dt>
171-
<dt>Is there an API?</dt>
172-
<dd>Yes! The <a href="https://github.com/pgxn/pgxn-api/wiki/">PGXN API</a> provides centralized index and API of distribution
173-
metadata, as well as the search APIs used here.</dd>
174-
175-
<dt><span id="logos"></span></dt>
176-
<dt>Is the PGXN logo available for use?</dt>
177-
<dd>Yes, see <a href="https://pgxn.org/art/">identity</a> for the license details and downloadable artwork.</dd>
178-
</dl>
125+
<h3 id="license">Under what license is PGXN’s source code distributed?</h3>
126+
127+
<p><a href="https://www.postgresql.org/about/licence/">The PostgreSQL License</a>. Note that the actual extensions themselves may be
128+
under any open source license, determined by their authors.</p>
129+
130+
<h3 id="contribute">Can other people contribute to PGXN?</h3>
131+
132+
<p>Definitely! Contributions and help with refining the specification are very
133+
welcome. Major code contributions may be funded out of the PGXN fund based on
134+
circumstances. Any contributions must be submitted under The PostgreSQL License.</p>
135+
136+
<h3 id="mirroring">What about mirroring? Can I create a PGXN mirror?</h3>
137+
138+
<p>Absolutely! See <a href="https://pgxn.org/mirroring/">mirroring</a> for the details.</p>
139+
140+
<h3 id="owners">Who owns and runs PGXN?</h3>
141+
142+
<p>Currently, PGXN is hosted on a box owned by <a href="https://www.depesz.com">depesz</a>. Eventually it may run on
143+
community servers, as the PostgreSQL.org Web Team determines. Or it may end up
144+
on one or more servers to be contributed to the <a href="https://www.postgresql.org/about/policies/funds-group/">PostgreSQL Funds Group</a>. In any
145+
case, the PGXN master index and server will always be contributed to the
146+
PostgreSQL community.</p>
147+
148+
<h3 id="source">Where is the PGXN source code hosted?</h3>
149+
150+
<p><a href="https://github.com/pgxn/">On GitHub</a>. Please feel free to fork and send pull requests!</p>
151+
152+
<h3 id="language">What language is PGXN written in?</h3>
153+
154+
<p>Mostly Perl. The database used by <a href="https://manager.pgxn.org/">PGXN Manager</a> is written in SQL, PL/pgSQL,
155+
and PL/Perl — and even uses <a href="https://pgxn.org/extension/semver">semver</a>, a <a href="https://semver.org/">semantic version</a> data type written in
156+
C and distributed right here on PGXN!</p>
157+
158+
<h3 id="api">Is there an API?</h3>
159+
160+
<p>Yes! The <a href="https://github.com/pgxn/pgxn-api/wiki/">PGXN API</a> provides centralized index and API of distribution metadata,
161+
as well as the search APIs used here.</p>
162+
163+
<h3 id="logos">Is the PGXN logo available for use?</h3>
179164

165+
<p>Yes, see <a href="https://pgxn.org/art/">identity</a> for the license details and downloadable artwork.</p>

0 commit comments

Comments
 (0)