Documentation

Documentation Location

We currently have documentation in a myriad of locations, such as

• the Guide
• manpages
• Trac wiki pages
• website

This situation is not ideal, since it is not clear which documentation goes where and creates inconsistencies between multiple locations.

Multiple documentation locations may be justifiable, for example when separating user from developers documentation.

We should move to a single location for documentation that is more easily editable than the guide currently is, but otherwise collects all information that is currently spread over the guide, wiki pages and the website.

Quick prototyping suggests that reStructured Text is not powerful enough for the features we need in the guide. However, conversion to asciidoc can be automated with docbookrx and yields good results, so conversion is probably doable in the near future. We're tracking this in #56046.

Documentation Content

Putting these improvements into a proper location is #56047.

Improving the Installation User Experience

• The download page should auto-detect the user's operating system and already offer the correct download.
• To satisfy the need for a "one-line-copy-paste-auto-install" while avoiding the dreaded "curl | sudo sh", we could offer a single line similar to xcode-select --install && curl -OL "$pkgurl" && sudo installer -package "$pkgfile" -target /

Documenting MacPorts' Advantages

The documentation should explain MacPorts' advantages and why certain decision have been made (and why they are good).

Privilege Separation (aka 'MacPorts requires sudo/root')

MacPorts does not run builds as your user, but will switch to a separate, unprivileged macports user when building. This prevents builds from accidentally modifying files in, for example, your home directory.

MacPorts also runs its builds inside a sandbox that will prevent them from modifying files outside of the places where MacPorts supports modifications to ensure a rogue build system will not wreak havoc on your system.

Files installed by MacPorts are owned by root, so that they cannot be changed by software run under your user account. This gives you the guarantee that the files installed by MacPorts are not changed without your knowledge.

MacPorts installs in a separate prefix (aka 'MacPorts requires modification of $PATH')

See wiki:FAQ#defaultprefix.

MacPorts installs libraries and tools my system already ships

See wiki:FAQ#syslibs, wiki:FAQ#ownlibs.

MacPorts delivers its ports tree and binary archives in a tamper-safe way

MacPorts' binary archives and ports tree are signed with public private key cryptography and are safe against tampering by nefarious attackers. You can be certain that binaries installed by MacPorts have actually been built on MacPorts' infrastructure.