[BUG](arborist) man page support appears completely non-existent

[Zordrak]

What / Why

Firstly please forgive any assertions I make that are completely wrong - I'm doing my best to understand something that is completely alien to me.

I had been trying to work out why my new package was not having its man page installed despite following all of the documentation I can find and trying several different iterations of configuration. I have been tracking this down through npm, into Arborist - and I believe that the fault lies in Arborist - and as per #2914 (comment) I am beginning to believe that actually Arborist completely lacks support for creating - only deleting - man pages.

What I think I know - but correct me where I'm totally off base:

• The Node object constructed in Arborist gets given bin paths, but not man paths, from the raw package.json. I still haven't quite worked out where the raw package.json becomes the package object that is passed into the Node class constructor.
• Nowhere in Arborist is there any defined reference or support for a man path meaning that it expects it to be either provided in the package object that is used to first populate the node object in the constructor, or it's expecting it to be populated dynamically by a subsequent call to bin-links/get-paths.getPaths()
• The Arborist Node object is granted a getter called binPaths that calls bin-links/get-paths.getPaths() (aliased as getBinPaths)
• However, Node.binPaths is only ever used twice in Arborist
  • once in lib/diff.js to confirm all the paths exist
  • once in lib/arborist/reify.js under _addNodeToTrashList to make sure the binPaths are deleted on removal

I believe that somewhere there is supposed to be a call to Node.binPaths that doesn't seem to exist. This call would return both the bin and man paths into the Node.package property that would be used later in bin-links/index.binLinks() to link both bins and man pages - but instead of calling Node.binPaths, it is just relying on the Node object having been instantiated with the bin property in the constructor's source data, rather than getting it through Node.binPaths.

It should be noted that if Arborist was doing what I think it is supposed to be doing to get the paths and link them using bin-links; bin-links does not follow the NPM documentation which states that man paths can be a string or an Array, as there is a hard-check in bin-links/get-paths.getPaths() for an Array: (manTarg && pkg.man && Array.isArray(pkg.man) && pkg.man.length)

Additionally, I have seen documentation stating that you can also use package.json sugar to include a man directory in the directories property, which should include all man pages in the directory - but I see no support for that in Arborist or in bin-links.

When

Performing any npm install of a package with man pages (though I am only testing with --global installs at the moment - I'm not sure what the linking logic is supposed to be in local mode).

Where

• npm install npm
• npm install orgtomate

Current Behavior

No man page links created. No errors.

Steps to Reproduce

Install a package with man pages configured either:

• As an man Array property in package.json
• As an man string property in package.json
• As a man string property in the directories property in package.json

Expected Behavior

man pages installed into ${base}/share/man/ via symlinks - as successfully achieved with npm link, although npm link only works with a man Array property due to that being the only supported approach in bin-links.

References

• Related to [BUG] Man pages are deleted, but not reinstalled #2914

[wraithgar]

This is the same issue as #4276, closing this one as a duplicate