linux-kernel.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: "Mickaël Salaün" <mic@digikod.net>,
	"Jann Horn" <jannh@google.com>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"Kees Cook" <keescook@chromium.org>,
	"Randy Dunlap" <rdunlap@infradead.org>,
	"Vincent Dagonneau" <vincent.dagonneau@ssi.gouv.fr>,
	landlock@lists.linux.dev, linux-kernel@vger.kernel.org,
	linux-man@vger.kernel.org, linux-security-module@vger.kernel.org,
	"Mickaël Salaün" <mic@linux.microsoft.com>,
	"Michael Kerrisk" <mtk.manpages@gmail.com>
Subject: Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock
Date: Sat, 31 Jul 2021 10:15:31 +1000	[thread overview]
Message-ID: <20210731001529.ggiknccl74akaahk@localhost.localdomain> (raw)
In-Reply-To: <1a698059-d9dd-5aa0-2765-42e704c3a697@gmail.com>

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

Hi, Alex!

At 2021-07-30T14:59:52+0200, Alejandro Colomar (man-pages) wrote:
> Yes, they were because of semantic newlines.
> 
> The "rules" are:
> 
> Follow mainly "semantic newlines" style (forgetting about the line
> length), which will give you a text that (mostly) fits into 75 or 80
> columns.
> 
> If after doing that there are some lines that exceed the 75 or 80
> column right margin, consider fixing that line by breaking it at a
> different point or maybe breaking it further.  The 80 column limit is
> a hard limit (I can't read anything past the 80 col), while the 75
> limit is a bit softer (that's for allowing quotes in reviews) (if
> fitting a line into col 75 would break it in a weird way, don't do
> it).
> 
> If I didn't explain myself enough, please tell me.

I'm a little puzzled by the above.  Semantic newlines have little to do
with the output line length in *roff systems.  They arose due to a Bell
Labs Unix Room practice, popularized by Brian Kernighan.  Brandon Rhodes
has a backgrounder on this[1].

Man pages tend to be really flexible with respect to output line length.
This is one reason the groff man macros expose a user-settable LL
register.  The main limitations on line length are people using tbl(1)
tables or disabling filling (with the .nf request or in .EX/.EE
examples).  Another limitation is that as lines get shorter, it becomes
hard to set the page headers and footers without them overlapping.

For the first two points there is not much the macro package can do;
both tbl(1) and filling disablement leave the placement of line breaks
in the hands of the document author, and they can abuse that power by
"oversetting" a line; that is, making it longer than the configured line
length.

The third point is a problem the macro package can overcome with some
effort, by measuring the lengths of the components that go into a header
or footer an abbreviating them.  This is not a theoretical concern;
Erlang supplies some man pages with insanely long names[2], and you can
see the problem in footers today on the man-pages site for any page
groff ships, because Michael pulls from our Git repository (to my great
relief, because I fix documentation errors and make other improvements
all the time) and our version identifier has gotten crazily long because
we're on the order of one thousand commits since the last release
candidate, and gnulib's git-version-gen uses release tags, commit count
since the tag, _and_ an abbreviated commit ID to generate the version
string.  For my tree right now that's "1.23.0.rc1.999-7ae6d".

Here's a specimen of how that works out in a rendered page:
<https://man7.org/linux/man-pages/man1/neqn.1.html> (scroll to the
bottom).

I've fixed the problem for long page names for the next groff release,
but it involved some string-manipulation gymnastics[3].  I haven't yet
factored those out into their own (private) macro which I can also call
when preparing the page footer.

Regards,
Branden

[1] https://rhodesmill.org/brandon/2012/one-sentence-per-line/
[2] CosNotifyChannelAdmin_StructuredProxyPushSupplier(3erl)
[3] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=b7f38e8a1d698e1078d7c215d08fde57d8e919b9

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

  parent reply	other threads:[~2021-07-31  0:15 UTC|newest]

Thread overview: 17+ 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 [this message]
2021-07-31 11:02             ` Alejandro Colomar (man-pages)
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=20210731001529.ggiknccl74akaahk@localhost.localdomain \
    --to=g.branden.robinson@gmail.com \
    --cc=alx.manpages@gmail.com \
    --cc=corbet@lwn.net \
    --cc=jannh@google.com \
    --cc=keescook@chromium.org \
    --cc=landlock@lists.linux.dev \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=linux-security-module@vger.kernel.org \
    --cc=mic@digikod.net \
    --cc=mic@linux.microsoft.com \
    --cc=mtk.manpages@gmail.com \
    --cc=rdunlap@infradead.org \
    --cc=vincent.dagonneau@ssi.gouv.fr \
    --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).