[PATCH 0/6] doc: linkify HTML harder

[PATCH 0/6] doc: linkify HTML harder

[Eric Wong]

<a> is really the only reason to use HTML :P

Eric Wong (6):
  doc: txt2pre: linkify new commands
  doc: lei: improve description of *-search commands
  doc: txt2pre: linkify "lei COMMAND" form
  doc: txt2pre: modernize and use v5.12
  doc: lei-import: link to lei-store-format(5)
  txt2pre: linkify lei/store => lei-store-format.html

 Documentation/lei-edit-search.pod   |  6 ++++--
 Documentation/lei-forget-search.pod |  4 +++-
 Documentation/lei-import.pod        |  5 +++--
 Documentation/lei-ls-search.pod     |  5 +++--
 Documentation/txt2pre               | 19 ++++++++++++++-----
 5 files changed, 27 insertions(+), 12 deletions(-)

[PATCH 1/6] doc: txt2pre: linkify new commands

[Eric Wong]

lei-index, public-inbox-netd, and public-inbox-pop3d
were not properly linkified in our HTML documentation.
---
 Documentation/txt2pre | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 3ecd9100..c8dbd2ba 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -42,6 +42,7 @@ for (qw[lei(1)
 	lei-q(1)
 	lei-rediff(1)
 	lei-refresh-mail-sync(1)
+	lei-reindex(1)
 	lei-rm(1)
 	lei-rm-watch(1)
 	lei-security(7)
@@ -63,8 +64,10 @@ for (qw[lei(1)
 	public-inbox-init(1)
 	public-inbox-learn(1)
 	public-inbox-mda(1)
+	public-inbox-netd(1)
 	public-inbox-nntpd(1)
 	public-inbox-overview(7)
+	public-inbox-pop3d(1)
 	public-inbox-purge(1)
 	public-inbox-v1-format(5)
 	public-inbox-v2-format(5)

[PATCH 2/6] doc: lei: improve description of *-search commands

[Eric Wong]

The `OUTPUT' use may not be immediately apparent, clarify
that it's from `lei q'.
---
 Documentation/lei-edit-search.pod   | 6 ++++--
 Documentation/lei-forget-search.pod | 4 +++-
 Documentation/lei-ls-search.pod     | 5 +++--
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/lei-edit-search.pod b/Documentation/lei-edit-search.pod
index 21cb11aa..7f447ca2 100644
--- a/Documentation/lei-edit-search.pod
+++ b/Documentation/lei-edit-search.pod
@@ -8,7 +8,9 @@ lei edit-search [OPTIONS] OUTPUT
 
 =head1 DESCRIPTION
 
-Invoke C<git config --edit> to edit the saved search at C<OUTPUT>.
+Invoke C<git config --edit> to edit the saved search at C<OUTPUT>,
+where C<OUTPUT> was supplied for argument of C<lei q -o OUTPUT ...>
+A listing of outputs is available via C<lei ls-search>.
 
 =head1 CONTACT
 
@@ -19,7 +21,7 @@ and L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta
 
 =head1 COPYRIGHT
 
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
diff --git a/Documentation/lei-forget-search.pod b/Documentation/lei-forget-search.pod
index adbe7638..5ff526f1 100644
--- a/Documentation/lei-forget-search.pod
+++ b/Documentation/lei-forget-search.pod
@@ -8,7 +8,9 @@ lei forget-search [OPTIONS] OUTPUT
 
 =head1 DESCRIPTION
 
-Forget a saved search at C<OUTPUT>.
+Forget a saved search at C<OUTPUT>,
+where C<OUTPUT> was supplied for argument of C<lei q -o OUTPUT ...>
+A listing of outputs is available via C<lei ls-search>.
 
 =head1 OPTIONS
 
diff --git a/Documentation/lei-ls-search.pod b/Documentation/lei-ls-search.pod
index a56611bf..0fe4b759 100644
--- a/Documentation/lei-ls-search.pod
+++ b/Documentation/lei-ls-search.pod
@@ -8,7 +8,8 @@ lei ls-search [OPTIONS] [PREFIX]
 
 =head1 DESCRIPTION
 
-List saved search queries.  If C<PREFIX> is given, restrict the output
+List saved search queries (generated from C<lei q -o OUTPUT>).
+If C<PREFIX> is given, restrict the output
 to entries that start with the specified value.
 
 =head1 OPTIONS
@@ -55,7 +56,7 @@ and L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta
 
 =head1 COPYRIGHT
 
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 

[PATCH 3/6] doc: txt2pre: linkify "lei COMMAND" form

[Eric Wong]

While manpages are named `L<lei-COMMAND(1)>', `lei COMMAND'
can be worth linkifying for ease-of-navigation, too.
---
 Documentation/txt2pre | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index c8dbd2ba..82573a30 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -9,7 +9,7 @@ use strict;
 use warnings;
 use PublicInbox::Linkify;
 use PublicInbox::Hval qw(ascii_html);
-my %xurls;
+my (%xurls, %lei);
 for (qw[lei(1)
 	lei-add-external(1)
 	lei-add-watch(1)
@@ -77,6 +77,7 @@ for (qw[lei(1)
 	my ($n) = (/([\w\-\.]+)/);
 	$xurls{$_} = "$n.html";
 	$xurls{$n} = "$n.html";
+	/\Alei-(.+?)\(1\)\z/ and $xurls{"lei $1"} = "$n.html";
 }
 
 for (qw[make(1) flock(2) setrlimit(2) vfork(2) tmpfs(5) inotify(7) unix(7)
@@ -161,6 +162,9 @@ if ($str =~ /^NAME\n\s+([^\n]+)/sm) {
 	if ($title =~ /([\w\.\-]+)/) {
 		delete $xurls{$1};
 	}
+	if ($title =~ /\blei-([\w\-]+)\b/) {
+		delete $xurls{"lei $1"};
+	}
 }
 $title = ascii_html($title);
 my $l = PublicInbox::Linkify->new;

[PATCH 4/6] doc: txt2pre: modernize and use v5.12

[Eric Wong]

Another teeny step towards v5.12.
---
 Documentation/txt2pre | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 82573a30..b9d74fb7 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -1,12 +1,12 @@
-#!/usr/bin/env perl
-# Copyright (C) 2014-2021 all contributors <meta@public-inbox.org>
+#!perl -w
+# n.b. this is invoked via $(PERL) in makefiles
+# Copyright (C) all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # Stupid script to make HTML from preformatted, utf-8 text versions,
 # only generating links for http(s).  Markdown does too much
 # and requires indentation to output preformatted text.
-use strict;
-use warnings;
+use v5.12;
 use PublicInbox::Linkify;
 use PublicInbox::Hval qw(ascii_html);
 my (%xurls, %lei);

[PATCH 5/6] doc: lei-import: link to lei-store-format(5)

[Eric Wong]

Users should know where `lei import' writes to.
---
 Documentation/lei-import.pod | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 4ac7dccd..25ef75c3 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -10,7 +10,8 @@ lei import [OPTIONS] (--stdin|-)
 
 =head1 DESCRIPTION
 
-Import messages into the local storage of L<lei(1)>.  C<LOCATION> is a
+Import messages into the local storage of L<lei(1)>
+(aka L<lei/store|lei-store-format(5)>).  C<LOCATION> is a
 source of messages: a directory (Maildir), a file, or a URL
 (C<imap://>, C<imaps://>, C<nntp://>, or C<nntps://>).  URLs requiring
 authentication use L<git-credential(1)> to
@@ -102,4 +103,4 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
-L<lei-index(1)>
+L<lei-index(1)>, L<lei-store-format(5)>

[PATCH 6/6] txt2pre: linkify lei/store => lei-store-format.html

[Eric Wong]

Linking to the manpage probably helps clarify what `lei/store'
refers to without too much clutter in the raw POD source.
---
 Documentation/txt2pre | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index b9d74fb7..62175f34 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -80,6 +80,8 @@ for (qw[lei(1)
 	/\Alei-(.+?)\(1\)\z/ and $xurls{"lei $1"} = "$n.html";
 }
 
+$xurls{'lei/store'} = 'lei-store-format.html';
+
 for (qw[make(1) flock(2) setrlimit(2) vfork(2) tmpfs(5) inotify(7) unix(7)
 		syslog(3)]) {
 	my ($n, $s) = (/([\w\-]+)\((\d)\)/);

Re: [PATCH 5/6] doc: lei-import: link to lei-store-format(5)

[Eric Wong]

Eric Wong <e@80x24.org> wrote:
> +(aka L<lei/store|lei-store-format(5)>).  C<LOCATION> is a

Can't have unescaped `/' like that, will squash this in:

diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 25ef75c3..69ec6497 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -11,7 +11,7 @@ lei import [OPTIONS] (--stdin|-)
 =head1 DESCRIPTION
 
 Import messages into the local storage of L<lei(1)>
-(aka L<lei/store|lei-store-format(5)>).  C<LOCATION> is a
+(aka L<leiE<sol>store|lei-store-format(5)>).  C<LOCATION> is a
 source of messages: a directory (Maildir), a file, or a URL
 (C<imap://>, C<imaps://>, C<nntp://>, or C<nntps://>).  URLs requiring
 authentication use L<git-credential(1)> to