Re: [PATCH] Documentation: add initial iomap kdoc

["Theodore Ts'o" <tytso@mit.edu>]

On Thu, May 18, 2023 at 07:51:22AM -0700, Christoph Hellwig wrote:
> On Thu, May 18, 2023 at 07:50:03AM -0700, Luis Chamberlain wrote:
> > On Thu, May 18, 2023 at 07:48:54AM -0700, Christoph Hellwig wrote:
> > > > +**iomap** allows filesystems to query storage media for data using *byte ranges*. Since block
> > > > +mapping are provided for a *byte ranges* for cache data in memory, in the page cache, naturally
> > > 
> > > Without fixing your line length I can't even read this mess..
> > 
> > I thought we are at 100?
> 
> Ony for individual lines and when it improves readability (whatever
> that means).  But multiple to long lines, especially full of text
> are completely unreadable in a terminal.

For C code, if you have really deeply nested code, sometimes it's
better to have some lines which are longer than to have gratuitous
line break just to keep everything under 72-76 characters.

But if you are writing a block of text, and you are expecting people
to read it in a terminal window, I think it is adviseable to wrap at
72 characters.  In fact, some will advise wrapping earlier than that,
to better aid comprehension.  For example:

   "Optimal line length or column width for body text is 40–70
   characters.  When people read, their eyes jump across a line of
   text, pausing momentarily to take in groups of three or four
   words. Studies have shown that readers can make only three or four
   of these jumps (or saccades) per line before reading becomes
   tiring.

   Too long lines with too many words also make it harder for the eyes
   to find the correct spot when they sweep back to the left to pick
   up the next line of text. To maintain readability, it is imperative
   to use moderate line lengths within the range of 40–70 characters.

   Do not set normally sized body text in a single column across a 8.5
   by 11 inch page. If you do that, the result will greatly exceed 70
   characters, reading efficiency will be significantly reduced, and
   your readers’ attention will be easily lost.

   Two column layouts are the best solution for achieving optimal body
   text column widths on American letter size paper. If that is not
   practical and using only one column is necessary, then be sure to
   use large side margins in order to bring the line length as close
   as possible to 70 characters or less."

   -- https://winterpm.com/

Cheers,

						- Ted