17.9 Install additional documentation

If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under PREFIX/share/doc. This can be done, like the previous item, in the post-install target.

Create a new directory for your port. The directory name should reflect what the port is. This usually means PORTNAME. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole PKGNAME.

Make the installation dependent on the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this:

post-install:
.if !defined(NOPORTDOCS)
    ${MKDIR} ${DOCSDIR}
    ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
.endif

Here are some handy variables and how they are expanded by default when used in the Makefile:

• DATADIR gets expanded to PREFIX/share/PORTNAME.

• DOCSDIR gets expanded to PREFIX/share/doc/PORTNAME.

• EXAMPLESDIR gets expanded to PREFIX/share/examples/PORTNAME.

These variables are exported to PLIST_SUB. Their values will appear there as pathnames relative to PREFIX if possible. That is, share/doc/PORTNAME will be substituted for %%DOCSDIR%% in the packing list by default, and so on. (See more on pkg-plist substitution here.)

All documentation files and directories installed should be included in pkg-plist with the %%PORTDOCS%% prefix, for example:

%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
%%PORTDOCS%%%%DOCSDIR%%/CONTACT
%%PORTDOCS%%@dirrm %%DOCSDIR%%

As an alternative to enumerating the documentation files in pkg-plist, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. PORTDOCS should not be set if NOPORTDOCS is in effect. Installing the documentation at PORTDOCS as shown above remains up to the port itself. A typical example of utilizing PORTDOCS looks as follows:

.if !defined(NOPORTDOCS)
        PORTDOCS=       *
.endif