handbook: remove portmaster et al

[vishwin]

Summary

More involved/explicit version of D22449.

These tools don't deserve mentioning in the handbook at all. When considering the audiences of the handbook, particularly those less experienced in building their own ports and troubleshooting build failures, we should not be encouraging having users shoot themselves in the foot. While building in unclean environments can prove useful, said usefulness is limited to those who intrinsically know what they are doing, and mentioning such doesn't provide value to handbook audiences. Ports-related mailing lists and other communication mediums see endless amounts of reports that to trained eyes are pilot errors, all of which can be avoided by encouraging building under clean environments. Further, certain ports effectively (and intentionally) require clean build environments due to conflicts.

[pauamma_gundo.com]

documentation/content/en/books/handbook/ports/_index.adoc

972

This doesn't explain how to remove all work directories, only that of a single port (and its dependencies, although that's left unsaid). Since some of the text removed (portsclean -C) did that, maybe mention running make clean in the root of the ports tree? Could be a follow-up review.

[fernape]

I agree with the general idea of the review.
To my understanding, building ports should be done in a clean environment, hence poudriere or synth. However, I would just mention these other two options just in case. Something along the lines:

There are also other tools that help building ports like Portmaster and Portupgrade.
They have been used historically in many installations but they are limited in what they can do and in general their use is not recommended.

documentation/content/en/books/handbook/ports/_index.adoc

972

Yes, it should be from the root or the sentence should specify that make clean cleans working directories recursively.

[bofh]

This has been under discussion in the portmgr with more in depth removal of references to all portmaster/portupgrade/synth. These tools has definitely their usages but on the contrary I would advise it only for the hackers or who actually know what they are doing. This is because there are lots of noises in bugzilla often when the user is using ports tree and the upgrade procedure is broken or even they do not have a clean ports tree. In fact I was supposed to remove these but we had some old informations in the testing section of the phb.

[vishwin]

documentation/content/en/books/handbook/ports/_index.adoc

972

Yeah I wanted to see what we have left after removing those sections entirely. Some revising to have make clean and even distfile management (because some of them are disk space hogs too) make sense is needed and should be part of this review.