build: Generate man page with fixed program name

[Explorer09]

Two commits:

• Use a more portable expression for the 'flex.1' man page on flex program.
• Fix the program name for the man page generation.

See the commit descriptions for details.

[westes]

I think I'm okay if we end up including the $(EXEEXT) on platforms where that is not empty. I don't like copying the executeable in. It isn't guaranteed to work on platforms where $(EXEEXT) is not empty and clutters up the working directory. I'm making adjustments and will get it onto master shortly.

[Explorer09]

@westes

I think I'm okay if we end up including the $(EXEEXT) on platforms where that is not empty. I don't like copying the executeable in. It isn't guaranteed to work on platforms where $(EXEEXT) is not empty and clutters up the working directory.

The is a reason for copying the executable into the working directory. Personally I want this to work portably, but there isn't an easy way to override the program name (the argv[0] when invoking the program) in the help2man framework. So a temporary file has to be used.

Note that in the help2man invocation, the ./flex program name is without $(EXEEXT) suffix. This is intentional so that the suffix won't get in the way of generating the man page. (Windows knows what program to invoke as it has the PATHEXT environment variable that specifies the extensions to search for.)

I was also tempted to delete the temporary flex program as soon as the man page is generated, but I decided against that as that would unnecessary complicates the command line in the flex.1 target, and that the file has to be cleaned up within make clean target anyway.

[westes]

(Windows knows what program to invoke as it has the PATHEXT environment variable that specifies the extensions to search for.)

Now that you remind me that all the $(EXEEXT) stuff is because MSWindows has nonstandard behavior, I have a couple questions:

• On MSWindows, what is wrong with having a flex.exe.1 manpage? (Does it not work if someone does "man flex" or whatever one does on MSWindows)?
• What breaks if we simply drop the $(EXEEXT) stuff altogether? I suppose the help2man invokation fails.

and that the file has to be cleaned up within make clean target anyway.

It would also need to be listed in .gitignore. to prevent cluttering of the working tree.

I suppose the thing we actually want is to be able to tell help2man that the thing to call the manpage is flex.1, not flex$(EXEEXT).1. Which actually seems like a pretty common usecase (given that some programs can be called by multiple names).

[Explorer09]

• On MSWindows, what is wrong with having a flex.exe.1 manpage? (Does it not work if someone does "man flex" or whatever one does on MSWindows)?

I don't maintain any Windows package for FOSS tools, so I cannot say this for sure, but I can guess one behavior can happen:

If flex man page is installed as "flex.exe.1" in the "man1" directory, then "man 1 flex" might not find the man page we want, but we are likely need to invoke as "man 1 flex.exe" instead.

This might not be a bug in a man program, because Unix/Linux utilities can have suffixes such as fsck.ext4.

And the question you asked is a non-issue because...

I suppose the thing we actually want is to be able to tell help2man that the thing to call the manpage is flex.1, not flex$(EXEEXT).1.

help2man --output option already did the right thing of fixing the output file name to "flex.1".

• What breaks if we simply drop the $(EXEEXT) stuff altogether? I suppose the help2man invokation fails.

I have no idea, but according to a source code of help2man (unofficial mirror; not the latest version), it invokes (for each $_ in { "help", "version" } ) `$ARGV[0] --$_ 2>/dev/null`, and so on Windows if flex does not have the .exe suffix, help2man might not be able to find it.

It would also need to be listed in .gitignore. to prevent cluttering of the working tree.

Good call. May I submit a PR for this?

[westes]

Wait.

We set the name of the man page. We tell help2man what program to use to generate the man page.

Why are we copying the executable in the first place?

[Explorer09]

@westes

We set the name of the man page. We tell help2man what program to use to generate the man page.

Why are we copying the executable in the first place?

The "Usage" string of the program or the "Synopsis" section of the man page depends on the program name invoked.

Sometimes the program is expected to be invoked with multiple names, e.g. test and [, and for those programs, the base name may be hard-coded in the help string.

For programs like make, this might not be the case, for example GNU make may be available as gmake and not make in a distro, and so the program name there in the "Usage" string will use argv[0] provided (not static). Flex is like this latter case, but flex is installed as flex (maybe also flex++ as a symlink), so we shouldn't generate a man page with "stage1flex" as the program name. That is simply wrong.

[Explorer09]

@westes I have a CI build log that demonstrated the issue: https://github.com/Explorer09/flex/actions/runs/8915179838

Here I have a "build" and "cross-build" configurations, look at the last step of both workflows and compare the generated man pages. Note that the stage1flex name is slipped into the generated man page file in the "cross-build" workflow.