* [ANNOUNCE] ssoma 0.2.0 - a bunch of updates
@ 2016-03-03 3:45 6% Eric Wong
0 siblings, 0 replies; 3+ results
From: Eric Wong @ 2016-03-03 3:45 UTC (permalink / raw)
To: meta
Most notably, this release fixes a potential bug where a ssoma
repository could be confused by MIME encoding in Message-ID headers.
While I have not seen any Message-ID with MIME encoding; this is a
potential attack vector to confuse message identification between
different implementations of ssoma.
There's also a bunch of minor improvements since 0.1.0 which was
released nearly 2 years ago:
26 changes since 0.1.0:
ssoma: cleanup IMAP password warnings
doc: remove HTML
cleanup whitespace stripping
disable case-insensitive option parsing
Documentation/txt2pre: support #fragments and ftp://
doc: generate README.html instead of index.html
set author info on git commits
Ssoma::Git: hoist out ensure_sha1 function
ssoma-mda: Use the email subject as the commit message
INSTALL: add missing reference to IPC::Run
.gitignore: relax MYMETA pattern
ssoma_repository: document header usage/removal
mda: strip out the Bytes header, too
ssoma-rm: do not commit changes on auto-removal miss
README: add OpenSSL exception
use Perl POD instead of pandoc-flavored Markdown
doc: fix links to AGPL-3.0+ documentation
doc: use links for our public email address
documentation build fixes
t/*.t: quiet down "git init"
t/: try to ensure test output is stable
t/*: use identifiable tempdir names
copyright updates for 2016
use Email::MIME::Header::header_raw to read Message-ID
move scripts to script/ directory
build: make syntax check target
---
INSTALL | 2 +-
Makefile.PL | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/INSTALL b/INSTALL
index d907ea3..72affff 100644
--- a/INSTALL
+++ b/INSTALL
@@ -12,7 +12,7 @@ downloading
ssoma is available via git and tarballs.
The latest tarball release is available here:
- http://ssoma.public-inbox.org/files/ssoma-0.1.0.tar.gz
+ http://ssoma.public-inbox.org/files/ssoma-0.2.0.tar.gz
You may also clone using git:
diff --git a/Makefile.PL b/Makefile.PL
index 2a7a6e7..bbf784d 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -12,7 +12,7 @@ $PM_FILES =~ tr/\n/ /;
WriteMakefile(
NAME => 'ssoma',
- VERSION => '0.1.0',
+ VERSION => '0.2.0',
AUTHOR => 'Eric Wong <e@80x24.org>',
ABSTRACT => 'some sort of mail archiver',
EXE_FILES => \@EXE_FILES,
--
EW
^ permalink raw reply related [relevance 6%]
* [PATCH ssoma] use Perl POD instead of pandoc-flavored Markdown
@ 2016-01-11 2:34 2% Eric Wong
0 siblings, 0 replies; 3+ results
From: Eric Wong @ 2016-01-11 2:34 UTC (permalink / raw)
To: meta; +Cc: Eric Wong
This project is currently implemented in Perl, and pod2man is
probably more common among potential users and developers of
this project.
---
Documentation/.gitignore | 1 +
Documentation/include.mk | 33 +++--
Documentation/{ssoma-mda.txt => ssoma-mda.pod} | 50 ++++---
Documentation/{ssoma-rm.txt => ssoma-rm.pod} | 27 ++--
Documentation/{ssoma.txt => ssoma.pod} | 77 ++++++-----
.../{ssoma_repository.txt => ssoma_repository.pod} | 151 +++++++++++++--------
MANIFEST | 8 +-
7 files changed, 208 insertions(+), 139 deletions(-)
create mode 100644 Documentation/.gitignore
rename Documentation/{ssoma-mda.txt => ssoma-mda.pod} (37%)
rename Documentation/{ssoma-rm.txt => ssoma-rm.pod} (53%)
rename Documentation/{ssoma.txt => ssoma.pod} (62%)
rename Documentation/{ssoma_repository.txt => ssoma_repository.pod} (59%)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..2211df6
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1 @@
+*.txt
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 993522e..319be35 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# Copyright (C) 2013-2016 all contributors <meta@public-inbox.org>
# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
all::
@@ -6,9 +6,12 @@ RSYNC = rsync
RSYNC_DEST = ssoma.public-inbox.org:/srv/ssoma/
docs := README COPYING INSTALL $(shell git ls-files 'Documentation/*.txt')
INSTALL = install
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
+POD2MAN = pod2man
+POD2MAN_OPTS = -v --stderr -d 1994-10-02 -c 'public-inbox user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
m1 =
m1 += ssoma
@@ -18,12 +21,24 @@ m1 += ssoma-rm
m5 =
m5 += ssoma_repository
-m7 =
-
man1 := $(addsuffix .1, $(m1))
man5 := $(addsuffix .5, $(m5))
man7 := $(addsuffix .7, $(m7))
+%.1 : Documentation/%.pod
+ $(pod2man) -s 1 $< $@+ && mv $@+ $@
+
+%.5 : Documentation/%.pod
+ $(pod2man) -s 5 $< $@+ && mv $@+ $@
+
+mantxt = $(addprefix Documentation/, $(addsuffix .txt, $(m1)))
+docs += $(mantxt)
+
+all :: $(mantxt)
+
+Documentation/%.txt : Documentation/%.pod
+ $(pod2text) $< $@+ && mv $@+ $@
+
all:: man html
man: $(man1) $(man5) $(man7)
@@ -41,8 +56,6 @@ install-man: man
test -z "$(man1)" || $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
test -z "$(man5)" || $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
-%.1 %.5 %.7 : Documentation/%.txt
- $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
txt2pre = ./Documentation/txt2pre < $< > $@+ && touch -r $< $@+ && mv $@+ $@
txt = INSTALL README COPYING
@@ -65,4 +78,6 @@ rsync-doc:
$(MAKE) gz-doc
$(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(RSYNC_DEST)
clean-doc:
- $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html)
+ $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html) $(mantxt)
+
+clean :: clean-doc
diff --git a/Documentation/ssoma-mda.txt b/Documentation/ssoma-mda.pod
similarity index 37%
rename from Documentation/ssoma-mda.txt
rename to Documentation/ssoma-mda.pod
index 3b6757b..b9f4392 100644
--- a/Documentation/ssoma-mda.txt
+++ b/Documentation/ssoma-mda.pod
@@ -1,17 +1,17 @@
% ssoma-mda(1) ssoma user manual
-# NAME
+=head1 NAME
ssoma-mda - mail delivery agent for ssoma
-# SYNOPSIS
+=head1 SYNOPSIS
-ssoma-mda [-1] /path/to/ssoma/repository.git < message
+B<ssoma-mda> [-1] /path/to/ssoma/repository.git E<lt> message
-# DESCRIPTION
+=head1 DESCRIPTION
ssoma-mda delivers messages to a git repository as described by
-ssoma_repository(5). It reads messages from STDIN and takes no
+L<ssoma_repository(5)>. It reads messages from STDIN and takes no
command-line arguments. It may be invoked by the MTA (mail transport
agent, e.g. postfix or exim) or as part of another MDA (e.g. procmail or
maildrop)
@@ -20,31 +20,39 @@ ssoma-mda takes no command-line options and does not alter its own
permissions. This must be done by the MTA or MDA which invokes
ssoma-mda.
-# OPTIONS
+=head1 OPTIONS
--1
-: Only allow a Message-ID to appear once in the database.
- Future messages with an identical Message-ID will not be allowed.
+=over 8
-# FILES
+=item -1
-See ssoma_repository(5) for details.
+Only allow a Message-ID to appear once in the database.
+Future messages with an identical Message-ID will not be allowed.
-# ENVIRONMENT
+=back
+
+=head1 FILES
+
+See L<ssoma_repository(5)> for details.
+
+=head1 ENVIRONMENT
ssoma-mda depends on no environment variables
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to E<lt>meta@public-inbox.orgE<gt>
+
+The mail archives are hosted at L<git://public-inbox.org/meta>
+
+See L<ssoma(1)> for instructions on how to subscribe.
-All feedback welcome via plain-text mail to <meta@public-inbox.org>\
-The mail archives are hosted at git://public-inbox.org/meta
-See ssoma(1) for instructions on how to subscribe.
+=head1 COPYRIGHT
-# COPYRIGHT
+Copyright 2013-2016 all contributors E<lt>meta@public-inbox.orgE<gt>
-Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
-License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>
+License: AGPL-3.0+ E<lt>http://www.gnu.org/licenses/agpl-3.0.txtE<gt>
-# SEE ALSO
+=head1 SEE ALSO
-git(1), ssoma(1), ssoma_repository(5)
+L<git(1)>, L<ssoma(1)>, L<ssoma_repository(5)>
diff --git a/Documentation/ssoma-rm.txt b/Documentation/ssoma-rm.pod
similarity index 53%
rename from Documentation/ssoma-rm.txt
rename to Documentation/ssoma-rm.pod
index 0e3aa2b..45a5ac6 100644
--- a/Documentation/ssoma-rm.txt
+++ b/Documentation/ssoma-rm.pod
@@ -1,14 +1,14 @@
% ssoma-rm(1) ssoma user manual
-# NAME
+=head1 NAME
ssoma-rm - remove messages from a ssoma repository
-# SYNOPSIS
+=head1 SYNOPSIS
-ssoma-rm /path/to/ssoma/repository.git < message
+ssoma-rm /path/to/ssoma/repository.git E<lt> message
-# DESCRIPTION
+=head1 DESCRIPTION
ssoma-rm removes messages from a ssoma repository. It only deletes
messages which match the Message-ID, Subject, and body of the email.
@@ -17,17 +17,20 @@ works on the latest HEAD (refs/heads/master) of the ssoma repository.
It does not remove the message from history, but prevents future users
of "ssoma sync" from seeing the message in their mailbox.
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to E<lt>meta@public-inbox.orgE<gt>
+
+The mail archives are hosted at L<git://public-inbox.org/meta>
-All feedback welcome via plain-text mail to <meta@public-inbox.org>\
-The mail archives are hosted at git://public-inbox.org/meta
See ssoma(1) for instructions on how to subscribe.
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<lt>meta@public-inbox.orgE<gt>
-Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
-License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>
+License: AGPL-3.0+ E<lt>http://www.gnu.org/licenses/agpl-3.0.txtE<gt>
-# SEE ALSO
+=head1 SEE ALSO
-git(1), ssoma(1), ssoma_repository(5)
+L<git(1)>, L<ssoma(1)>, L<ssoma_repository(5)>
diff --git a/Documentation/ssoma.txt b/Documentation/ssoma.pod
similarity index 62%
rename from Documentation/ssoma.txt
rename to Documentation/ssoma.pod
index f05e230..2e336f7 100644
--- a/Documentation/ssoma.txt
+++ b/Documentation/ssoma.pod
@@ -1,10 +1,10 @@
% ssoma(1) ssoma user manual
-# NAME
+=head1 NAME
ssoma - mail archive synchronization and extraction client
-# SYNOPSIS
+=head1 SYNOPSIS
ssoma add LISTNAME URL maildir:/path/to/maildir/ [TARGET]
@@ -16,35 +16,38 @@ ssoma sync [--since=DATE] [LISTNAME]
ssoma cat MESSAGE-ID [LISTNAME|GIT_DIR]
-# DESCRIPTION
+=head1 DESCRIPTION
-ssoma may be used to sync and export mail to Maildir, IMAP or mbox(5)
+ssoma may be used to sync and export mail to Maildir, IMAP or L<mbox(5)>
from any published ssoma git repository.
-* add LISTNAME URL DESTINATION [TARGET]
+=over
+
+=item add LISTNAME URL DESTINATION [TARGET]
This starts a subscription to a mailing list by configuring a git
repository. LISTNAME is a name of your choosing. It must only consist
of alphanumeric characters, underscores, periods and dashes, and must start
and end with an alphanumeric character. URL is the URL to a git repository,
-this supports all URLs git(7) supports. DESTINATION is the local
+this supports all URLs L<git(7)> supports. DESTINATION is the local
destination to extract mail to. This may be a maildir:, mbox: path,
or an imap:// or imaps:// URL.
-.
-The repository is stored in ~/.ssoma/$LISTNAME.git If at any time
-a user wishes to stop following the list, just remove the git repository
-from your file system.
-.
+
+The repository is stored in ~/.ssoma/$LISTNAME.git
+
+If at any time a user wishes to stop following the list, just remove the
+git repository from your file system.
+
IMAP users may configure the imap.pass and imap.tunnel variables in
-~/.ssoma/$LISTNAME.git/config in the same way as git-imap-send(1).
+~/.ssoma/$LISTNAME.git/config in the same way as L<git-imap-send(1)>.
Remember to restrict permissions to ~/.ssoma/$LISTNAME.git/config
if you are storing a password in it.
-.
-TARGET may optionally be specified if you wish to extract a list
-to multiple destinations (e.g. an mbox for certain tools, but also
-to your IMAP account). The default TARGET name is "local".
-* sync [--since=DATE] [LISTNAME] [TARGET]
+TARGET may optionally be specified if you wish to extract a list to multiple
+destinations (e.g. an mbox for certain tools, but also to your IMAP account).
+The default TARGET name is "local".
+
+=item sync [--since=DATE] [LISTNAME] [TARGET]
This clones/fetches from the remote git repository into the local
repository and extracts messages into destinations configured with the
@@ -52,47 +55,53 @@ repository and extracts messages into destinations configured with the
synchronized. If LISTNAME is given, only subscriptions for a given LISTNAME
is synchronized. If TARGET is also given, the only the specified TARGET
is synchronized.
-.
+
If you are following a list with a long history, you may only want to
extract recent messages by specifying --since=DATE and passing any DATE
-format understood by git-log(1).
+format understood by L<git-log(1)>.
-* cat MESSAGE-ID [LISTNAME|GIT_DIR]
+=item cat MESSAGE-ID [LISTNAME|GIT_DIR]
This outputs the message matching MESSAGE-ID to stdout (in mbox format).
If LISTNAME is given, this limits the Message-ID search to that list.
-.
+
Specifying a GIT_DIR in place of LISTNAME is also possible, this is
-intended for administrators using ssoma-rm(1).
+intended for administrators using L<ssoma-rm(1)>.
+
+=back
-# FILES
+=head1 FILES
All client-side git repositories are stored in ~/.ssoma/$LISTNAME.git/
-See ssoma_repository(5) for details.
-# ENVIRONMENT VARIABLES
+See L<ssoma_repository(5)> for details.
+
+=head1 ENVIRONMENT VARIABLES
SSOMA_HOME may be used to override the default ~/.ssoma/ directory.
This is useful for testing, but not recommended otherwise.
-# CONTACT
+=head1 CONTACT
+
+The mail archives are hosted at L<git://public-inbox.org/meta>
+
+See L<ssoma(1)> for instructions on how to subscribe.
-All feedback welcome via plain-text mail to <meta@public-inbox.org>\
-The mail archives are hosted at git://public-inbox.org/meta
You may subscribe using ssoma:
ssoma add pi git://public-inbox.org/meta mbox:/path/to/mbox
ssoma sync pi
-# SOURCE CODE
+=head1 SOURCE CODE
git clone git://80x24.org/ssoma
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<lt>meta@public-inbox.orgE<gt>
-Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
-License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>
+License: AGPL-3.0+ E<lt>http://www.gnu.org/licenses/agpl-3.0.txtE<gt>
-# SEE ALSO
+=head1 SEE ALSO
-git(1), ssoma_repository(5), ssoma-rm(1)
+L<git(1)>, L<ssoma_repository(5)>, L<ssoma-rm(1)>
diff --git a/Documentation/ssoma_repository.txt b/Documentation/ssoma_repository.pod
similarity index 59%
rename from Documentation/ssoma_repository.txt
rename to Documentation/ssoma_repository.pod
index 1303afd..1c5635c 100644
--- a/Documentation/ssoma_repository.txt
+++ b/Documentation/ssoma_repository.pod
@@ -1,32 +1,32 @@
% ssoma_repository(5) ssoma user manual
-# NAME
+=head1 NAME
ssoma_repository - repository and tree description for ssoma
-# DESCRIPTION
+=head1 DESCRIPTION
ssoma uses a git repository to store each email as a git blob. The tree
filename of the blob is based on the SHA1 hexdigest of the Message-ID
header. A commit is made for each message delivered. The commit SHA-1
identifier is used by ssoma clients to track synchronization state.
-# PATHNAMES IN TREES
+=head1 PATHNAMES IN TREES
A Message-ID may be extremely long and also contain slashes, so using
them as a path name is challenging. Instead we use the SHA-1 hexdigest
-of the Message-ID (excluding the leading "<" and trailing ">") to
-generate a path name. Leading and trailing white space in the
+of the Message-ID (excluding the leading "E<lt>" and trailing "E<gt>")
+to generate a path name. Leading and trailing white space in the
Message-ID header is ignored for hashing.
-A message with Message-ID of: <20131106023245.GA20224@dcvr.yhbt.net>
+A message with Message-ID of: E<lt>20131106023245.GA20224@dcvr.yhbt.netE<gt>
Would be stored as: f2/8c6cfd2b0a65f994c3e1be266105413b3d3f63
Thus it is easy to look up the contents of a message matching a given
a Message-ID.
-# CONFLICTS
+=head1 CONFLICTS
Message-ID is a unique-enough identifier for practical purposes, but
they may still conflict (especially in case of malicious clients and
@@ -50,7 +50,7 @@ Note: public-inbox currently uses "ssoma-mda -1" to disable this
conflict resolution feature. This simplifies the implementation
and use of public-inbox.
-# HEADERS
+=head1 HEADERS
The Message-ID (case-insensitive) header is required.
"Bytes", "Lines" and "Content-Length" headers are stripped and not
@@ -58,35 +58,42 @@ allowed, they can interfere with further processing.
When using ssoma with public-inbox-mda, the "Status" mbox header
is also stripped as that header makes no sense in a public archive.
-# LOCKING
+=head1 LOCKING
-flock(2) locking exclusively locks the empty $GIT_DIR/ssoma.lock file
+L<flock(2)> locking exclusively locks the empty $GIT_DIR/ssoma.lock file
for all non-atomic operations.
-# EXAMPLE INPUT FLOW (SERVER-SIDE MDA)
+=head1 EXAMPLE INPUT FLOW (SERVER-SIDE MDA)
1. Message is delivered to a mail transport agent (MTA)
+
1a. (optional) reject/discard spam, this should run before ssoma-lda
+
1b. (optional) reject/strip unwanted attachments
ssoma-mda handles all steps once invoked.
2. Mail transport agent invokes ssoma-mda
+
3. reads message via stdin, extracting Message-ID
+
4. acquires exclusive flock lock on $GIT_DIR/ssoma.lock
+
5. creates or updates the blob of associated 2/38 SHA-1 path
+
6. updates the index and commits
+
7. releases $GIT_DIR/ssoma.lock
-ssoma-mda can also be used as an inotify(7) trigger to monitor maildirs,
+ssoma-mda can also be used as an L<inotify(7)> trigger to monitor maildirs,
and the ability to monitor IMAP mailboxes using IDLE will be available
in the future.
-# GIT REPOSITORIES (SERVERS)
+=head1 GIT REPOSITORIES (SERVERS)
ssoma uses bare git repositories on both servers and clients.
-Using the git-init(1) command with --bare is the recommend method
+Using the L<git-init(1)> command with --bare is the recommend method
of creating a git repository on a server:
git init --bare /path/to/wherever/you/want.git
@@ -96,78 +103,104 @@ all the choices regarding git repository locations.
Special files in $GIT_DIR on the server:
-* $GIT_DIR/ssoma.index - a git index file used for MDA updates,
-: The normal git index (in $GIT_DIR/index) is not used at all as
- there is typically no working tree.
+=over
+
+=item $GIT_DIR/ssoma.index
+
+A git index file used for MDA updates.
+The normal git index (in $GIT_DIR/index) is not used at all as
+there is typically no working tree.
-* $GIT_DIR/ssoma.lock - empty file for flock(2) locking
-: This is necessary to ensure the index and commits are updated
- consistently and multiple processes running MDA do not step on
- each other.
+=item $GIT_DIR/ssoma.lock
-# GIT REPOSITORIES (CLIENTS)
+An empty file for L<flock(2)> locking.
+This is necessary to ensure the index and commits are updated
+consistently and multiple processes running MDA do not step on
+each other.
+
+=back
+
+=head1 GIT REPOSITORIES (CLIENTS)
ssoma uses bare git repositories for clients (as well as servers).
The default is to use GIT_DIR=~/.ssoma/$LISTNAME.git in the user's home
directory. This is a bare git repository with two additional files:
-* $GIT_DIR/ssoma.lock - empty lock file, same as used by ssoma-mda(1)
-* $GIT_DIR/ssoma.state - a git-config(1) format file used by ssoma(1)
+=over
+
+=item $GIT_DIR/ssoma.lock
+
+empty lock file, same as used by L<ssoma-mda(1)>
+
+=item $GIT_DIR/ssoma.state
+
+a L<git-config(1)> format file used by L<ssoma(1)>
+
+=back
Each client $GIT_DIR may have multiple mbox/maildir/command targets.
It is possible for a client to extract the mail stored in the git
repository to multiple mboxes for compatibility with a variety of
different tools.
-# $GIT_DIR/ssoma.state format.
-
- ; "local" is the default name (analogous to "origin" with remotes)
- [target "local"]
- path = /path/to/mbox
-
- ; this tells ssoma where to start the next import from
- ; this means ssoma will not redundantly import old
- ; messages and the user is free to move/delete old
- ; messages from the mbox.
- last-imported = 33eaf25f43fd73d8f4f7b0a066b689809d733191
-
- ; "alt" is a user-defined name, in case a user wants to output
- ; the repo in several formats
- [target "alt"]
- ; note the trailing '/' to denote the maildir path,
- ; the Email::LocalDelivery Perl module depends on this
- ; trailing slash to identify it as a maildir
- path = /path/to/maildir/
- last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
-
- ; users may also choose to pipe to an arbitrary command of their
- ; choice, this filter may behave like an MDA (and implement
- ; filtering). Tools like procmail(1)/maildrop(1) may be
- ; invoked here.
- [target "script"]
- command = /path/to/executable/which/reads-mail-from-stdin
- last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
-
-# EXAMPLE OUTPUT FLOW (CLIENT)
+=head1 $GIT_DIR/ssoma.state format
+
+ ; "local" is the default name (analogous to "origin" with remotes)
+ [target "local"]
+ path = /path/to/mbox
+
+ ; this tells ssoma where to start the next import from
+ ; this means ssoma will not redundantly import old
+ ; messages and the user is free to move/delete old
+ ; messages from the mbox.
+ last-imported = 33eaf25f43fd73d8f4f7b0a066b689809d733191
+
+ ; "alt" is a user-defined name, in case a user wants to output
+ ; the repo in several formats
+ [target "alt"]
+ ; note the trailing '/' to denote the maildir path,
+ ; the Email::LocalDelivery Perl module depends on this
+ ; trailing slash to identify it as a maildir
+ path = /path/to/maildir/
+ last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
+
+ ; users may also choose to pipe to an arbitrary command of their
+ ; choice, this filter may behave like an MDA (and implement
+ ; filtering). Tools like procmail(1)/maildrop(1) may be
+ ; invoked here.
+ [target "script"]
+ command = /path/to/executable/which/reads-mail-from-stdin
+ last-imported = 950815b313a4e616c6fe39f46b2e894b51d7d62f
+
+=head1 EXAMPLE OUTPUT FLOW (CLIENT)
1. clone or fetches to bare git repo (GIT_DIR=~/.ssoma/$LISTNAME.git)
+
2. checks for last-imported commit in ~/.ssoma/$LISTNAME.git/ssoma.state
+
3. diffs last-imported commit with current HEAD
+
4. imports new emails to mbox/maildir since last-imported up to current HEAD
+
5. updates last-imported commit
-# CAVEATS
+=head1 CAVEATS
It is NOT recommended to check out the working directory of a git.
there may be many files.
It is impossible to completely expunge messages, even spam, as git
retains full history. Projects may (with adequate notice) cycle to new
-repositories/branches with history cleaned up via git-filter-branch(1).
+repositories/branches with history cleaned up via L<git-filter-branch(1)>.
This is up to the administrators.
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<lt>meta@public-inbox.orgE<gt>
+
+License: AGPL-3.0+ E<lt>http://www.gnu.org/licenses/agpl-3.0.txtE<gt>
+
+=head1 SEE ALSO
-Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
-License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>
+L<gitrepository-layout(5)>, L<ssoma(1)>
diff --git a/MANIFEST b/MANIFEST
index 27283c9..ebfbe09 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,10 +1,10 @@
.gitignore
COPYING
Documentation/include.mk
-Documentation/ssoma-mda.txt
-Documentation/ssoma-rm.txt
-Documentation/ssoma.txt
-Documentation/ssoma_repository.txt
+Documentation/ssoma-mda.pod
+Documentation/ssoma-rm.pod
+Documentation/ssoma.pod
+Documentation/ssoma_repository.pod
Documentation/txt2pre
INSTALL
MANIFEST
--
EW
^ permalink raw reply related [relevance 2%]
* [PATCH] use Perl POD instead of pandoc-flavored Markdown
@ 2016-01-04 22:26 7% Eric Wong
0 siblings, 0 replies; 3+ results
From: Eric Wong @ 2016-01-04 22:26 UTC (permalink / raw)
To: meta
This project is currently implemented in Perl, and pod2man is
probably more common among potential users and developers of
this project.
---
Documentation/.gitignore | 1 +
Documentation/include.mk | 30 ++++++++++++++------
.../{public-inbox-mda.txt => public-inbox-mda.pod} | 32 ++++++++++++++++------
MANIFEST | 2 +-
4 files changed, 48 insertions(+), 17 deletions(-)
create mode 100644 Documentation/.gitignore
rename Documentation/{public-inbox-mda.txt => public-inbox-mda.pod} (34%)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..8ba4186
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1 @@
+/public-inbox-mda.txt
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 694416e..4669ac5 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -6,9 +6,12 @@ RSYNC = rsync
RSYNC_DEST = public-inbox.org:/srv/public-inbox/
docs := README COPYING INSTALL TODO $(shell git ls-files 'Documentation/*.txt')
INSTALL = install
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
+POD2MAN = pod2man
+POD2MAN_OPTS = -v --stderr -d 1994-10-02 -c 'public-inbox user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
m1 =
m1 += public-inbox-mda
@@ -36,13 +39,22 @@ install-man: man
test -z "$(man1)" || $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
test -z "$(man5)" || $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
-%.1 %.5 %.7 : Documentation/%.txt
- $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+%.1 : Documentation/%.pod
+ $(pod2man) -s 1 $< $@+ && mv $@+ $@
+
+mantxt = $(addprefix Documentation/, $(addsuffix .txt, $(m1)))
+docs += $(mantxt)
+
+all :: $(mantxt)
+
+Documentation/%.txt : Documentation/%.pod
+ $(pod2text) $< $@+ && mv $@+ $@
txt2pre = ./Documentation/txt2pre < $< > $@+ && touch -r $< $@+ && mv $@+ $@
txt := INSTALL README COPYING TODO
-dtxt := design_notes.txt design_www.txt dc-dlvr-spam-flow.txt
-dtxt := $(addprefix Documentation/, $(dtxt))
+dtxt := design_notes.txt design_www.txt dc-dlvr-spam-flow.txt
+dtxt := $(addprefix Documentation/, $(dtxt)) $(mantxt)
%.html: %.txt
$(txt2pre)
@@ -64,4 +76,6 @@ rsync-doc:
$(MAKE) gz-doc
$(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(RSYNC_DEST)
clean-doc:
- $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html)
+ $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html) $(mantxt)
+
+clean :: clean-doc
diff --git a/Documentation/public-inbox-mda.txt b/Documentation/public-inbox-mda.pod
similarity index 34%
rename from Documentation/public-inbox-mda.txt
rename to Documentation/public-inbox-mda.pod
index 8e33e02..80bb349 100644
--- a/Documentation/public-inbox-mda.txt
+++ b/Documentation/public-inbox-mda.pod
@@ -1,20 +1,36 @@
% public-inbox-mda(1) public-inbox user manual
-# NAME
+=head1 NAME
public-inbox-mda - mail delivery for public-inbox
-# SYNOPSIS
+=head1 SYNOPSIS
+
+B<public-inbox-mda> E<lt> message
+
+=head1 DESCRIPTION
Mail Delivery Agent (MDA) for public-inbox installations.
Each system user may have their own public-inbox instances
-# ENVIRONMENT
+=head1 ENVIRONMENT
+
+=over 8
+
+=item ORIGINAL_RECIPIENT
+
+the original recipient email address, from Postfix
+
+=item PI_CONFIG
+
+config file. default: ~/.public-inbox/config
+
+=item PI_EMERGENCY
+
+emergency destination. default: ~/.public-inbox/emergency/
-* ORIGINAL_RECIPIENT - the original recipient email address, from Postfix
-* PI_CONFIG - config file. default: ~/.public-inbox/config
-* PI_EMERGENCY - emergency destination. default: ~/.public-inbox/emergency/
+=back
-# PI_CONFIG FILE
+=head1 PI_CONFIG FILE
-This is a config file parseable by git-config(1).
+This is a config file parseable by L<git-config(1)>.
diff --git a/MANIFEST b/MANIFEST
index 5d45046..e11afc8 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4,7 +4,7 @@ Documentation/dc-dlvr-spam-flow.txt
Documentation/design_notes.txt
Documentation/design_www.txt
Documentation/include.mk
-Documentation/public-inbox-mda.txt
+Documentation/public-inbox-mda.pod
Documentation/txt2pre
HACKING
INSTALL
--
EW
^ permalink raw reply related [relevance 7%]
Results 1-3 of 3 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2016-01-04 22:26 7% [PATCH] use Perl POD instead of pandoc-flavored Markdown Eric Wong
2016-01-11 2:34 2% [PATCH ssoma] " Eric Wong
2016-03-03 3:45 6% [ANNOUNCE] ssoma 0.2.0 - a bunch of updates Eric Wong
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).