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@xxxxxxxxx>
>> ---
>>
>> 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
