It seems the texdoc.cnf installed in texmf-dist/texdoc by default uses lastfile_switch=true thus preventing file in TEXMFHOME to have any effect about texdoc

[jfbu]

maybe I misundertstand the instructions. With the above reported "problem" my system says

texdoc -f
Info: Running Texdoc not installed in the current TEXMFMAIN.
/usr/local/texlive/2023/texmf-dist/scripts/texdoc/texdoclib.tlu 4.0.1
Configuration file(s):
    active	/usr/local/texlive/2023/texmf-dist/texdoc/texdoc.cnf
    disabled	/Users/user/Library/texmf/texdoc/texdoc.cnf
Recommended file(s) for personal settings:
    /Users/user/Library/texmf/texdoc/texdoc.cnf

but the comments in texmf.cnf say

# The next line has no effect when this file is installed as the last
# configuration file (default) but is useful when you install it as the "tricky"
# configuration file (usually TEXMFHOME/texdoc/texdoc-dist.cnf) whose mere
# existence is a hack to make it easier to run the development version, see
# <https://github.com/TeX-Live/texdoc>.

So is TEXMFHOME/texdoc/texdoc-dist.cnf the "tricky" or the "Recommended" location for user customization? I am a bit confused at this stage.

EDITED: Apologies the texmf.cnf comment refers to texdoc -dist.cnf but I did not see the -dist part hence my confusion.

[wtsnjp]

I think this is the cause of this problem.

Info: Running Texdoc not installed in the current TEXMFMAIN.

Running a Texdoc outside of the current TEXMFMAIN is only supported on a limited basis for debugging purposes. As a general rule, please use the Texdoc that is installed normally in the current TEXMFMAIN; we cannot provide much support for running Texdocs outside of TEXMFMAIN, and you do so at your own risk.

I guess the cause of your problem is probably that the TEXMF variable settings are inappropriate for the version of TeX Live that contains the Texdoc you are running; the TEXMFHOME tree must have a higher priority than the TEXMFDIST tree, but perhaps it is not set up that way.

[jfbu]

Ok. Indeed I have a set-up where 2023 is a symlink and this appears to confuse Texdoc and let it report erroneously

Info: Running Texdoc not installed in the current TEXMFMAIN.

My texdoc is in TEXMFMAIN:

• TEXMFMAIN

$ kpsewhich --var-value TEXMFMAIN
/usr/local/texlive/2023/texmf-dist
$ cd /usr/local/texlive/2023
$ pwd -P
/usr/local/texlive/2020

Because I am using a rolling-release since 2020 and do not keep intervening years. The symlink and not simply change of directory name was I suppose motivated by the fear to clutter my back-up disk with gigabytes of files, which would happen if I were to change each year the directory name.

edit: and the reason to keep 2023 and to adjust some kpsewhich variables to report 2023 is for matters of tex log files in case I have to communicate some such log when raising tickets on TeX related repos.

• LOCATION OF TEXDOC

$ which texdoc
/Library/TeX/texbin/texdoc
$ cd /Library/TeX/texbin
$ pwd -P
/usr/local/texlive/2020/bin/x86_64-darwinlegacy
$ ls -l texdoc
lrwxr-xr-x  1 xxx  zzzzz  42 30 mar 11:05 texdoc -> ../../texmf-dist/scripts/texdoc/texdoc.tlu
$ cd ../../texmf-dist/scripts/texdoc
$ pwd -P
/usr/local/texlive/2020/texmf-dist/scripts/texdoc

So the problem is presumably Texdoc is not resolving locations to absolute paths and fails to see symlinks are involved. (this is on macos as seen from darwinglegacy above).

[jfbu]

My TEXMFHOME does have a higher priority than TEXMFMAIN in general for example for macro style files.
Here some extract of tlmgr conf output. There is nothing special about if for a TeXLive install on mac os, except that all "2023" are in fact symlinks.

TEXMF={{}/Users/aaaaaaaa/Library/texlive/2023/texmf-config,/Users/aaaaaaaa/Library/texlive/2023/texmf-var,/Users/aaaaaaaa/Library/texmf,!!/usr/local/texlive/2023/texmf-local,!!/usr/local/texlive/2023/texmf-config,!!/usr/local/texlive/2023/texmf-var,!!/usr/local/texlive/2023/texmf-dist}
TEXMFCONFIG=/Users/aaaaaaaa/Library/texlive/2023/texmf-config
TEXMFDBS={!!/usr/local/texlive/2023/texmf-local,!!/usr/local/texlive/2023/texmf-config,!!/usr/local/texlive/2023/texmf-var,!!/usr/local/texlive/2023/texmf-dist}
TEXMFDIST=/usr/local/texlive/2023/texmf-dist
TEXMFHOME=/Users/aaaaaaaa/Library/texmf
TEXMFLOCAL=/usr/local/texlive/2023/texmf-local
TEXMFMAIN=/usr/local/texlive/2023/texmf-dist

I do not understand the comments at bottom of texdoc.cnf about lastfile_switch = true. This boolean was not commented in my installation at its /usr/local/texlive/2020/texmf-dist/texdoc/texdoc.cnf location and commenting it out fixed my problem. This seems logical as it seems logical that first this file is loaded then the TEXMFHOME one is loaded last. So I concluded the problem was that the lastfile_switch = true should have been commented out in that file. I commented it out and it fixed my problem. I had no memory of having touched that setting anytime before.

But now I am lost. If indeed it is normally not commented, that means that file is loaded last? but then how does a user file in TEXMFHOME can override settings, or I do not understand at all what lastfile_switch is supposed to convey?
Or perhaps the settings in the texmf.cnf from TEXMFHOME once set are never overridden by a later loaded texmf.cnf?

And I am really much perplexed about the contrast between

# The next line has no effect when this file is installed as the last
# configuration file (default) but is useful when you install it as the "tricky"
# configuration file (usually TEXMFHOME/texdoc/texdoc-dist.cnf) whose mere
# existence is a hack to make it easier to run the development version, see
# <https://github.com/TeX-Live/texdoc>.

and the message from output of texdoc -f:

Recommended file(s) for personal settings:
    /Users/aaaaaaaa/Library/texmf/texdoc/texdoc.cnf

So the same location (EDIT: NO! not same location) is referred to as being both the "recommended" one and the "tricky" one.

EDIT: very sorry. My brain did NOT see texdoc-dist.cnf I read it as texdoc.cnf. I apologize for my mistake. OK, so that point is clarified. I confirm I do not have any texdoc-dist.cnf file anywhere

[jfbu]

I have edited parts of my earlier message because they were caused by an error on my part about having misread the comment provided at bottom of texdoc.cnf file.

[wtsnjp]

So the problem is presumably Texdoc is not resolving locations to absolute paths and fails to see symlinks are involved.

Reading symlink on macOS is simply not supported. Installing the readlink command may solve this problem (see #44).

[wtsnjp]

I am closing this issue since there have been no new comments for a while.