summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorKyle Meyer <kyle@kyleam.com>2021-06-10 14:59:43 -0400
committerKyle Meyer <kyle@kyleam.com>2021-06-11 13:36:54 -0400
commitc901d3ec025773c8eae04257099fcdfe704085ac (patch)
tree738fb967fe89d468e5a5d8f56810c544bd9075bd /Documentation
parent61952fe189a2a1e97b7156eaee831a5a1915dd57 (diff)
downloadpiem-c901d3ec025773c8eae04257099fcdfe704085ac.tar.gz
Support reading inboxes from ~/.public-inbox/config
A client may mirror and configure inboxes locally. Doing so enables fast local access to public-inbox-httpd and public-inbox-nntpd. And with the next pubic-inbox release (v1.7), it will be necessary to set up local externals for lei. That can lead to a good amount of information being duplicated between the piem-inboxes option and ~/.public-inbox/config. To avoid this, let users set an option to enable collecting information from public-inbox's configuration. This relies on code getting the list of inboxes with piem-merged-inboxes rather than inspecting piem-inboxes directly. That should be okay because at this point there should be very few third-party callers. An alternative would be to merge values from the configuration into the value of piem-inboxes. That'd let callers continue to inspect public-inboxes, but I'd prefer not to touch the value of a user option. Message-Id: <20210610185943.14155-5-kyle@kyleam.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/piem.texi46
1 files changed, 46 insertions, 0 deletions
diff --git a/Documentation/piem.texi b/Documentation/piem.texi
index 3e3ccf9..73d277e 100644
--- a/Documentation/piem.texi
+++ b/Documentation/piem.texi
@@ -165,6 +165,52 @@ local clone of @url{https://git.kernel.org/pub/scm/git/git.git/}). This
information is required to apply patches from an archive to a local code
repository (@pxref{Applying patches}).
+@findex piem-merged-inboxes
+@vindex piem-get-inboxes-from-config
+If you mirror some inboxes locally (e.g., for fast local access or for
+use with lei), you don't need to duplicate the information from your
+public-inbox configuration
+(@url{https://public-inbox.org/public-inbox-config.txt,public-inbox-config(5)}).
+When the option @code{piem-get-inboxes-from-config} is non-nil, the
+function @code{piem-merged-inboxes}, which all code should use for
+accessing the registered inboxes, returns a combined set of inboxes
+derived from @code{piem-inboxes} and public-inbox's configuration.
+Merging is done at the level of inbox properties (e.g., an inbox's URL
+may be defined in @code{piem-inboxes} and the inbox's address in
+public-inbox's configuration). When a value is defined in both sources,
+the one in @code{piem-inboxes} takes precedence.
+
+Properties described for @code{piem-inboxes} are constructed by mapping
+
+@example
+[publicinbox $inbox]
+$name = $value
+@end example
+
+@noindent
+to
+
+@example
+ ($inbox :$name $value ...)
+@end example
+
+@noindent
+The one exception is @code{:coderepo}. In public-inbox's configuration,
+the value of @code{publicinbox.$inbox.coderepo} points to another
+configuration option, @code{coderepo.$value.dir}, which in turn points
+to a repository's git directory. The @code{:coderepo} of
+@code{piem-inboxes}, however, should be set to the @emph{working tree},
+so @code{:coderepo} is derived from the value of
+@code{coderepo.$value.dir}, stripping a trailing @file{/.git} if
+present.
+
+@findex piem-clear-merged-inboxes
+Note that @code{piem-merged-inboxes} reads from the public-inbox
+configuration once, generates the merged set of inboxes, and then caches
+the result. If you change @code{piem-inboxes} outside the customize
+interface or change public-inbox's configuration, you need to call the
+command @code{piem-clear-merged-inboxes} to clear the cache.
+
@node Enabling integration libraries
@section Enabling integration libraries
@findex piem-elfeed-mode