Re: Format inline code

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On Fri, 6 Nov 2020 at 17:36, Alejandro Colomar <colomar.6.4.3@gmail.com> 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@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?

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/