Re: Format inline code

Alejandro Colomar
2020-11-05T22:01:29Z

On 2020-11-05 22:37, Michael Kerrisk (man-pages) wrote:
>> On one hand, yes, it adds some lines of markup, i.e., a bit of noise.
>> On the other hand, I just see .RS/.RE as {/} in C scopes:
>> they clearly delimit logic blocks of text,
>> and also help in greatly reducing the quantity of .IP needed,
>> needing only .PP for most things, which simplifies logic.
>>
>> Choose your poison :p
>
> So, suppose we change this. Really, what I should have written is:
>
> [[
> .TH xxx 2 yyyyy zzzzz
> .TP
> XXXXXXXXXX
> .RS <----- I moved this .RS
> 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.
> .PP
> .RS +4n
> .EX
> int
> main(int argc, char *argv[])
> {
> return 0;
> }
> .EE
> .RE
> .RE
> ]]
>
> So, any time we have a .TP block that might have inline code (or
> perhaps just multiple paragraphs), then the proposal is that we write
>
> [[
> .TP
> HEADWORD
> .RS
> ...
> .RE
> ]]
>
> But, what about the .TP blocks that contain just a single paragraph
> and no inline code? Do we omit the .RS/.RE? That's a little
> inconsistent and possibly confusing. On the other hand, if we add the
> .RS/.RE to such blocks, that's a lot of clutter. Do you see what I
> mean? It looks like there's no simple answer here.

Hi Michael,

I was just thinking about that.

.TP has a special feature:

The paragraph right after .TP will start on the same line as the TP (if
the HEADWORD is short enough), and therefore, it doesn't even use .PP.

So it is like this (A):

[[
.TP
HEADW
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 <----- I moved this .RS
.PP
Augue interdum velit euismod in pellentesque. Tristique senectus et
netus et malesuada fames ac turpis egestas. Gravida arcu ac tortor
dignissim convallis.
.PP
.RS +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.RE
.RE
]]

[[
HEADW 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.

Augue interdum velit euismod in pellentesque.
Tristique senectus et netus et malesuada fames ac turpis egestas.
Gravida arcu ac tortor dignissim convallis.

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

For cases with no inline code and a single paragraph,
you don't need anything at all.
For cases with 2 paragraphs or more you would start using .RS/.RE.
Yes, that's inconsistent... and I don't see a clear solution to that.

Or you could do like in system_data_types.7,
where we used .RS just after the .TP.
The difference is that in that case you force a newline,
so the first paragraph will
always start on the line after the HEADWORD (B):

[[
.TP
HEADW
.RS <----- I moved this .RS
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.
.PP
Augue interdum velit euismod in pellentesque.
Tristique senectus et netus et malesuada fames ac turpis egestas.
Gravida arcu ac tortor dignissim convallis.
.PP
.RS +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.RE
.RE
]]

[[
HEADW
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.

Augue interdum velit euismod in pellentesque.
Tristique senectus et netus et malesuada fames ac turpis egestas.
Gravida arcu ac tortor dignissim convallis.

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

In case of just one paragraph (A):

[[
.TP
HEADW
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.
]]

[[
HEADW 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.
]]

Or (B):

[[
.TP
HEADW
.RS <----- I moved this .RS
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.
.RE
]]

[[
HEADW
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.
]]

Do you like any of them?

Thanks,

Alex

>
> Thanks,
>
> Michael
>