ports/49955: [PATCH] bsd.port.mk: add target to automatically install port documentation

[Sergei Kolobov]

On 2004-01-28 at 01:42 +0100, Oliver Eikemeier wrote:
> Sergei Kolobov wrote:
> >Ports that have few doc files get this:
> >
> >DOCS=		file1 file2 subdir/file3
> 
> this doesn't save you much compared with
> 
> 	@cd ${WRKSRC}/doc && ${INSTALL_DATA} file1 file2 subdir/file3
> 	${DOCSDIR}

Yes, that's what it is, essentially - with @${MKDIR} ${DOCSDIR}, all
wrapped in .if !defined(NOPORTDOCS).

If you find it stupid (or lazy) to add support for this in bsd.port.mk,
here's my experience: most of the 50+ ports I maintain personally, plus
many other ports I've touched recently have this construct.
I have also converted several ports to this construct in a process of
updating, etc. Moreover, the only purpose of post-install target in some
of those ports is to install docs, so the whole target is wrapped in
.if !defined(NOPORTDOCS).

Most of this ports have static DOCS lists - e.g., AUTHORS NEWS README
TODO - and just a few have occassional *.html (or similar) glob, but
none of them need to copy tons of files into DOCSDIR or create a
directory structure under DOCSDIR.

> it yould be interesting when this macro could copy hierarchies.
> Anyway, do you have a sample port the would benefit from a DOCS macro?
> I named to Java ports a examples (using javadoc, i.e. junit, java3d,
> forte, whatever) for the PORTDOCS macro, because
> 
> - they have dynamically generated documentation, changing often
> - have a large, deep documentation tree
> - install the documentation themselves
> - don't always honour NOPORTDOCS

No, I don't disagree with that. In fact, I see the need for that.
All I'm saying is most of the ports I deal with are completely different
in this regard.

> Or is your point that most people are too lazy to write
> 
> PORTDOCS=	NEWS Changelog
> 
> .ifndef NOPORTDOCS
> 	@${MKDIR} ${DOCSDIR}
> 	@cd ${WRKSRC} && ${INSTALL_DATA} ${PORTDOCS} ${DOCSDIR}
> .endif
> 
> but would use
> 
> DOCSSRC=	NEWS Changelog
> 
> instead?

Essentially, yes.  It's not about laziness ;) but about convenience,
and shortening a lot of port Makefiles.
I, for one, would like to see that.  ;)

> And please avoid INSTALL_DOCS, it's too similar to INSTALL_MAN.

Yes, the original version I've submitted in the PR had this bad naming
choice. I have setlled on DOCS name since then.

Again, as I mentioned in my previous message, I would like to see two
separate variables:

- DOCS: pretty much static list, allows some simple wildcards, one dir
  level only

- DOCS_GLOB: dynamically generated list, uses full power of allows
  liberal use of wildcards, can copy directory hierarchy.
  This is your PORTDOCS today.

and corresponding USE_DOCS to specify whether you need to install the
docs automatically into DOCSDIR, or just add them to pkg-plist if
NOPORTDOCS is not set, or both.

Sergei