I'm unsure about this. :-)

It doesn't work on macOS for some reason. I hadn't the time to check why yet. (Highlighting the SYNOPSIS section does work.) That's no show-stopper, though.

It works in my Ubuntu VM, but it can lead to highlighting the text between the code blocks as C. (E.g. in printf(3))

So, do we prefer a pretty colorful section or no highlighting at all?

I'm pretty sure it's a syntax syncing issue, but I'm not sure if I'm using syntax sync group[t]here right. grouphere doesn't seem to affect highlighting at all.

If you :syn sync minlines=300, the highlighting consistently works, but that seems like a suboptimal solution. The reason I'm separating out Examples and using grouphere is so that only what needs to be highlighted gets synced. Then again I'm not sure if C syntax highlighting is really that slow.

If performance isn't an issue, the solution would be to add EXAMPLES\= to the SYNOPSIS regex that is already there.

As for the wrong highlighted English in the Example section, I like the highlighted code more than I dislike the bright yellow for and etc. :)

If performance isn't an issue, the solution would be to add EXAMPLES= to the SYNOPSIS regex that is already there.

I'd prefer that over these groupthere hacks. :> I can confirm that it works.

And I have no strong opinion about having colored EXAMPLE sections (including all common text) or not. I hope that someone else decides.

The highlighting in the screenshot is somewhat random. So it looks impressive at a glance, but adds noise to the non-code text.

To avoid false positives, maybe don't highlight lines that start with a Title case string. That might be good enough.

I changed my mind and actually prefer the way the PR currently works now.

Because having an extra syntax group manExample, opposed to adding EXAMPLES\= to manSynopsis, means I can easily disable the syntax highlighting for that section, in case I ever decide not to like the false highlighting of normal text.

I added a slightly conservative sentence match. Here's printf(3) again.
The red highlighting is not from any changes in this PR. I changed my :hi manUnderline to a red color, since I just found out that the script that preprocesses man pages, runtime/lua/man.lua, uses manUnderline. :)

This merge results in slightly odd highlighting for strcat(3).

Before above after:

A short one word sentence added after program source:

On a smaller terminal (without reflowing the manpage):

And sorry for the excessively large pictures I guess, t̶h̶e̶ ̶c̶u̶l̶p̶r̶i̶t̶ ̶i̶s̶ ̶t̶h̶e̶ ̶̶P̶r̶o̶g̶r̶a̶m̶ ̶s̶o̶u̶r̶c̶e̶̶ ̶l̶i̶n̶e̶.̶

@gravndal You mean the "Program source" header isn't highlighted? Otherwise I don't see a problem.

Example code for c++ manpages (e.g std::vector) are located in a section called Example, so that might also be worth including in the syntax region.

@justinmk No meaning that Program source was the line that caused issues with the highlighting, e.g. SEE ALSO not being highlighted, or the C code not being highlighted unless it is out of view (and a syntax update is made/forced). On second review, deleting it doesn't change anything so that was a bit of an early conclusion on my end.

The highlighting of the last line is also somewhat sporadic, though that doesn't have anything to do with this pull as far as I can tell.

@gravndal Your very last screenshot shows what looks like the desired syntax highlighting. If bigger screen or scrolling degrades the experience, it's most likely a syntax performance issue, not related to this PR. you can try:

:syntax sync fromstart

also try CTRL-L .

@justinmk Tried that, it doesn't change anything. What does however is putting the cursor on top of one of the brackets in the example code, the result being highlighting up and until the matching bracket. Doing a CTRL-L or :syntax sync fromstart will then remove the highlighting.

(also tried without my config too rule out anything to do with non defaults, yields the same result)

Can't reproduce. In any case, this PR was a "best effort". As long as it didn't seriously regress anything, please send improvements in the form of a PR. It's not clear from the images if anything seriously regressed.

So playing around with it a bit more, I'd say it's the sentence check. Adding a dot after Program source, or deleting the line and the parenthesis after ... performance.) brings the desired highlighting.

deleting the line and the parenthesis after ... performance.) brings the desired highlighting.

That makes sense. Since a .) shouldn't occur in C code, I'll try adding .) to the pattern.

@Synray it might be best to check if there is a line immediately below the title-cased match. If not, then it's probably not a sentence.

check if there is a line immediately below the title-cased match.

That is way simpler and seems to work better. I made manSentence a region:

  syntax region manSentence start=/^\s\{3,7}\%(\u\|\*\)[^{}=]*/ end=/\n$/ end=/\ze\n\s\{3,7}#/ keepend contained contains=manReference

I also added manLowerSentence:

  syntax match manLowerSentence /\n\s\{3,7}\l.\+[()]\=\%(\:\|.\|-\)[()]\=[{};]\@<!\n$/ display keepend contained contains=manReference

manLowerSentence matches single-line sentence fragments like those in printf(3).

In the example screenshot I highlighted manSentence and manLowerSentence with a brighter background -- manLowerSentence is highlighted with twice the intensity.

And here's strcat(3):

These regions hide manSubHeading, which could be prevented if I only match sentences that start after 7 spaces, by changing the \{3,7} part of the match to \{7}, but I recall seeing sentences indented at 3 spaces in a man page that I forget the name of.

As far as I can tell by the defaults laid out in groff_man(7) the only lines that will have 3n indentation are lines created with the .SS macro (described as subsections in man-pages(7) and sub-subheadings in groff_man(7)). While some subheadings might be quite sentence-like aren't they still subheadings?

described as subsections in man-pages(7)

In that case then they should be highlighted as sub headings. I'll make the change.