where to put examples?

[Peter Danecek]

On Oct 23, 2013, at 18:24 , Blair Zajac <blair at orcaware.com> wrote:

> On 10/23/2013 07:41 AM, Peter Danecek wrote:
>> 
>> 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.
> 
> I disagree, I don't find $prefix/share/examples natural at all, maybe because Linux doesn't have this directory at all.  I'm used to only looking in $prefix/share/doc/$subport for any additional samples, documentation, examples.

> I do request that all content documentation and example content be findable from $prefix/share/doc/$subport, even if it is a symlink.

However, the current situation is even worse. You just cannot rely on anything, neither to find documentation or examples in $prefix/share/doc/$subport, nor in any other place (e.g. $prefix/share/examples/$subport). 

I accept, your wish to have a similar layout as on Linux and I am fine with any solution. I just want to know where to put documentation and examples to do "the right thing", at least when I have to decide. And I ask to resolve this ambiguity in the documentation and to tell me what to do. 

Personally, my preference would probably be to put related to a port in one hierarchy, i.e. 
 $prefix/share/$subport/doc
 $prefix/share/$subport/examples
 $prefix/share/$subport/other_as_needed
But I accept this not a plain ground decision.

I also think, it may not be worth bothering with modifying the way the build/install system handles this, except maybe setting the cited symlinks.

>> So here I would propose that the Python Portgroup should NOT create this ${prefix}/share/doc/${subport}/examples directory at all.
> 
> Again, I think it should have it, and it can be a symlink.

There were actually two considerations here:

1. It should not conflict with the requested "policy" (if any) on where to put examples and or docu. Okay, you disagree the input I was given before. 

2. I just think, creating this empty directory is not any helpful. You just risk to end up with something like: ${prefix}/share/doc/${subport}/examples/examples/* instead (and this is actually happening), or you have to delete the directory again before copying or symlinking.

So again, is there any consensus where to put docu and examples, at least, if I have the choice?

Greetings!
~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/ae89633f/attachment.p7s>