Re: Format inline code

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

Hi Alex,

On Thu, 5 Nov 2020 at 15:59, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
>
>
> On 2020-11-05 12:36, Michael Kerrisk (man-pages) wrote:
> > 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.
>
> Hi Michael,
>
> 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.

Thanks,

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