[File] file-5.46: problems in file.man and magic.man

[Winston]

2 small issues in the man pages:
* "in preference to"
* installed misc/magic: file, directory, or absent?

I originally reported these to FreeBSD.  They asked me to report it
upstream to you.

Before doing so, I retrieved file-5.46, built it, examined it, read
through ./configure, the Makefiles, etc. and tailored my suggestions
accordingly.

Issue 1: In file.man

   The text "In addition, if ... $HOME/.magic exists, it will be used in
   preference to the system magic files."

   "in preference to" implies "instead of", which is not the case.
   $HOME/.magic(.mgc) is "in addition to", not "in preference to".
   I suggest something like:

--- doc/file.man        2024-12-10 10:57:43.867226000 -0500
+++ doc/file.man.new    2024-12-10 10:56:03.695608000 -0500
@@ -114,3 +114,3 @@
 .Pa $HOME/.magic
-exists, it will be used in preference to the system magic files.
+exists, it will be used before the system magic files.
 .Pp


Issue 2: references to ${datadir}/misc/magic as a directory in file.man
and magic.man

   This one's more complicated.  Both man pages refer to misc/magic as a
   directory, but:

   * On FreeBSD, it's a file: the concatenation of all the Magdir/*
     files, and there is no misc/magic.mgc.  If there's a configure
     option in file-5.46 to do that, I didn't see it, so maybe it's a
     FreeBSD-only change to save space.  In any case, misc/magic as
     installed there is not a directory as the man pages say.

   * Building file-5.46 did not install ${datadir}/misc/magic as either
     a file or a directory.  The only file installed was misc/magic.mgc.
     If that's the standard, then again the man pages are wrong since
     misc/magic is absent.

   I didn't look to see what libmagic does; i.e., whether it actually
   reads misc/magic/* if misc/magic.mgc doesn't exist and misc/magic is
   a directory.  If it does, then references to misc/magic/ as a
   directory may still be suitable with qualifiers like "if it exists
   and is a directory".

   Otherwise, references to system misc/magic as a directory in file.man
   and magic.man probably should be removed altogether.

HTH,
 -WBE