Deciphering a Porter's Handbook paragraph

[Benjamin Kaduk]

On Mon, 2 Jan 2012, Warren Block wrote:

> http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/book.html#PORTING-PREFIX

------
The value of PREFIX will be set to LOCALBASE (default /usr/local). If 
USE_LINUX_PREFIX is set, PREFIX will be LINUXBASE (default /compat/linux).
------

I don't think we've yet said something like:
LOCALBASE should be set to where existing ports have already been 
installed (the ``base directory'' of where the ``local additions'' to the 
system have been made); it is uncommon for having PREFIX != LOCALBASE in 
normal usage.
We probably should say something like that.


>
> ------
>  # make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`
>
>  If anything is installed outside of PREFIX, the package creation
>  process will complain that it cannot find the files.
> ------
>
> Okay so far.
>
> ------
>  This does not test for the existence of internal references, or
>  correct use of LOCALBASE for references to files from other ports.
> ------
>
> I want to rewrite that to be more specific about what "this" refers to:
>
>  This simple test does not check for incorrect internal references
>  or the correct use of LOCALBASE for references to files from other
>  ports.
>
> That seems a bit better.  Now for the good one:

Maybe, but only a little bit.
I think the point it is trying to make is that a port might install a 
shell script that has a hardcoded path '/usr/local/...' in it, and just 
generating the package does not try to (say) execute that script, and so 
the error would be undetected.  Likewise, it does not check that calls to 
dependencies refer to LOCALBASE (as opposed to just PREFIX or even a 
hardcoded /usr/local).
I'm not convinced that it's intuitively clear what "correct internal 
references" are to the ordinary reader.

>
> ------
>  Testing the installation in /var/tmp/`make -V PORTNAME` to do that
>  while you have it installed would do that.
> ------
>
> What?  Testing the installation... how?  Does "installation" mean 
> already-installed files, or does it mean the user is supposed to do an 
> installation?  What does "that" in "to do that" refer to?  What does the last 
> "that" refer to?
>
> I think it may mean:
>
>  To test for those problems, run the program from the temporary
>  installation in /var/tmp/`make -V PORTNAME` and verify that it
>  operates correctly.

Er, yes, that.

>
> The complete rewritten paragraph:
>
>  This simple test does not check for incorrect internal references
>  or the correct use of LOCALBASE for references to files from other
>  ports.  To test for those problems, run the program from the temporary
>  installation in /var/tmp/`make -V PORTNAME` and verify that it
>  operates correctly.
>
> Please, someone help me encromulate this.
Just so long as we can eschew obfuscation at the same time.

That seems basically correct, though I might try to expand "incorrect 
internal references" a bit.  I might also s/To test for these problems/To 
verify that the port has correct references/ or something kind of like 
that, since "to test for these problems ... verify that it operates 
correctly" feels like correct operation implies that the problems are 
present, which is of course just silly.

-Ben Kaduk