Hi Alex,
On Fri, 6 Nov 2020 at 17:36, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote:
>
> 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?
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 :/
Yeah, I've wondered about a conversion to .rst, but so far I'm not
sure, and also I presume it will take a lot of work.
> >> 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
(Yes.)
> 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.
Yes, I guess one could argue that point too :-).
> 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.
Yeah, I can see the argument.
> > * 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...
queue.3 was the only one that still used 'mdoc' mark-up.
> 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.
So, I am a little bit hesitant about "fix-as-we-go". Possibly, this
means some pages will never be changed. If we were to make the change,
my preference would be to do all pages at once. But I am not fixed on
that idea. Some grepping[1] suggests that the number of pages that
would need to be changed is around 100. Perhaps fix-as-we-go would be
feasible...
I'm still thinking about this one.
Cheers,
Michael
[1] grep -l '\.IP$' $(grep -l '\.RS' $(git grep -l '\.TP' man?)) | wc
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
