linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
Subject: Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock
Date: Sun, 1 Aug 2021 19:28:24 +1000	[thread overview]
Message-ID: <20210801092822.cpbqa3hdmkd23es2@localhost.localdomain> (raw)
In-Reply-To: <6c73ce9c-c8b3-426a-5c0a-f66b634210fb@gmail.com>

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

[CC list brutally trimmed]

At 2021-07-31T13:02:27+0200, Alejandro Colomar (man-pages) wrote:
> I think you misunderstood the context here.
> 
> I meant all of that about input, i.e., the text of the patch itself,
> text to be added to a man page source text.
> 
> What I meant is that when you break lines semantically (when writing a
> patch), and initially forget about the 80 (or 75) column right margin,
> most of the lines you write will already (as a side effect of breaking
> lines semantically) be within the 80 (or 75) right margin.
> 
> For those that still don't fit into 80 characters after doing that,
> break further (or at some other point that may also break nicely
> semantically); otherwise, I won't see the text when editing the man
> page on my 80-col terminal.
> 
> For those that still don't fit into 75 characters after doing that,
> consider breaking further, but only if doing so seems easy and lines
> break nicely.  I can still see after line 75, and I can do some effort
> to scroll an email a few columns if needed (when many quotes move the
> text further to the right).  So if the source code would break in a
> weird way because of forcing a 75 col right margin, please ignore that
> margin.
> 
> I hope I was clear this time.

Quite so.  In my experience with the groff man pages (~60 of them), when
you apply the semantic newline rule to commas, colons, and semicolons as
well as sentence-ending punctuation, text lines that exceed 72 columns
are fairly rare.  (I also set multi-word parentheticals on their own
input lines.)

As I've noted elsewhere (in the "intro" PDF I shared the other day,
though I don't think the document made it to the linux-man@
list--filtered, I suspect), if you find yourself crashing past 72
columns when using semantic newlines with ordinary prose, there's a good
chance you need to recast for readability.

From what I've seen, the hardest line length problems the Linux
man-pages project deals with are in non-prose contexts; function
synopses and similar.

> BTW, thanks for your mail.  It wasn't related to what I meant, but was
> interesting :=)

Thank you.  That mitigates my chagrin at talking past the point.  :)

Regards,
Branden

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

  reply	other threads:[~2021-08-01  9:28 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-12 15:57 [PATCH v2 0/4] Add Landlock man pages Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock Mickaël Salaün
2021-07-29 14:56   ` Alejandro Colomar (man-pages)
2021-07-29 22:01     ` G. Branden Robinson
2021-07-29 22:34       ` Alejandro Colomar (man-pages)
2021-07-30 12:15     ` Mickaël Salaün
2021-07-30 12:41       ` Alejandro Colomar (man-pages)
2021-07-30 12:59         ` Alejandro Colomar (man-pages)
2021-07-30 14:32           ` Mickaël Salaün
2021-07-31  0:15           ` G. Branden Robinson
2021-07-31 11:02             ` Alejandro Colomar (man-pages)
2021-08-01  9:28               ` G. Branden Robinson [this message]
2021-07-30 23:39       ` G. Branden Robinson
2021-07-31 10:51         ` Alejandro Colomar (man-pages)
2021-07-31 13:48           ` G. Branden Robinson
2021-07-12 15:57 ` [PATCH v2 2/4] landlock_create_ruleset.2: Document new syscall Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 3/4] landlock_add_rule.2: " Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 4/4] landlock_restrict_self.2: " Mickaël Salaün

Reply instructions:

You may reply publicly 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

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

  git send-email \
    --in-reply-to=20210801092822.cpbqa3hdmkd23es2@localhost.localdomain \
    --to=g.branden.robinson@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=linux-man@vger.kernel.org \
    --subject='Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock' \
    /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

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 NNTP newsgroup(s).