user/dev discussion of public-inbox itself
 help / color / Atom feed
* [PATCH] public-inbox-v2-format(5): fix formatting
@ 2019-10-07 20:27 Alyssa Ross
  2019-10-07 20:52 ` Eric Wong
  0 siblings, 1 reply; 4+ messages in thread
From: Alyssa Ross @ 2019-10-07 20:27 UTC (permalink / raw)
  To: meta; +Cc: Alyssa Ross

This was being rendered as a paragraph, so line breaks weren't
preserved and it was unreadable in man.
---
 Documentation/public-inbox-v2-format.pod | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod
index 28d3550..58e6b6d 100644
--- a/Documentation/public-inbox-v2-format.pod
+++ b/Documentation/public-inbox-v2-format.pod
@@ -24,13 +24,13 @@ $EPOCH - Integer starting with 0 based on time
 $SCHEMA_VERSION - PublicInbox::Search::SCHEMA_VERSION used by Xapian
 $PART - Integer (0..NPROCESSORS)
 
-foo/ # assuming "foo" is the name of the list
-- inbox.lock                 # lock file (flock) to protect global state
-- git/$EPOCH.git             # normal git repositories
-- all.git                    # empty git repo, alternates to git/$EPOCH.git
-- xap$SCHEMA_VERSION/$SHARD  # per-shard Xapian DB
-- xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP and threading
-- msgmap.sqlite3             # same the v1 msgmap
+	foo/                              # assuming "foo" is the name of the list
+	- inbox.lock                      # lock file (flock) to protect global state
+	- git/$EPOCH.git                  # normal git repositories
+	- all.git                         # empty git repo, alternates to git/$EPOCH.git
+	- xap$SCHEMA_VERSION/$SHARD       # per-shard Xapian DB
+	- xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP and threading
+	- msgmap.sqlite3                  # same the v1 msgmap
 
 For blob lookups, the reader only needs to open the "all.git"
 repository with $GIT_DIR/objects/info/alternates which references
-- 
2.23.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] public-inbox-v2-format(5): fix formatting
  2019-10-07 20:27 [PATCH] public-inbox-v2-format(5): fix formatting Alyssa Ross
@ 2019-10-07 20:52 ` Eric Wong
  2019-10-07 21:13   ` Alyssa Ross
  0 siblings, 1 reply; 4+ messages in thread
From: Eric Wong @ 2019-10-07 20:52 UTC (permalink / raw)
  To: Alyssa Ross; +Cc: meta

Alyssa Ross <hi@alyssa.is> wrote:
> This was being rendered as a paragraph, so line breaks weren't
> preserved and it was unreadable in man.

Thanks for noticing that, it's obvious I never really looked at
the result :x  (and I'm writing a new .pod right now, too)

> diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod
> index 28d3550..58e6b6d 100644
> --- a/Documentation/public-inbox-v2-format.pod
> +++ b/Documentation/public-inbox-v2-format.pod
> @@ -24,13 +24,13 @@ $EPOCH - Integer starting with 0 based on time
>  $SCHEMA_VERSION - PublicInbox::Search::SCHEMA_VERSION used by Xapian
>  $PART - Integer (0..NPROCESSORS)

Looks like the lines preceding this patch need to be indented to
preserve newlines, too.

> -foo/ # assuming "foo" is the name of the list
> -- inbox.lock                 # lock file (flock) to protect global state
> -- git/$EPOCH.git             # normal git repositories
> -- all.git                    # empty git repo, alternates to git/$EPOCH.git
> -- xap$SCHEMA_VERSION/$SHARD  # per-shard Xapian DB
> -- xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP and threading
> -- msgmap.sqlite3             # same the v1 msgmap
> +	foo/                              # assuming "foo" is the name of the list
> +	- inbox.lock                      # lock file (flock) to protect global state
> +	- git/$EPOCH.git                  # normal git repositories
> +	- all.git                         # empty git repo, alternates to git/$EPOCH.git
> +	- xap$SCHEMA_VERSION/$SHARD       # per-shard Xapian DB
> +	- xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP and threading
> +	- msgmap.sqlite3                  # same the v1 msgmap

I noticed both the original and post-patch manpage exceeds the
limits of an 80-column terminal.  I think it's worth it to
reflow and perhaps reword to ensure folks who are limited to 80
columns can viwe (but I can take care of it, too, if you're busy)

Even fitting 80 columns on my screen is a challenge with the
giant fonts I need to workaround poor eyesight :<

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] public-inbox-v2-format(5): fix formatting
  2019-10-07 20:52 ` Eric Wong
@ 2019-10-07 21:13   ` Alyssa Ross
  2019-10-15 20:11     ` [PATCH 2/1] doc: v2-format: get man output under 80 cols Eric Wong
  0 siblings, 1 reply; 4+ messages in thread
From: Alyssa Ross @ 2019-10-07 21:13 UTC (permalink / raw)
  To: Eric Wong; +Cc: meta

[-- Attachment #1: Type: text/plain, Size: 480 bytes --]

> I noticed both the original and post-patch manpage exceeds the
> limits of an 80-column terminal.  I think it's worth it to
> reflow and perhaps reword to ensure folks who are limited to 80
> columns can viwe (but I can take care of it, too, if you're busy)
>
> Even fitting 80 columns on my screen is a challenge with the
> giant fonts I need to workaround poor eyesight :<

I appreciate your commitment!  I think you'd be a better judge of how
to format it nicely than me. :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH 2/1] doc: v2-format: get man output under 80 cols
  2019-10-07 21:13   ` Alyssa Ross
@ 2019-10-15 20:11     ` Eric Wong
  0 siblings, 0 replies; 4+ messages in thread
From: Eric Wong @ 2019-10-15 20:11 UTC (permalink / raw)
  To: meta; +Cc: Alyssa Ross

Alyssa Ross <hi@alyssa.is> wrote:
> > I noticed both the original and post-patch manpage exceeds the
> > limits of an 80-column terminal.  I think it's worth it to
> > reflow and perhaps reword to ensure folks who are limited to 80
> > columns can viwe (but I can take care of it, too, if you're busy)
> >
> > Even fitting 80 columns on my screen is a challenge with the
> > giant fonts I need to workaround poor eyesight :<
> 
> I appreciate your commitment!  I think you'd be a better judge of how
> to format it nicely than me. :)

I'll apply this on top of your patch since there's wording
changes, too:

------8<----
Subject: [PATCH] doc: v2-format: get man output under 80 cols

We need to better ensure our manpage output is readable with a
standard terminal width.  And fix some wording while we're at
it:

* use "inbox" instead of "list" for our storage
* replace the last "$PART" reference with "$SHARD"
---
 Documentation/public-inbox-v2-format.pod | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/public-inbox-v2-format.pod b/Documentation/public-inbox-v2-format.pod
index 58e6b6d3..10c63090 100644
--- a/Documentation/public-inbox-v2-format.pod
+++ b/Documentation/public-inbox-v2-format.pod
@@ -20,17 +20,17 @@ databases for parallelism by "shards".
 
 =head2 INBOX OVERVIEW AND DEFINITIONS
 
-$EPOCH - Integer starting with 0 based on time
-$SCHEMA_VERSION - PublicInbox::Search::SCHEMA_VERSION used by Xapian
-$PART - Integer (0..NPROCESSORS)
-
-	foo/                              # assuming "foo" is the name of the list
-	- inbox.lock                      # lock file (flock) to protect global state
-	- git/$EPOCH.git                  # normal git repositories
-	- all.git                         # empty git repo, alternates to git/$EPOCH.git
-	- xap$SCHEMA_VERSION/$SHARD       # per-shard Xapian DB
-	- xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP and threading
-	- msgmap.sqlite3                  # same the v1 msgmap
+  $EPOCH - Integer starting with 0 based on time
+  $SCHEMA_VERSION - DB schema version (for Xapian)
+  $SHARD - Integer starting with 0 based on parallelism
+
+  foo/                              # "foo" is the name of the inbox
+  - inbox.lock                      # lock file to protect global state
+  - git/$EPOCH.git                  # normal git repositories
+  - all.git                         # empty, alternates to $EPOCH.git
+  - xap$SCHEMA_VERSION/$SHARD       # per-shard Xapian DB
+  - xap$SCHEMA_VERSION/over.sqlite3 # OVER-view DB for NNTP, threading
+  - msgmap.sqlite3                  # same the v1 msgmap
 
 For blob lookups, the reader only needs to open the "all.git"
 repository with $GIT_DIR/objects/info/alternates which references

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-07 20:27 [PATCH] public-inbox-v2-format(5): fix formatting Alyssa Ross
2019-10-07 20:52 ` Eric Wong
2019-10-07 21:13   ` Alyssa Ross
2019-10-15 20:11     ` [PATCH 2/1] doc: v2-format: get man output under 80 cols Eric Wong

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