ports/68241: portlint suggest the use of undocumented macros

[Fernan Aguero]

The following reply was made to PR ports/68241; it has been noted by GNATS.

From: Fernan Aguero <fernan at iib.unsam.edu.ar>
To: Dag-Erling =?iso-8859-1?Q?Sm=F8rgrav?= <des at des.no>
Cc: FreeBSD-gnats-submit at FreeBSD.org, freebsd-doc at FreeBSD.org,
	marcus at FreeBSD.org
Subject: Re: ports/68241: portlint suggest the use of undocumented macros
Date: Wed, 23 Jun 2004 11:48:48 -0300

 +----[ Dag-Erling Smørgrav <des at des.no> (23.Jun.2004 11:32):
 |
 | Fernan Aguero <fernan at iib.unsam.edu.ar> writes:
 | > 	Upon running portlint -a I get messages like the following:
 | > 	WARN: /home/fernan/.../pkg-plist [21]: consider using DOCSDIR macro
 | > 	WARN: /home/fernan/.../pkg-plist: %%PORTDOCS%%@dirrm %%DOCSDIR%% is missing
 | >
 | > 	The use of these macros is not documented in the Porter's
 | > 	Handbook, nor on the portlint(1) man page.
 | 
 | http://www.freebsd.org/doc/en/books/porters-handbook/dads-documentation.html
 | 
 | DES
 | -- 
 | Dag-Erling Smørgrav - des at des.no
 |
 +----]
 
 Oh I see. The problem is that I was expecting to find
 something like this here:
 http://www.freebsd.org/doc/en/books/porters-handbook/porting-plist.html
 
 There is a mention here to PLIST_SUB and how setting VAR=VALUE
 pairs would make %%VAR%% be substituted with VALUE in the
 pkg-plist. But it seems that DOCSDIR should not be used like
 this. That was what confused me from the examples I saw: no
 one set PLIST_SUB+= DOCSDIR=${DOCSDIR}
 
 So, IMO, the problem is that there is a link in
 'dads-documentation.html' pointing to 'porting-plist.html'
 ("See more on pkg-plist substitution __here__"). But not the
 other way around. Perhaps it could be helpful to have a link
 added in 'dads-documentation.html'? Maybe before starting to
 talk about when this substitution takes place ("This
 substitution (as well as addition ..."), as an addition to
 the previous paragraph?.
 
 Thanks for the pointer, and sorry for the noise. 
 
 Fernan
 
 -- 
 F e r n a n   A g u e r o
 http://genoma.unsam.edu.ar/~fernan