Update documentation on lesskey paths & fix OS/2 lookup

[ralish]

The man page documentation on where less looks for a user's lesskey file is out of date for all systems except Unix-like. This PR documents the correct locations for Windows, MS-DOS, OS/2, and OS-9 systems and improves the presentation.

While updating the documentation I noticed a bug in the code when running on OS/2. less truncates the first character when looking under the XDG_CONFIG_HOME and .config paths in the user's home directory. That's correct where the default lesskey file has a leading . or _, but OS/2 is the exception as it uses lesskey.ini. The fix ensures on OS/2 that lesskey.ini is used with these paths instead of esskey.ini.

I'm not sure if OS/2 is in practice a supported platform anymore (or MS-DOS and OS-9 for that matter), but since the code and documentation are still present I've included them.

Note: Slightly larger diff is due to trimming unnecessary end-of-line whitespace in modified files.

[avih]

This PR has 3 kinds of changes:

1. Some OS/2 changes.
2. No-op changes, typically removing space from the end of the line (in both source code and manpage).
3. Actual docs changes.

I suggest individual commits for these 3 parts, and maybe consider skipping the no-op changes completely (depending on what @gwsw prefers). Either way, it's generally preferable to separate no-op changes from real changes, for the sake of easier-to-navigate history log and bisections.

Regarding the OS/2 changes, while I'm not familiar with this code, maybe an alternative approach would be to skip the 1st char depending on whether it's dot or underscore rather than depending on whether compiling for OS/2 or not?

[gwsw]

Yes, I would prefer to omit the whitespace changes. They unnecessarily clog up the change history and make it harder to see what's really changed. The diff is 86 lines with the whitespace changes omitted and 813 lines with the whitespace changes included.

The OS/2 (lesskey.ini) changes and the doc changes look fine so they can be combined in a single commit.

[ralish]

No problem, I've updated the PR removing all the whitespace changes.

[ralish]

And further squashed into a single commit as requested.

[gwsw]

Thanks. The only issue I see is in the two calls to dirfile(), you are passing &def_filename as the second parameter. Shouldn't that just be def_filename? It seems like you're passing a const char ** as a parameter which is expected to be a const char *. I don't have an OS/2 system to test on, but I'm surprised that this runs correctly, or even compiles.

[ralish]

I think you're right. A silly mistake on my part. I also don't have an OS/2 system available (they're pretty hard to find these days!) but for unrelated reasons I've been meaning to get one setup.

Let's hold merging this for a week or two and I'll see if I can get something running. I'm curious to see if less compiles even absent these changes. I can't help but wonder when was the last time someone tried to compile less for OS/2 (or MS-DOS for that matter).

[ralish]

Update: I setup an OS/2 Warp 4.52 system and the current less source is broken independent of this PR (not entirely surprisingly). While I was at it I also looked at the DOS build with MSVC and it's also broken. I've managed to fix all the issues for both and get them compiling cleanly with various improvements so less lives again on both MS-DOS, OS/2, and compatibles. I'll tidy-up my tree and submit some separate PRs for your review, after which I'll rebase this PR.

[avih]

less lives again on both MS-DOS, OS/2

Please describe which exact compilers were used - and where to get them from. These are very old platforms, and others need to know what and how in order to build them, or else it can't be maintained.

[ralish]

I'll make sure everything is documented. The very short version for your reference is emx+gcc 0.9d-fix4 for OS/2 (the last EMX release) and Microsoft Visual C++ 1.52 for MS-DOS (the last version that can target MS-DOS).

[avih]

Microsoft Visual C++ 1.52 for MS-DOS

Are you aware that this is a 16 bit compiler? e.g. int is 16 bit, and I don't know whether there are 32 bit types. Available ram is 64K I think (unless various extenders are used - but I don't think this compiler uses them).

It's a very limited platform, and I don't know how much current less can actually work reasonably in such setup.

Also, there's already a working DOS build using DJGPP, which should build out of the box. This is 32 bit build, and it does use one of those DOS extenders.

[ralish]

Yes, am aware that it's a 16-bit compiler. 32-bit types work just fine, it's only pointers that are 16-bit. Available RAM is 1MB (20-bits), but in practice is 640KB (conventional memory) minus other resident applications, so usually around 550-600KB. So still very constrained, but a lot more than 64KB (which agree, would be unworkable). From the testing I've done it does work fine, but I haven't tried it with "large" files (100's of KB).

Are you sure DJGPP works? I was going to test it at some point, but given MSVC was broken I have no expectations around DJGPP. Having a 16-bit native build still has (retrocomputing) value given it works on everything MS-DOS does. The 32-bit build sets the baseline at an 80386 and depends on a DOS extender to be clever about memory management.

[avih]

Are you sure DJGPP works?

It did build not long ago, but I didn't test recently, and there were also some djgpp fixes in recent times (check the less git history). It's easy to install a DJGPP cross compiler, build "less", and run it (I tested in dosbox - not real dos).

[avih]

The 32-bit build sets the baseline at an 80386

Your DOS fixes sets the same baseline cc9d963 So I don't really see the value in 16 bit build.

Not saying it shouldn't be supported, but I don't think the DJGPP build limits the usefulness of the build compared to your suggested 16 bit build.

[avih]

Available RAM is 1MB (20-bits), but in practice is 640KB (conventional memory) minus other resident applications, so usually around 550-600KB

Your DOS fixes include compressing the binary, but typically decompression is to RAM.

So if we start with sub-600K heap, then the decompressed image will eat about 250K of that (judging by the commit message) before less even starts.

I'd think 250K ram usage is not worth the 40K binary size deduction in this scenario.

[ralish]

Your DOS fixes sets the same baseline cc9d963 So I don't really see the value in 16 bit build.

Smaller binary, faster program, no DOS extender dependency, works within the limits of the DOS memory model. As noted in the Makefile, it can be trivially disabled by someone who genuinely wants pre-386 compatibility. On balance, my calculation is that given how uncommon lack of 32-bit instruction set support is, it's more useful to default it on than off.

I'd think 250K ram usage is not worth the 40K binary size deduction in this scenario.

I don't really understand what you're saying here. The size of the binary isn't a 1:1 correspondence to the size in memory, and the compression here is multi-faceted. It's not at all the same as, for example, decompressing a Zip file. It's packing the binary by optimising the load-time relocation table and removing sequences of repeated bytes. So there's certainly some overhead, but it's not analogous to having to decompress the entire thing in memory side-by-side.

Granted, I haven't measured the precise memory overhead, but from my own testing it works just fine. As with the 386 instruction set usage, it can of course be trivially disabled by anyone in the Makefile.

[avih]

It's not at all the same as, for example, decompressing a Zip file.

I'm not familiar with this specific exe-compression, which is why I said that AFAIK it's typically decompressed in RAM. I think like UPX. I assumed it's similar here, but indeed it's possible that this doesn't work that way, which is why I asked.

Granted, I haven't measured the precise memory overhead

Would that be possible? IIRC there's some library function which is able to report the available heap size?

If yes, would you be able to use that function early in main in less, with and without the compression, and report back the heap size with and without it? Thanks.

Also, unrelated, would you mind sharing your VCVARS.BAT content? I have the ISO and the files are accessible, but I've only extracted it without installing. It does seem that it's enough to set the LIB and INCLUDE env vars correctly, but it would still be useful to know how that file looks like.

Speaking of which, why are INCDIR and LIBDIR required at Makefile.ds? wouldn't it be enough to set LIB and INCLUDE via VCVARS.BAR, and then let the compiler use those instead of using the absolute paths as specifiled at the makefile?

[ralish]

Would that be possible? IIRC there's some library function which is able to report the available heap size?

Unsure if this is possible, but happy to look into it. Will get back to you on that front.

Also, unrelated, would you mind sharing your VCVARS.BAT content? I have the ISO and the files are accessible, but I've only extracted it without installing. It does seem that it's enough to set the LIB and INCLUDE env vars correctly, but it would still be useful to know how that file looks like.

It's very minimal as it turns out:

@echo off
set TOOLROOTDIR=C:\MSVC
set PATH=C:\MSVC\BIN;%PATH%
set INCLUDE=C:\MSVC\INCLUDE;%INCLUDE%
set LIB=C:\MSVC\LIB;%LIB%
set INIT=C:\MSVC;%INIT%

Speaking of which, why are INCDIR and LIBDIR required at Makefile.ds? wouldn't it be enough to set LIB and INCLUDE via VCVARS.BAR, and then let the compiler use those instead of using the absolute paths as specifiled at the makefile?

Good pick-up given the above. Yes, we can just use those. To be honest I just kept them in the Makefile and continued to use them as they were present in the original file. It's arguably a bit clearer having them present, but the expectation is that you've run MSVCVARS.BAT in the shell environment before building. I've removed INCDIR and LIBDIR from Makefile.dsu, as well as CC as it's always going to be cl so the indirection gains effectively nothing. Changes are in this commit on the DOS branch and the OS/2 PR has been rebased onto it. There's an updated nmake.log attached to the PR as well.

[avih]

Thanks for the vcvars file.

I've removed INCDIR and LIBDIR from Makefile.dsu, as well as CC as it's always going to be cl so the indirection gains effectively nothing.

Personally I think I'd have removed LIBDIR and INCDIR but kept CC. But let's see first what @gwsw thinks of this whole dos changes thing.

FWIW, personally I don't think it's worth going forward with that. It's not just one or two small bits, and this is for 40 years old OS which has not been supported for almost that much, and which can still be served by djgpp too, which is a lot closer to posix/win32 than pure dos - and it's already working, or at least has been not too long ago. I don't think the additional requirements for an extender and at least 386 are too steep in these circumstances, to be honest. Though I'm not the one making this decision.

Can't speak about OS2, and didn't try to look at those changes. If it's only what was here originally (that first char thing), then it's trivial and would probably be fine, but if you added more things around, dunno.

Also, as already stated by the maintainer:

Yes, I would prefer to omit the whitespace changes.

I know you touched some git meta files to help with that, but personally I'm still not in favour of them.

[ralish]

FWIW, personally I don't think it's worth going forward with that. It's not just one or two small bits

Isn't it? The changes outside of the DOS-specific Makefile and defines are tiny and have zero impact on other platforms. So from a risk perspective, it's practically zero. This was very much intended.

I don't really understand the cynicism to be honest. The codebase is full of support for plenty of other ancient platforms, so I figured I'd make a good faith attempt to make some of them work again given all that's required are minor tweaks and tidy-up. It's fun from a retro-computing perspective, and seeing as the support is already there in the codebase, just neglected, it seemed nice to fix it. This was about fixing code that's already present, not adding new code for older operating systems.

I know you touched some git meta files to help with that, but personally I'm still not in favour of them.

I don't mind either way, at the end of the day it's just a contribution to tidy-up the codebase. The objection as I read it was that it contaminates the diff with actual changes interspersed with whitespace changes, which I completely understand. Hence doing it in a single commit and codebase wide so it doesn't have that downside. The end result is just a tidier codebase.

[avih]

FWIW, personally I don't think it's worth going forward with that. It's not just one or two small bits

Isn't it? The changes outside of the DOS-specific Makefile and defines are tiny and have zero impact on other platforms. So from a risk perspective, it's practically zero. This was very much intended.

It's possible. I didn't look very closely at most of them, but I did see there are a lot of them.

I don't really understand the cynicism to be honest. The codebase is full of support for plenty of other ancient platforms

I don't think I was cynic. It's a personal opinion - and not the one which counts.

Yes, older OSs support code does exist, but I don't know how much of it is actually working or tested. For instance, I don't know when was the last time someone tried to compile current "less" for Sun OS SVR4, or much more obscure platforms, and none of it was added recently.

I'm guessing it does compile for illumos (continuation of Open Solaris) and the current Oracle-Solaris thing, because these are largely maintained.

I also feel that 16 bit platform/compiler has to have some gotchas which we might not notice immediately, and which might require further changes if supported. Admittedly I don't have experience or knowledge with that, but that's my hunch.

I figured I'd make a good faith attempt to make some of them work again given all that's required are minor tweaks and tidy-up. It's fun from a retro-computing perspective, and seeing as the support is already there in the codebase, just neglected, it seemed nice to fix it. This was about fixing code that's already present, not adding new code for older operating systems.

Yes, it does look like a good effort, and I can appreciate that - I do. I also value the magic which is supporting such a big project on such platform - in 2026. But I still don't think it's worth adding/fixing 16 bit code support today to such a big project. My main concern is not even the current changes. It's more what it might require in the future from a maintenance point of view.

It's a bit of FUD on my side, but weighting the pros and cons, and considering this platform is already supported currently (djgpp), even if with slightly steeper requirements, if it was my decision then I'd probably drop 16 bit dos support instead of fixing it.

at the end of the day it's just a contribution to tidy-up the codebase.

Again, not my decision to make, but personally I'm not in vavour of general code tidying up by contributors. It's something the maintainer might want to do sometimes, but I've not seen many projects too thrilled about such incoming patches/PRs.

But I'm not making this decision, so it's just an opinion.

[ralish]

It's a bit of FUD on my side, but weighting the pros and cons, and considering this platform is already supported currently (djgpp), even if with slightly steeper requirements, if it was my decision then I'd probably drop 16 bit dos support instead of fixing it.

I think that's the crux of it. I submitted the PRs because given the support is present in the codebase I assume it's supposed to work, and the PRs make the required changes to make it work as intended and compile cleanly. If the decision is made by @gwsw to remove support entirely I would personally feel that's a shame given it's present and works with these changes (and the effort I put in was then a waste of time), but that's still the better call than having broken/dead code in the codebase.

If that's the decision, there's a bunch of other code that's probably a strong candidate for removal as well. The various Borland C code paths and OS-9 support are probably both worth considering.

[gwsw]

Regarding support for ancient OSes like MS-DOS, OS-9, etc., I'm reluctant to deliberately remove support just because I can't easily test them. On the other hand, I can't realistically keep the support up to date without being able to test them. The approach I've been using is to rely on other people who are actively using those systems to provide necessary patches if something breaks. Realistically, this means there may be periods of time when particular systems are unsupported.

I'm inclined to continue half-heartedly supporting them as I've been doing. So I'll probably integrate the current patches from @ralish. The only issue is the whitespace changes which have returned in all the recent patches. Each of the four latest PRs include the whitespace changes, so it will take me more time than I would like to work my way through the diffs to see what changes are really relevant. I'll probably defer this to after the current beta cycle.

[ralish]

The only issue is the whitespace changes which have returned in all the recent patches.

@gwsw I can remove these if you'd prefer. While I find their removal makes the codebase cleaner and removes distractions, especially due to my own mental quirks, you're the maintainer so it's ultimately up to you. The whitespace changes are mostly localised in a single commit in the first PR, so if you were to review the commits in that PR individually, once it's merged the remaining PRs will be easier to read a consolidated diff of as they're each stacked on top of the other. Alternatively you can fetch the branches and diff the changes between each locally using git diff to easily get the view in advance of merging anything.

One important note is that the subsequent commit after the bulk whitespace changes introduces the .git-blame-ignore-revs file which references the previous commit SHA. So if the branch can no longer be merged by fast-forward it must be rebased and the commit SHA updated. Otherwise the .git-blame-ignore-revs file will be incorrect. Once merged it will be fine unless there's a force push that rewrites history prior to that commit hash (extremely unlikely). I'm happy to rebase the branches when/if needed if more commits are introduced to master before they're merged.

On the other hand, I can't realistically keep the support up to date without being able to test them.

Are there specific things you'd like to see implemented if feasible to make this less of a burden on yourself? For example, would you like to automate building for some of these older platforms in CI and running the test suite if it were possible?

[gwsw]

Yes, it would be helpful to remove the whitespace changes from all the PRs. I don't think that such cosmetic changes should be bundled with functional changes; it just confuses the history and makes it harder to evaluate changes. Frankly, I'm not sure that the whitespace changes are of much use at all; IME there are very few cases where trailing whitespace makes any difference.

I know very little about CI, but I think it would be quite useful if it were possible to add automatic builds for some of the rarer environments, like MS-DOS/VC, MS-DOS/Borland, OS/2, OS-9, etc. I have no idea if this is easy or even possible.

[ralish]

Yes, it would be helpful to remove the whitespace changes from all the PRs.

I've removed almost all the whitespace changes and the .git-blame-ignore-revs file (no longer needed). The only whitespace changes left are in the files I've thoroughly reworked, like the MSVC makefile. All four branches have been rebased on latest master changes. The PRs are still stacked, so the changes in the second PR include the changes in the first PR, and so on, so I still recommend reviewing and merging sequentially so when you review the second PR you see only its changes, not those picked up via the first PR, etc ...

I know very little about CI, but I think it would be quite useful if it were possible to add automatic builds for some of the rarer environments, like MS-DOS/VC, MS-DOS/Borland, OS/2, OS-9, etc. I have no idea if this is easy or even possible.

I think this should be possible with a little work for the MS-DOS builds but will be difficult for OS/2 and OS-9. If you're interested though in improving the CI to build and test on more platforms (even if semi-supported ones like MS-DOS), I'm happy to look into it and propose something.

[ralish]

@gwsw Thanks for merging those four PRs. I hope it proves useful to the project, especially for the retrocomputing fans. I'll rebase this branch on master and test it so this original documentation update + bugfix can be merged. Will report back once that's done.

[gwsw]

The man page update has been merged in cd8d01e.

The fix to get the correct lesskey filename on OS/2 has been implemented in ca3cb65. I took @avih 's Aug 23 suggestion to decide whether to strip the first char based on whether it is a dot/underscore.

[ralish]

Oh that's great, thanks for that. Nice to have it all done! I'll close this out then.