docs/173321: ports(7) man page -- no info on building with debugging info

[Ronald F.Guilmette]

>Number:         173321
>Category:       docs
>Synopsis:       ports(7) man page -- no info on building with debugging info
>Confidential:   no
>Severity:       serious
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Nov 03 04:10:01 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 8.3-RELEASE amd64
>Organization:
entr0py
>Environment:

FreeBSD 8.3-RELEASE GENERIC amd64

>Description:

Looking in the ports(7) man page, there does not appear to be any information
in there whatsoever that describes the accepted & official method whereby
any given port can be built and installed in such a way so that the
executable(s) and also the shared library/libraries that form the port
will be compiled with full debugging symbols AND so that this debug info
will NOT be stripped out of the components of the port as they are actually
being installed into the directories where they will ultimately live.

This makes no sense to me (and I consider it a bug), because the ports(7)
man page _does_ have what looks like complete information about any and
every possible ``standard'' port Makefile target.  Given that, it seems
to me to be more than reasonable to expect this man page to also document
something as fundamental as how to build & install a port with debug symbols.

>How-To-Repeat:

man 7 ports

>Fix:

I would suggest some prose to add, but frankly, I am not 100% sure that I
know the Right Way to build & install with debugging symbols.  (I think that
I know, but I could easily be wrong.)
>Release-Note:
>Audit-Trail:
>Unformatted: