Re: Format inline code

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

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.

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

> 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

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. Perhaps the source is also
  a little harder to understand.
* 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.
 
Thanks,

Michael

>  man7/test_man_format.7 | 132 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 132 insertions(+)
>  create mode 100644 man7/test_man_format.7
> 
> diff --git a/man7/test_man_format.7 b/man7/test_man_format.7
> new file mode 100644
> index 000000000..6fc7ae974
> --- /dev/null
> +++ b/man7/test_man_format.7
> @@ -0,0 +1,132 @@
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Do whatever the heck you want with it.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH TEST_MAN_FORMAT 7 2020-11-06 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +test_man_format \- playground page to test formatting
> +.SH DESCRIPTION
> +Please, modify the source of this page to see the output changes.
> +.SH EXAMPLES
> +.SS .RS/.RE after first .TP paragraph
> +.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
> +.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
> +.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
> +.PP
> +Augue interdum velit euismod in pellentesque.
> +Tristique senectus et netus et malesuada fames ac turpis egestas.
> +Gravida arcu ac tortor dignissim convallis.
> +.IP +4n
> +.EX
> +int
> +main(int argc, char *argv[])
> +{
> +     return 0;
> +}
> +.EE
> +.RE
> +.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.
> +.IP
> +.\" We could use .RS+.PP/.RE here, but as an analogy to C's one-line if's,
> +.\" we could also use .IP for simplicity when there is only one
> +.\" paragraph affected.
> +Augue interdum velit euismod in pellentesque.
> +Tristique senectus et netus et malesuada fames ac turpis egestas.
> +Gravida arcu ac tortor dignissim convallis.
> +.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.
> +.SS .RS/.RE Always
> +.TP
> +HEADW
> +.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
> +.TP
> +HEADW
> +.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.
> +.IP 4
> +.EX
> +int
> +main(int argc, char *argv[])
> +{
> +     return 0;
> +}
> +.EE
> +.RE
> +.TP
> +HEADW
> +.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
> +.SH SEE ALSO
> +.BR man (1),
> +.BR man2html (1),
> +.BR groff (7),
> +.BR groff_man (7),
> +.BR man (7),
> +.BR man-pages (7),
> +.BR mdoc (7)
> 


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