From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Alejandro Colomar <colomar.6.4.3@gmail.com>
Cc: "G . Branden Robinson" <g.branden.robinson@gmail.com>,
linux-man <linux-man@vger.kernel.org>
Subject: Re: Format inline code
Date: Sun, 8 Nov 2020 13:22:51 +0100 [thread overview]
Message-ID: <CAKgNAkjsnu9+rxdLgZ5VzYxjFf_c1Ed0JUQ8=KHkK6Qw9X4B-Q@mail.gmail.com> (raw)
In-Reply-To: <387259c5-3051-8058-e99c-b17873fe7187@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/
next prev parent reply other threads:[~2020-11-08 12:23 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-05 10:19 Format inline code Alejandro Colomar
2020-11-05 11:36 ` Michael Kerrisk (man-pages)
2020-11-05 14:59 ` Alejandro Colomar
2020-11-05 21:37 ` Michael Kerrisk (man-pages)
2020-11-05 22:01 ` Alejandro Colomar
2020-11-06 9:38 ` Alejandro Colomar
2020-11-06 16:00 ` Michael Kerrisk (man-pages)
2020-11-06 16:36 ` Alejandro Colomar
2020-11-08 12:22 ` Michael Kerrisk (man-pages) [this message]
2020-11-12 11:32 ` Alejandro Colomar
2020-11-12 21:17 ` Alejandro Colomar
2020-11-13 8:28 ` G. Branden Robinson
2020-11-13 9:00 ` Michael Kerrisk (man-pages)
2020-11-13 9:47 ` G. Branden Robinson
2020-11-13 10:11 ` Michael Kerrisk (man-pages)
2020-11-13 10:21 ` Alejandro Colomar
[not found] ` <fbaf2a56-3f2e-e5ce-6ca2-e8f30156947d@gmail.com>
2020-11-12 21:20 ` Alejandro Colomar
2020-11-12 22:55 ` [RFC v1] perf_event_open.2: srcfix + ffix Alejandro Colomar
2020-11-13 9:21 ` Michael Kerrisk (man-pages)
2020-11-13 10:26 ` Alejandro Colomar
2020-11-13 10:39 ` Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAKgNAkjsnu9+rxdLgZ5VzYxjFf_c1Ed0JUQ8=KHkK6Qw9X4B-Q@mail.gmail.com' \
--to=mtk.manpages@gmail.com \
--cc=colomar.6.4.3@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).