Name "delta" clashes with a POSIX-standardized legacy VCS tool🐛

[vrza]

Problem: The program name delta clashes with a legacy tool from the SCCS package, which is part of the POSIX standard. The Linux man-pages project ships the man page for this legacy tool, so users typing man delta will be presented with a mismatching man page.

Solution: Use an unambiguous name for the program binary, e.g. git-delta.

[dandavison]

Hi @vrza, there's a related discussion here about what would be needed to get delta into Debian/Ubuntu: #26

It's a bit confusing -- I thought the binary name "delta" was taken in Debian by something called swap-cwm, but you've now pointed out a second clash with a different legacy tool! How did swap-cwm get delta into Debian if it was already taken by SCCS?

In any case, and I hope this doesn't sound stubborn, or thoughtless, but no-one nowadays uses this SCSS thing, right? I don't think anyone should have to take into account unused historical projects from the 1970s when naming their binaries. So, I don't have any intentions to change the name of the delta binary: it causes problems for hardly anyone. But if Debian/Ubuntu does include delta, they may of course choose to do so with a different executable name. That would be a bit unfortunate, because it will not match the public documentation, and won't be the executable name that users of other Linux and non-Linux systems use, but it seems like quite a common fate. For example bat is installed as batcat on Debian/Ubuntu for a similar reason: sharkdp/bat#982)

[vrza]

How did swap-cwm get delta into Debian if it was already taken by SCCS?

They only checked for explicit filesystem namespace clashes.

Debian ships GNU CSSC, which installs delta as:

/usr/lib/x86_64-linux-gnu/cssc/delta

The cssc package doesn't install a delta man page.

swap-cwm installs:

/usr/bin/delta
/usr/share/man/man1/delta.1.gz

manpages-posix installs:

/usr/share/man/man1/delta.1posix.gz

I don't think anyone should have to take into account unused historical projects from the 1970s when naming their binaries.

The most recent version of GNU CSSC at the time of this writing -- 1.4.1 -- was released in May 2019. Activity on the mailing list is sporadic, but it seems that there are people who use it, at least in order to convert legacy source repositories to more modern version control systems.

I also found this nugget of information on the CSSC mailing list:

There however is the original SCCS source available as true OpenSource
since December 2006 and it is actively used and maintained.

SCCS is 10x to 50x faster than CSSC and added a lot of new and interesting
features during the past 12.5 years of being OSS.

So it seems that SCCS is actively maintained as well, the last stable version at the time of this writing -- 5.09 -- was released in February 2019. And I thought Emacs had a track record -- this software will be 50 years old next year and still has people maintaining it!

So, I don't have any intentions to change the name of the delta binary: it causes problems for hardly anyone

It causes a problem / confusion for every Linux user that has it installed on a system that also has manpages-posix installed and tries to get help by typing man delta. I'd say that's a very large number of users.

The man page clash is not specific to Debian -- pretty much every Linux distribution uses the same upstream man-pages. You can try convincing the man-pages people to start excluding from their distribution these POSIX tools that are not commonly installed nowadays. Or, make and distribute your own delta(1) man page -- still clashing with swap-cwm, but both take precedence over the delta(1p) man page.

Frankly, delta is a common word in science/engineering, and it seems reasonable to expect that there would be existing tools with that name. Did you check for similarly named software tools (especially ones covered by technical standards) before deciding on how to name your tool?

[dandavison]

Wow, OK perhaps I was a bit unfair to SCCS -- 50 years and still being maintained is very impressive.

Frankly, delta is a common word in science/engineering, and it seems reasonable to expect that there would be existing tools with that name. Did you check for similarly named software tools (especially ones covered by technical standards) before deciding on how to name your tool?

Open source software is written by people in their spare time, for free, but most of all for fun. People do this because they enjoy it. When I started writing delta, I had no moral, technical, or aesthetic obligation to investigate whether the name had ever been used by a project with a man page. I knew that "delta" wasn't a standard Unix command or executable from a well-known package. Beyond that, it was just me starting to write a Rust CLI program for fun, in order to learn Rust.

[vrza]

This is a straw man argument: the author closed the ticket arguing that they had no obligation to prevent the issue from occurring in the first place, as if this were an argument that the issue itself does not exist.

[dandavison]

This is a straw man argument: the author closed the ticket arguing that they had no obligation to prevent the issue from occurring in the first place, as if this were an argument that the issue itself does not exist.

Not at all. I closed the ticket because I am not aware of any bug revealed by the discussion in this ticket, and therefore there is no further action to take on this ticket. If you are aware of a bug, please explain what it is.

Problem: The program name delta clashes with a legacy tool from the SCCS package, which is part of the POSIX standard. The Linux man-pages project ships the man page for this legacy tool, so users typing man delta will be presented with a mismatching man page.

I don't see a bug there. Delta is available to anybody in any country in the world. Linux is just one category of operating system on which Delta can be installed. It is not the case that software project X clashing with some obscure Linux man page constitutes a bug in software project X. There might be an argument that it indicates a bug in the linux distribution for not being able to handle installation of software with clashing executable names / man page names.

Furthermore, I am unaware of a way to check for name clashes with any package in any operating system / distribution commonly used anywhere in the world. I tend to spend most of my time in English-speaking computing communities, but there may be Arabic/Chinese/Russian etc distributions containing clashing executable names / man pages.

[vrza]

If you are aware of a bug, please explain what it is.

It's a usability / user experience issue.

I already explained it in this same thread here, and I offered three possible paths to resolution that are not mutually exclusive, one here, and two more here.

Here is a short summary of the above:

Issue: on systems where this tool is installed, typing delta will run this tool, while typing man delta will either display documentation for a different tool, or no documentation at all. This results in poor user experience that is not consistent with other tools. As an example/reference, we can look at related git tools such as git-diff, git-apply etc. -- as good citizens in the land of *nix CLI tools, they are all distributed with documentation in the form of matching man pages, and their names are prefixed with git- to indicate that they are integrated with git and at the same time avoid name clashing with similarly named tools.

Proposed solutions:

1. Ship a man page in section 1 with the tool -- this would improve the user experience, as man pages are a standard way to access reference manuals on *nix systems.

2. Rename the tool to e.g. git-delta, or perhaps even something that more clearly indicates that this is a "pretty printing" tool specific to git. This would:

2a) make the name more consistent with other aforementioned tools specific to git (git-diff, git-apply etc.);
2b) be a sign of respect towards the legacy and heritage of Unix, version control and open source tooling -- the original delta tool and its innovative interleaved deltas / "SCCS weave" method of storing file revisions was influential in the development of later VCS tools and was adopted as an industry standard together with the rest of the SCCS tool suite; and at the same time
2c) resolve all extant name clashes.

3. Convince the maintainers of man-pages-posix to stop shipping the delta(1p) man page. I wouldn't recommend this approach but I'm including it for the sake of completeness, as it would serve to resolve the issue.

[Kr1ss-XD]

FWIW I'd argue that it's not the devs' but the package maintainers' job to prevent/circumvent this kind of conflicts.

Upstream developers can't be supposed to know or research about all possible environments an application could run in.

It might be more sensible to direct this proposal towards the distribution, or even better the maintainer themselves.

[vrza]

Writing man pages, or any other general user documentation for an active software project, should most certainly not be the job of package maintainers.

[SuperSandro2000]

Not every piece of software provides a man page. Where it was necessary enough Distros like Debian just wrote their own man page or converted --help to a man page.

Renaming a binary in a distro is a very easy task to do. If not your packaging system sucks.

cssc ships the binary under /usr/lib/x86_64-linux-gnu/cssc/delta which is not a problem because because it is not on the PATH and shouldn't clash with /bin/delta. If it does clash then prepend the binary directory to the PATH which should be done anyway. Also cssc is some legacy software which only very few people will use in combination with delta. Nothing to worry about IMO.

[vrza]

Where it was necessary enough Distros like Debian just wrote their own man page or converted --help to a man page.

It seems that maintainers of this project refuse to ever create a man page, and hold the opinion that this is the job of downstream distributions.

This, among other things, implies on every upstream documentation change, either:

• duplication of effort downstream, where multiple downstream package maintainers are individually manually assembling man pages, or
• downstream maintainers assembling a package by combining upstream with parts of some other distribution package

That doesn't make much sense to me, nor I have heard that such practices are widespread.

Can you provide such examples of projects that are actively maintained upstream, for which downstream distributions maintainers are maintaining man pages themselves?