Re: Format inline code

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

Hi M,

On 2020-11-06 17:00, Michael Kerrisk (man-pages) wrote:
 > Hi Alex,
 >
 > On 11/6/20 10:38 AM, Alejandro Colomar wrote:
 >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >> ---
 >>
 >> Hi Michael,
 >>
 >> This is not a patch.
 >> But I sent you a full page to better see what we're talking about.
 >
 > Thanks. The "patch" was helpful.
:P

BTW, the thing I tried in the "patch"
of passing a length argument to .IP
is not possible, right?
It would simplify some things.

 >
 >> Here are, as subsections of EXAMPLES,
 >> A (.RS/.RE after first .TP paragraph) and
 >> B (.RS/.RE Always)
 >> from last email.
 >>
 >> As for using .RS/.RE for single paragraphs,
 >> we could do as in C:
 >> {} for multi-line ifs/loops -> .RS/.RE for multiple paragraphs.
 >
 > With the important caveat that {} plus indentation is a lot more
 > visually comprehensible than a .RS/.RE pair.
Agree.  I dislike most if not all markup languages
for being not very easy to read.
Maybe .rst is the only one I kind of like in that sense :/

 >
 >> just indent for single-line ifs/loops -> .IP for single paragraphs.
 >
 > So., I think the choice is really down to something like
 > this:
 >
 > * For .TP with single paragraph, no extra markup
 > * For .TP with multiple paragraphs/examples, I would probably prefer:
 >
 >          .TP
 >          .RS
 >          [paragraphs started by .PP]
 >          .RE
 >
 > rather than:
 >
 >          .TP
 >          [first para]
 >          .RS
 >          [paragraphs started by .PP]
 >          .RE
 >

I'd reword it as:

           .TP
           .RS
           [first para]
           [paragraphs started by .PP]
           .RE

i.e., the first paragraph should not start by .PP.
But I agree on including the first one in the .RS/.RE group
for logic and consistency reasons.


 > But I still wonder, do we want to do this? The advantages:
 >
 > * Consistent use of .PP everywhere.
 >
 > The disadvantages:
 > * A bit more mark-up required.

Agree on that one.

 > * Perhaps the source is also a little harder to understand.

I would argue the other way:

.IP Does too many things: It indents, and it also adds a new paragraph.
It is like .RS+.PP/.RE grouped into one macro.

With the separation into .RS/.RE and .PP,
each macro does one job, and does it well.
So when you see .RS, you know you're moving +1 tab,
when you see .RE, you're moving -1 tab.
and when you see .PP, you're leaving a blank line.

It will be more code (the previous disadvantage),
but conceptually, I think it will be simpler.

 > * What to do with existing pages? Do we convert them? Scripting
 >    will probably help, but still there's probably a decent
 >    amount of work required.

Well, we can change them slowly.

Scripting will probably be difficult,
and maybe it doesn't even fix 50% of the cases,
so it will probably need to be mostly handmade.

But there's no hurry.
It works as it is now, so we can change one page at a time,
and some day all will be fixed.
We had pages with very old markup (queue.3; is there any other?),
until very recently...

For example, when we add new code to a page, we can fix that page.
perf_event_open.2 could be a start;
it also has some other obvious srcfixes,
which could be fixed on the same patch.

Thanks,

Alex

 >
 > Thanks,
 >
 > Michael