[bug #64018] [man, mdoc] decide on a common base paragraph indentation

[Ingo Schwarze]

Follow-up Comment #21, bug #64018 (project groff):

Regarding editing manual page source code in such a way as to avoid
particularly ugly line breaks in standard-width 80 column terminal windows:

[comment #12 comment #12:]
> Possibly, _mdoc_(7) page authors knew this and carefully edited the ones
that did, so that now no one sees them.
> But they would have be de-semanticizing their inputs by sweating formatting
details.
> Perhaps Ingo will join me in finding that dubious,

In OpenBSD, people *mostly* avoid such hand-optimization of presentational
markup and stick to semantic markup.  In the vast majority of cases, that
yields good results and minimizes maintenance effort.

However, a smaller number of pages exists that, for one reason or another, are
hard to get into a state both easy to read and looking pleasant, if you purely
stick to presentational markup.  It typically  happens with content that is
more complicated and harder to understand in the first place.  These cases are
not typically as simple and straightforward as SYNOPSIS sections; we tend to
stick to semantic markup in the SYNOPSIS.  The auto-breaking features of .Op,
.Fl, and .Ar tend to work reliably in general.

I know for sure that in such cases, our chief documentation maintainer, Jason
McIntyre, occasionally does resort to manually optimizing the source code such
that output lines do not exceed 80 columns, do not break in bad places places,
and so on.  Now if we would suddenly increase the global indentation by 2n,
most of these hand-optimized cases would suddenly become hard to read and ugly
in precisely the way Jason spent some work on avoiding.  That would be bad
because, as i said, these are not just random cases, but typically cases with
complicated content, where causing an additional distraction for the readers
would be particularly unfortunate.

For that reason, i'm definitely not going to increase the global offset from
5n to 7n in mandoc(1).  Even if you were to do that in groff(1), mandoc would
certainly not follow, and i might possibly even patch it back in the OpenBSD
port of groff.

I'm not quite sure how this kind of hand-optimization is regarded in FreeBSD
and NetBSD.  I talked to both Warren Block and Thomas Klausner multiple times
face-to-face, but don't recall ever bringing up this particular topic.  I
guess their view might be somewhat similar, but i'm not completely sure.  It
seems likely to me their approach might be somewhat less systematic and more
ad-hoc than in OpenBSD.  So i cannot exclude that hand-optimization might be
slightly more common and semantic markup slightly weaker on average in their
pages than in ours.  In general, they tend to invest less into documentation
than we do.  I know even less about DragonflyBSD, except that they usually
follow FreeBSD quite closely (even though often with significant time delays)
unless they are specifically working on an area of their system, so i doubt
they are doing much general-purpose manual page work in the first place.

> even if he hates the changed indentation (which I aim to change back, and
port over to _groff man_(7), in case that wasn't clear).

I felt relieved when earlier comments in this ticket made this seem likely to
me.  Thank you!


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64018>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/