where to put examples?

[Peter Danecek]

Hi Ryan!

On Oct 18, 2013, at 1:43 , Ryan Schmidt <ryandesign at macports.org> wrote:

> 
> On Oct 17, 2013, at 10:18, Peter Danecek <Peter.Danecek at bo.ingv.it> wrote:
> 
>> There is some note in porthier(7) which might suggest documentation would go into ${prefix}/share/doc and examples into ${prefix}/share/examples, no further details. 
> 
> This is what I would view as correct. More specifically: documentation goes in ${prefix}/share/doc/${subport} and examples in ${prefix}/share/examples/${subport}.
> 
> The version number usually does not belong in these paths because there can only be one version of a port active at one time.
> 
> ${prefix}/share/${subport} is a location where ports can install any architecture-agnostic files they may need. Some build systems may also put documentation or examples here. If I did anything about this in a portfile it would probably just be to install symlinks at ${prefix}/share/doc/${subport} and ${prefix}/share/examples/${subport} pointing to the places within ${prefix}/share/${subport} where the build system installed them.

Okay, this all makes sense to me.

> If other documentation, portfiles or portgroups puts these files elsewhere, ideally they should be fixed. For example, ${prefix}/share/doc/${subport}/examples seems wrong to me.

So here I would propose that the Python Portgroup should NOT create this ${prefix}/share/doc/${subport}/examples directory at all. 
 
(1) It is probably the "wrong" location for manually installed documentation. 
(2) I do not find it particularly useful that this directory is created. I often see a situation where the directory a dir `examples` in the distribution package. I find it logical to just copy this to the appropriate location. So having an empty `examples` dir around just complicates the situation.

The only problem I see is it might break ports which  rely on this!

Should I file a bug report against the portgroup? (including documentation?)

What about providing the "correct" location of doc and example directories in variables by base? Is this a reasonable request?

Cheers,
~petr

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 1762 bytes
Desc: not available
URL: <http://lists.macosforge.org/pipermail/macports-dev/attachments/20131023/ac0a2199/attachment.p7s>