Re: Format inline code

Michael Kerrisk (man-pages)
2020-11-05T11:37:13Z

Hi Alex,

On Thu, 5 Nov 2020 at 11:19, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hey Michael,
>
> I tried to reply to the old thread where we talked about it,
> but I couldn't find it.

I think it was p[robably in the thread that starts here:
https://lore.kernel.org/linux-man/f70c7f62-9d61-71aa-67cf-43501a29bccc@gmail.com/

> I think it was in a thread of some patch for system_data_types,
> so I didn't know how to filter for it :/
>
> So let's start a clean thread for that.
>
> Currently, man-pages(7) proposes:
>
> =================
> .PP
> .in +4n
> .EX
> int
> main(int argc, char *argv[])
> {
> return 0;
> }
> .EE
> .in
> .PP
> =================
>
> I think you said that it doesn't always work.
>
> I don't agree with that:
> If you correctly use .RS/.RE instead of misusing .IP,
> I think it will work always.
>
> I mean, if you have a block that is indented,
> I propose to use .RS/.RE for the whole block,
> instead of .IP for every paragraph
> (if you use .IP, then yes,
> that construct needs to be modified to use it too).
> An implementation of what I mean is system_data_types.7.
>
> If you think it would still fail in some scenario,
> please show me.
>
> Another problem of that construct is that it uses naked .in.
> I agree with it.
>
> How about the following?:
>
> =================
> .PP
> .RS +4n
> .EX
> int
> main(int argc, char *argv[])
> {
> return 0;
> }
> .EE
> .RE
> .PP
> =================
>
> I don't know if that syntax is correct,
> but I tried it, and it seems to work.
>
> AFAIK, it will _always_ work
> as long as blocks are correctly indented using .RS/.RE,
> and it uses man macros only.

So, suppose I want to produce output as follows, where XXXXXXXXX is
the start of a hanging list (.TP):

[[
xxx(2) System Calls Manual xxx(2)

XXXXXXXXXX
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.

int
main(int argc, char *argv[])
{
return 0;
}

zzz yyy xxx(2)
]]

The way I currently produce that is markup something like:

[[
.TH xxx 2 yyy zzz
.TP
XXXXXXXXXX
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.
.IP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
]]

Downside: in the above, I need to know whether to use .IP or .PP,
depending on whether I'm currently in an indented text block.

I think you are suggesting that instead, I could do something like:

[[
.TH xxx 2 yyyyy zzzzz
.TP
XXXXXXXXXX
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.
.RS
.PP
.RS +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.RE
.RE
]]

I agree that this works, and has the virtue that I can consistently use

.PP
.RS +4n
.EX
...
.EE
.RE

everywhere. The downside is that I have to add an extra .RS/.RE pair,
and that's quite a bit of mark-up to add each time (to a construct
that is already quite mark-up heavy). I don't totally object to the
extra mark-up, but it would be nice if there was a way to accomplish
the desired result (consistent mark-up everywhere) without requiring
su much mark-up.

Thanks,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/