Improve Manpage syntax

[keith-hall]

Fixes #1148
(and also relates to #1213 )

How git push --help looks after these changes when using bat as the pager:

[sharkdp]

Thank you very much! The new man page for git push looks great 👍

Unfortunately, this seems to break C syntax highlighting for man pages like select(2) which look like this, currently:

I hope it's fine that I push a select(2) syntax regression test that should fail on this branch. We don't have to keep this exact style (meaning: it's fine if we have to push a new highlighted/Manpage/select-2.man version) but it would be great if the C syntax highlighting still works.

[sharkdp]

It seems like I can not push to your fork, but you can cherry-pick e1af838 if you want.

[keith-hall]

Well spotted, thanks! It is definitely useful to have these regression tests 👍 I have cherry picked your commit and pushed some fixes. It uses some "heuristics" to determine if it is C code or not - namely presence of a block comment or #include directive - if you know of any man pages where this won't work, please let me know!

(about not being able to push to my fork: sorry about that. I like to keep forks separate from my own repos, so I created a GitHub org for them, but unfortunately GitHub since stopped allowing maintainers push access - it doesn't even show the option when creating the PR. I guess it makes sense because organizations have their own permissions/rules)

[sharkdp]

Well spotted, thanks! It is definitely useful to have these regression tests +1 I have cherry picked your commit and pushed some fixes. It uses some "heuristics" to determine if it is C code or not - namely presence of a block comment or #include directive - if you know of any man pages where this won't work, please let me know!

That sounds great 👍

(about not being able to push to my fork: sorry about that. I like to keep forks separate from my own repos, so I created a GitHub org for them, but unfortunately GitHub since stopped allowing maintainers push access - it doesn't even show the option when creating the PR. I guess it makes sense because organizations have their own permissions/rules)

No worries. You can also create branches in this repo, if you prefer that.

[sharkdp]

Thank you very much for the improvements and the detailed tests!

[sharkdp]

There's actually a large C code block at the bottom of select(2) which is not highlighted (was not highlighted before either):

EXAMPLES
       #include <stdio.h>
       #include <stdlib.h>
       #include <sys/select.h>

       int
       main(void)
       {
           fd_set rfds;
           struct timeval tv;
           int retval;

           /* Watch stdin (fd 0) to see when it has input. */

           FD_ZERO(&rfds);
           FD_SET(0, &rfds);
…

Should that have been highlighted by your change? If not, that's also fine.

[keith-hall]

It shouldn't have been - I didn't notice it and didn't change under which sections it applies. I have now pushed a new commit to the manpage-improvements branch addressing this.
There are a few changes in the regression test which I wasn't expecting, however, like
e0b7b80#diff-c601da59bcdb7dd775083ccc40783338d94e9d2ed4fefc316b698189e654addfL149

[sharkdp]

There is a "visual diff" in the GA output: https://github.com/sharkdp/bat/runs/1268838933?check_suite_focus=true

Can't really tell why these changes happen though.

I guess the manpage syntax will always stay on a "best effort" basis, as there is no well-defined "syntax", to my knowledge. So I guess I'm fine with most changes (even if there are a few regressions) as long as there is an overall improvement.