DOC: #793 clarify --home and the home Prolog flag

Explain what the home directory is used for (boot.prc, library/) and
distinguish the two forms of --home: with =DIR sets the home directory
(and adds SWI_HOME_DIR to the environment); without argument reports
the located home directory.  Cross-reference the --home option, the
`home` Prolog flag, and the findhome section from each other.  Update
both the swipl(1) man page and the user manual.

Author: JanWielemaker

man/overview.plx

@@ -426,12 +426,12 @@ initialization/[1,2].  See also the Prolog flag
 \prologflag{debug_on_interrupt}.
 
     \cmdlineoptionitem{--home[=DIR]}{}
-Use \arg{DIR} as home directory.  See \secref{findhome} for details.
-If \arg{DIR} is omitted, the found location is printed and the process
-exits.  If the location cannot be found an error is printed and the
-process exits with status~1.  If the home directory is set using this
-option, the environment variable \const{SWI_HOME_DIR} holding the
-specified directory is added to the process.
+With \arg{DIR}, set SWI-Prolog's home directory to \arg{DIR} and add
+the environment variable \const{SWI_HOME_DIR} holding \arg{DIR} to the
+process.  Without an argument, report the located home directory and
+exit; if the location cannot be found, print an error and exit with
+status~1.  See \secref{findhome} for how the home directory is located
+and \prologflag{home} for what SWI-Prolog uses it for.
 
     \cmdlineoptionitem{--quiet}{}
 \index{verbose}\index{quiet}%
@@ -1820,6 +1820,8 @@ its library as \file{<home>/library}. Some installations may put
 architecture independent files in a \jargon{shared home} and also
 define \prologflag{shared_home}.  System files can be found using
 absolute_file_name/3 as \term{swi}{file}.  See file_search_path/2.
+See \secref{findhome} for how this location is determined and
+\cmdlineoption{--home} for setting or reporting it from the command line.
 
     \prologflagitem{integer_rounding_function}{down,toward_zero}{r}
 ISO Prolog flag describing rounding by \verb$//$ and \verb$rem$ arithmetic

src/swipl.1.in

@@ -147,10 +147,25 @@ if Prolog was compiled for multi-threading and
 otherwise.
 .RE
 .TP
-.BI \-\-home= DIR
-Use
+.BI \-\-home\fR[= DIR ]
+SWI-Prolog uses its
+.I home directory
+to find its startup file as
+.IB <home> /boot.prc
+and its library as
+.IB <home> /library\fR.
+With
+.IR DIR ,
+set the home directory and add the environment variable
+.B SWI_HOME_DIR
+holding
 .I DIR
-as home directory.
+to the process.
+Without an argument, print the located home directory and exit; if the
+location cannot be found, print an error and exit with status 1.
+See also the
+.B home
+Prolog flag.
 .TP
 .BI \-\-stack\-limit= size [bkmg]
 Set the combined stack limit to