MANPATH and overriding/modifying default paths.

MANPATH and overriding/modifying default paths.

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 1392 bytes --]

Hi,

A while back, I complained to Ingo that MANPATH is heavy-handed: it 
doesn't allow us to modify the default search path (in, e.g., 
/etc/man.conf), but only override it.

He mentioned that in manpath(1) used on systems, MANPATH can modify 
instead of override by placemen to colons.  To wit:

MANPATH
     If $MANPATH is set, manpath displays its value rather than 
determining it on the fly. If $MANPATH is prefixed by a colon, then the 
value of the variable is appended to the list determined from the 
content of the configuration files. If the colon comes at the end of the 
value in the variable, then the determined list is appended to the 
content of the variable. If the value of the variable contains a double 
colon (::), then the determined list is inserted in the middle of the 
value, between the two colons.

The enclosed patch does just this for apropos(1), whatis(1), and 
catman(8) (which is also updated with -C like the others).  I modified 
the explanation above to be (I hope) a little clearer as to precedence.

Objections?

I personally like this, as on shared machines I usually have a 
scattering of utilities in my ~/bin and would love a ~/man with the 
manuals showing up by default (i.e., manually running mandocdb(8) to 
generate databases then setting MANPATH in my .profile).  It has always, 
always annoyed me that I can't do this.

Take care,

Kristaps

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 5985 bytes --]

Index: apropos.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.1,v
retrieving revision 1.13
diff -u -r1.13 apropos.1
--- apropos.1	12 Dec 2011 02:00:49 -0000	1.13
+++ apropos.1	18 Dec 2011 14:48:27 -0000
@@ -239,11 +239,22 @@
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev MANPATH
-Colon-separated paths overriding the default list of paths searched for
+Colon-separated paths modifying the default list of paths searched for
 manual databases.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
+If
+.Ev MANPATH
+begins with a
+.Sq \&: ,
+it is appended to the default list;
+else if it ends with
+.Sq \&: ,
+it is prepended to the default list; else if it contains
+.Sq \&:: ,
+the default list is inserted between the colons.
+If none of these conditions are met, it overrides the default list.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
Index: catman.8
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/catman.8,v
retrieving revision 1.2
diff -u -r1.2 catman.8
--- catman.8	4 Dec 2011 22:52:50 -0000	1.2
+++ catman.8	18 Dec 2011 14:48:27 -0000
@@ -23,6 +23,7 @@
 .Sh SYNOPSIS
 .Nm catman
 .Op Fl fv
+.Op Fl C Ar file
 .Op Fl M Ar manpath
 .Op Fl m Ar manpath
 .Op Fl o Ar path
@@ -37,6 +38,12 @@
 Force an update to all files.
 .It Fl v
 Print each file being updated.
+.It Fl C Ar file
+Specify an alternative configuration
+.Ar file
+in
+.Xr man.conf 5
+format.
 .It Fl M Ar manpath
 Use the colon-separated path instead of the default list of paths
 searched for
@@ -44,7 +51,7 @@
 databases.
 Invalid paths, or paths without manual databases, are ignored.
 .It Fl m Ar manpath
-Append the colon-separated paths to the list of paths searched
+Prepend the colon-separated paths to the list of paths searched
 for
 .Xr mandocdb 8
 databases.
@@ -70,6 +77,26 @@
 If
 .Fl f
 is specified, all files are updated.
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev MANPATH
+Colon-separated paths modifying the default list of paths searched for
+manual databases.
+Invalid paths, or paths without manual databases, are ignored.
+Overridden by
+.Fl M .
+If
+.Ev MANPATH
+begins with a
+.Sq \&: ,
+it is appended to the default list;
+else if it ends with
+.Sq \&: ,
+it is prepended to the default list; else if it contains
+.Sq \&:: ,
+the default list is inserted between the colons.
+If none of these conditions are met, it overrides the default list.
+.El
 .Sh EXIT STATUS
 .Ex -std
 .Sh SEE ALSO
Index: catman.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/catman.c,v
retrieving revision 1.7
diff -u -r1.7 catman.c
--- catman.c	16 Dec 2011 12:06:35 -0000	1.7
+++ catman.c	18 Dec 2011 14:48:27 -0000
@@ -66,7 +66,7 @@
 main(int argc, char *argv[])
 {
 	int		 ch;
-	char		*aux, *base;
+	char		*aux, *base, *conf_file;
 	struct manpaths	 dirs;
 	char		 buf[MAXPATHLEN];
 	extern char	*optarg;
@@ -81,8 +81,11 @@
 	aux = base = NULL;
 	xstrlcpy(buf, "/var/www/cache/man.cgi", MAXPATHLEN);
 
-	while (-1 != (ch = getopt(argc, argv, "fm:M:o:v")))
+	while (-1 != (ch = getopt(argc, argv, "C:fm:M:o:v")))
 		switch (ch) {
+		case ('C'):
+			conf_file = optarg;
+			break;
 		case ('f'):
 			force = 1;
 			break;
@@ -112,7 +115,7 @@
 	}
 
 	memset(&dirs, 0, sizeof(struct manpaths));
-	manpath_parse(&dirs, NULL, base, aux);
+	manpath_parse(&dirs, conf_file, base, aux);
 	ch = manup(&dirs, buf);
 	manpath_free(&dirs);
 	return(ch ? EXIT_SUCCESS : EXIT_FAILURE);
@@ -124,6 +127,7 @@
 	
 	fprintf(stderr, "usage: %s "
 			"[-fv] "
+			"[-C file] "
 			"[-o path] "
 			"[-m manpath] "
 			"[-M manpath]\n",
Index: manpath.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/manpath.c,v
retrieving revision 1.7
diff -u -r1.7 manpath.c
--- manpath.c	13 Dec 2011 21:09:01 -0000	1.7
+++ manpath.c	18 Dec 2011 14:48:27 -0000
@@ -87,15 +87,40 @@
 	free(buf);
 	pclose(stream);
 #else
-	manpath_parseline(dirs, auxp);
+	int		 append, prepend;
+	char		*insert;
 
-	if (NULL == defp)
-		defp = getenv("MANPATH");
+	insert = NULL;
+	append = prepend = 0;
+	file = NULL == file ? MAN_CONF_FILE : file;
 
-	if (NULL == defp)
-		manpath_manconf(dirs, file ? file : MAN_CONF_FILE);
-	else
+	if (NULL == defp && NULL != (defp = getenv("MANPATH"))) {
+		append = ':' == defp[0];
+		if ( ! append && '\0' != defp[0])
+			if (':' == defp[(int)strlen(defp) - 1])
+				prepend = 1;
+		if ( ! append && ! prepend)
+			insert = strstr(defp, "::");
+	}
+
+	if (NULL == defp) {
+		manpath_manconf(dirs, file);
+		return;
+	}
+
+	if (prepend)
+		manpath_manconf(dirs, file);
+
+	if (NULL != insert) {
+		*insert++ = '\0';
 		manpath_parseline(dirs, defp);
+		manpath_manconf(dirs, file);
+		manpath_parseline(dirs, insert + 1);
+	} else
+		manpath_parseline(dirs, defp);
+
+	if (append)
+		manpath_manconf(dirs, file);
 #endif
 }
 
Index: whatis.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/whatis.1,v
retrieving revision 1.4
diff -u -r1.4 whatis.1
--- whatis.1	12 Dec 2011 02:00:49 -0000	1.4
+++ whatis.1	18 Dec 2011 14:48:27 -0000
@@ -111,11 +111,22 @@
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev MANPATH
-Colon-separated paths overriding the default list of paths searched for
+Colon-separated paths modifying the default list of paths searched for
 manual databases.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
+If
+.Ev MANPATH
+begins with a
+.Sq \&: ,
+it is appended to the default list;
+else if it ends with
+.Sq \&: ,
+it is prepended to the default list; else if it contains
+.Sq \&:: ,
+the default list is inserted between the colons.
+If none of these conditions are met, it overrides the default list.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact

Re: MANPATH and overriding/modifying default paths.

[Kristaps Dzonsons]

On 18/12/2011 15:52, Kristaps Dzonsons wrote:
> Hi,
>
> A while back, I complained to Ingo that MANPATH is heavy-handed: it
> doesn't allow us to modify the default search path (in, e.g.,
> /etc/man.conf), but only override it.
>
> He mentioned that in manpath(1) used on systems, MANPATH can modify
> instead of override by placemen to colons. To wit:

Ugh, I obviously shouldn't type so quickly... "the manpath(1) utility 
(Mac OS X, FreeBSD, Linux) can modify the default list by placement of 
colons".

>
> MANPATH
> If $MANPATH is set, manpath displays its value rather than determining
> it on the fly. If $MANPATH is prefixed by a colon, then the value of the
> variable is appended to the list determined from the content of the
> configuration files. If the colon comes at the end of the value in the
> variable, then the determined list is appended to the content of the
> variable. If the value of the variable contains a double colon (::),
> then the determined list is inserted in the middle of the value, between
> the two colons.
>
> The enclosed patch does just this for apropos(1), whatis(1), and
> catman(8) (which is also updated with -C like the others). I modified
> the explanation above to be (I hope) a little clearer as to precedence.
>
> Objections?
>
> I personally like this, as on shared machines I usually have a
> scattering of utilities in my ~/bin and would love a ~/man with the
> manuals showing up by default (i.e., manually running mandocdb(8) to
> generate databases then setting MANPATH in my .profile). It has always,
> always annoyed me that I can't do this.
>
> Take care,
>
> Kristaps

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: MANPATH and overriding/modifying default paths.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Sun, Dec 18, 2011 at 04:08:20PM +0100:
> On 18/12/2011 15:52, Kristaps Dzonsons wrote:

>> A while back, I complained to Ingo that MANPATH is heavy-handed: it
>> doesn't allow us to modify the default search path (in, e.g.,
>> /etc/man.conf), but only override it.
>>
>> He mentioned that in manpath(1) used on systems, MANPATH can modify
>> instead of override by placemen to colons. To wit:

> Ugh, I obviously shouldn't type so quickly... "the manpath(1)
> utility (Mac OS X, FreeBSD, Linux) can modify the default list by
> placement of colons".

Heh, you are doing that for manpath(1)-based systems only.
In that case, i have certainly no objection.

Hum, how do we document that, if it is done for manpath(1),
but not for man.conf(5)?  Not sure, but that's hardly a show
stopper, that can certainly be solved.

Maybe it might be useful for man.conf(5)-based systems as well.
But i'm not really sure; i never needed it, and i'm a bit hesitant
to change utilities to use environment variables for yet more
functionality.  In any case, i'd rather not change the semantics
related to man.conf(5) right now, to not interfere with getting
apropos(1) ready.  We can return to it later, when we want to.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: MANPATH and overriding/modifying default paths.

[Kristaps Dzonsons]

On 18/12/2011 20:09, Ingo Schwarze wrote:
> Hi Kristaps,
>
> Kristaps Dzonsons wrote on Sun, Dec 18, 2011 at 04:08:20PM +0100:
>> On 18/12/2011 15:52, Kristaps Dzonsons wrote:
>
>>> A while back, I complained to Ingo that MANPATH is heavy-handed: it
>>> doesn't allow us to modify the default search path (in, e.g.,
>>> /etc/man.conf), but only override it.
>>>
>>> He mentioned that in manpath(1) used on systems, MANPATH can modify
>>> instead of override by placemen to colons. To wit:
>
>> Ugh, I obviously shouldn't type so quickly... "the manpath(1)
>> utility (Mac OS X, FreeBSD, Linux) can modify the default list by
>> placement of colons".
>
> Heh, you are doing that for manpath(1)-based systems only.
> In that case, i have certainly no objection.
>
> Hum, how do we document that, if it is done for manpath(1),
> but not for man.conf(5)?  Not sure, but that's hardly a show
> stopper, that can certainly be solved.
>
> Maybe it might be useful for man.conf(5)-based systems as well.
> But i'm not really sure; i never needed it, and i'm a bit hesitant
> to change utilities to use environment variables for yet more
> functionality.  In any case, i'd rather not change the semantics
> related to man.conf(5) right now, to not interfere with getting
> apropos(1) ready.  We can return to it later, when we want to.

Saying man.conf(5)-based systems is a bit misleading, as manpath(1) 
systems generally use man.conf as well.  Ugh!  I think it's easier to 
say "manpath-systems" (FreeBSD, etc.) and "non-manpath-systems" 
(OpenBSD, etc.).

Right now, if USE_MANPATH is invoked, manpath_parse() simply routes 
directly into manpath(1), passing environment variables and using the 
`-M', `-m', and `-C' flags accepted by manpath(1).  So manpath(1) was 
already prepending/appending MANPATH.

The enclosed patch stretches this over non-manpath systems, as you can 
see.  This brings non-manpath in line with manpath vis-a-vis the MANPATH 
variable.

As mentioned, I really like it just because I've specifically been 
thwarted by this before.  Since few people use MANPATH anyway, and 
usually in the correct colon-separated way, I don't see how this will 
bother users, too.

Thoughts?

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: MANPATH and overriding/modifying default paths.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Sun, Dec 18, 2011 at 03:52:02PM +0100:

> A while back, I complained to Ingo that MANPATH is heavy-handed: it
> doesn't allow us to modify the default search path (in, e.g.,
> /etc/man.conf), but only override it.
> 
> He mentioned that in manpath(1) used on systems, MANPATH can modify
> instead of override by placemen to colons.  To wit:
> 
> MANPATH
>     If $MANPATH is set, manpath displays its value rather than
> determining it on the fly. If $MANPATH is prefixed by a colon, then
> the value of the variable is appended to the list determined from
> the content of the configuration files. If the colon comes at the
> end of the value in the variable, then the determined list is
> appended to the content of the variable. If the value of the
> variable contains a double colon (::), then the determined list is
> inserted in the middle of the value, between the two colons.
> 
> The enclosed patch does just this for apropos(1), whatis(1), and
> catman(8) (which is also updated with -C like the others).  I
> modified the explanation above to be (I hope) a little clearer as to
> precedence.

Yes, your wording is better, very clear and concise.

> Objections?

First, i misread your patch.  You changed the #else clause of
the cpp(1) alternative, not the #ifdef clause.  Thanks for
pointing that out once again.

Then, i hesitated for some time whether we really want this,
but came to the conclusion that we have MANPATH anyway, it does
not change MANPATH semantics that much, the proposed use case
makes sense, i could not come up with a better solution, and it
improves compatibility a tiny bit.

So i have tweaked it and committed it to OpenBSD.
At the expense of three additional lines of code -
actually, all of them closing braces - i got rid of two
local variables, made the code flow much more obvious
and got the oportunity of inserting eight comments.

While here, i have also put back -m (which got lost)
and copied Linux semantics of treating an empty MANPATH
the same way as an undefined MANPATH, which obviously
is more useful than returning empty results.

Feel free to merge to bsd.lv, or tell me to do it;
conflict resolution will be trivial.

Yours,
  Ingo


CVSROOT:	/cvs
Module name:	src
Changes by:	schwarze@cvs.openbsd.org	2011/12/24 14:51:40

Modified files:
	usr.bin/mandoc : apropos.1 manpath.c 

Log message:
Support leading, trailing and double colons in MANPATH
to prepend, append or insert the man.conf(5) default path;
compatible with GNU manpath(1), implementation by kristaps@,
heavily tweaked by me.


Index: apropos.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/apropos.1,v
retrieving revision 1.9
diff -u -p -r1.9 apropos.1
--- apropos.1	12 Dec 2011 01:59:13 -0000	1.9
+++ apropos.1	24 Dec 2011 21:42:07 -0000
@@ -239,11 +239,22 @@ Text production:
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev MANPATH
-Colon-separated paths overriding the default list of paths searched for
+Colon-separated paths modifying the default list of paths searched for
 manual databases.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
+If
+.Ev MANPATH
+begins with a
+.Sq \&: ,
+it is appended to the default list;
+else if it ends with
+.Sq \&: ,
+it is prepended to the default list; else if it contains
+.Sq \&:: ,
+the default list is inserted between the colons.
+If none of these conditions are met, it overrides the default list.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
Index: manpath.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/manpath.c,v
retrieving revision 1.3
diff -u -p -r1.3 manpath.c
--- manpath.c	19 Dec 2011 02:26:33 -0000	1.3
+++ manpath.c	24 Dec 2011 21:42:07 -0000
@@ -38,16 +38,54 @@ void
 manpath_parse(struct manpaths *dirs, const char *file,
 		char *defp, char *auxp)
 {
+	char		*insert;
 
+	/* Always prepend -m. */
 	manpath_parseline(dirs, auxp);
 
-	if (NULL == defp)
-		defp = getenv("MANPATH");
+	/* If -M is given, it overrides everything else. */
+	if (NULL != defp) {
+		manpath_parseline(dirs, defp);
+		return;
+	}
+
+	/* MANPATH and man.conf(5) cooperate. */
+	defp = getenv("MANPATH");
+	if (NULL == file)
+		file = MAN_CONF_FILE;
+
+	/* No MANPATH; use man.conf(5) only. */
+	if (NULL == defp || '\0' == defp[0]) {
+		manpath_manconf(dirs, file);
+		return;
+	}
+
+	/* Prepend man.conf(5) to MANPATH. */
+	if (':' == defp[0]) {
+		manpath_manconf(dirs, file);
+		manpath_parseline(dirs, defp);
+		return;
+	}
+
+	/* Append man.conf(5) to MANPATH. */
+	if (':' == defp[(int)strlen(defp) - 1]) {
+		manpath_parseline(dirs, defp);
+		manpath_manconf(dirs, file);
+		return;
+	}
 
-	if (NULL == defp)
-		manpath_manconf(dirs, file ? file : MAN_CONF_FILE);
-	else
+	/* Insert man.conf(5) into MANPATH. */
+	insert = strstr(defp, "::");
+	if (NULL != insert) {
+		*insert++ = '\0';
 		manpath_parseline(dirs, defp);
+		manpath_manconf(dirs, file);
+		manpath_parseline(dirs, insert + 1);
+		return;
+	}
+
+	/* MANPATH overrides man.conf(5) completely. */
+	manpath_parseline(dirs, defp);
 }
 
 /*
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: MANPATH and overriding/modifying default paths.

[Kristaps Dzonsons]

>> A while back, I complained to Ingo that MANPATH is heavy-handed: it
>> doesn't allow us to modify the default search path (in, e.g.,
>> /etc/man.conf), but only override it.
>>
>> He mentioned that in manpath(1) used on systems, MANPATH can modify
>> instead of override by placemen to colons.  To wit:
>>
>> MANPATH
>>      If $MANPATH is set, manpath displays its value rather than
>> determining it on the fly. If $MANPATH is prefixed by a colon, then
>> the value of the variable is appended to the list determined from
>> the content of the configuration files. If the colon comes at the
>> end of the value in the variable, then the determined list is
>> appended to the content of the variable. If the value of the
>> variable contains a double colon (::), then the determined list is
>> inserted in the middle of the value, between the two colons.
>>
>> The enclosed patch does just this for apropos(1), whatis(1), and
>> catman(8) (which is also updated with -C like the others).  I
>> modified the explanation above to be (I hope) a little clearer as to
>> precedence.
>
> Yes, your wording is better, very clear and concise.
>
>> Objections?
>
> First, i misread your patch.  You changed the #else clause of
> the cpp(1) alternative, not the #ifdef clause.  Thanks for
> pointing that out once again.
>
> Then, i hesitated for some time whether we really want this,
> but came to the conclusion that we have MANPATH anyway, it does
> not change MANPATH semantics that much, the proposed use case
> makes sense, i could not come up with a better solution, and it
> improves compatibility a tiny bit.
>
> So i have tweaked it and committed it to OpenBSD.
> At the expense of three additional lines of code -
> actually, all of them closing braces - i got rid of two
> local variables, made the code flow much more obvious
> and got the oportunity of inserting eight comments.
>
> While here, i have also put back -m (which got lost)
> and copied Linux semantics of treating an empty MANPATH
> the same way as an undefined MANPATH, which obviously
> is more useful than returning empty results.
>
> Feel free to merge to bsd.lv, or tell me to do it;
> conflict resolution will be trivial.

Ingo,

I'm checking this in right now, applying the apropos(1) updates to 
whatis(1) and catman(8).

Thanks for looking this over!

Kristaps

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv