user/dev discussion of public-inbox itself
 help / color / Atom feed
From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH] doc: add public-inbox.cgi(1) manpage
Date: Sat,  2 Nov 2019 21:51:08 +0000
Message-ID: <20191102215108.1102-1-e@80x24.org> (raw)

Yet another case of documenting things which should NOT be used :>
---
 Documentation/.gitignore           |  1 +
 Documentation/include.mk           |  1 +
 Documentation/public-inbox.cgi.pod | 34 ++++++++++++++++++++++++++++++
 MANIFEST                           |  1 +
 4 files changed, 37 insertions(+)
 create mode 100644 Documentation/public-inbox.cgi.pod

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 4d2ca22..f26169a 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -1,3 +1,4 @@
 /public-inbox-*.txt
+/public-inbox.cgi.txt
 /standards.txt
 /.x
diff --git a/Documentation/include.mk b/Documentation/include.mk
index fd2c95f..e948778 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -37,6 +37,7 @@ podtext = $(PODTEXT) $(PODTEXT_OPTS)
 m1 =
 m1 += public-inbox-compact
 m1 += public-inbox-convert
+m1 += public-inbox.cgi
 m1 += public-inbox-edit
 m1 += public-inbox-httpd
 m1 += public-inbox-index
diff --git a/Documentation/public-inbox.cgi.pod b/Documentation/public-inbox.cgi.pod
new file mode 100644
index 0000000..01187d8
--- /dev/null
+++ b/Documentation/public-inbox.cgi.pod
@@ -0,0 +1,34 @@
+=head1 NAME
+
+public-inbox.cgi - CGI wrapper for PublicInbox::WWW
+
+=head1 SYNOPSIS
+
+You generally want to run public-inbox-httpd, instead
+
+=head1 DESCRIPTION
+
+public-inbox.cgi provides a CGI interface wrapper on top of the
+PSGI/Plack L<PublicInbox::WWW> module.  It is only provided for
+compatibility reasons and NOT recommended.
+
+CGI with Perl is slow due to code loading overhead and web servers lack
+the scheduling fairness of L<public-inbox-httpd(1)> for handling git
+clones and streaming large mbox downloads.
+
+=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
+
+The mail archives are hosted at L<https://public-inbox.org/meta/>
+and L<http://hjrcffqmbrq6wope.onion/meta/>
+
+=head1 COPYRIGHT
+
+Copyright 2019 all contributors L<mailto:meta@public-inbox.org>
+
+License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<public-inbox-httpd(1)>, L<PublicInbox::WWW>, L<public-inbox-daemon(8)>,
diff --git a/MANIFEST b/MANIFEST
index 9582642..dac096e 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -31,6 +31,7 @@ Documentation/public-inbox-v1-format.pod
 Documentation/public-inbox-v2-format.pod
 Documentation/public-inbox-watch.pod
 Documentation/public-inbox-xcpdb.pod
+Documentation/public-inbox.cgi.pod
 Documentation/standards.perl
 Documentation/txt2pre
 HACKING

                 reply index

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://public-inbox.org/README

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191102215108.1102-1-e@80x24.org \
    --to=e@80x24.org \
    --cc=meta@public-inbox.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

user/dev discussion of public-inbox itself

Archives are clonable:
	git clone --mirror https://public-inbox.org/meta
	git clone --mirror http://czquwvybam4bgbro.onion/meta
	git clone --mirror http://hjrcffqmbrq6wope.onion/meta
	git clone --mirror http://ou63pmih66umazou.onion/meta

Example config snippet for mirrors

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta
	nntp://ou63pmih66umazou.onion/inbox.comp.mail.public-inbox.meta
	nntp://czquwvybam4bgbro.onion/inbox.comp.mail.public-inbox.meta
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.mail.public-inbox.meta
	nntp://news.gmane.org/gmane.mail.public-inbox.general

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git