where to put examples?

[Peter Danecek]

Hi all,

I am now a bit puzzled about where to put examples (and to some extend also docs). In the Guide there is little information on this and I found nothing in the wiki.

--- cite ---
4.7.3. Install Docs and Examples

TODO:
--- end ---

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. 

The following side-note on PortGroup python from the guide, would suggest a pattern like this ${prefix}/share/doc/${name}/examples. (I use ${name} below, but in some case it may actually be ${subport}).

--- cite ---
5.9.5.3. python PortGroup Sugar
[...]
pre-destroot
Default: creates directory ${destroot}${prefix}/share/doc/${subport}/examples.
--- end ---

These are conflicting, so at least one might be outdated and reality draws an even more varying picture.

Looking through Macport's hierarchy I find the following (most common) patterns, for 'examples':

${prefix}/share/examples/${name}/
${prefix}/share/${name}/examples/
${prefix}/share/${name}/${version}/examples/

${prefix}/share/doc/${name}/examples/
${prefix}/share/${name}/doc/examples/

and for `doc`:

${prefix}/share/doc/${name}/
${prefix}/share/${name}/doc/
${prefix}/share/${name}/${version}/doc/

The are even more complex paths. In the case of py-pyobjc-cocoa, this is probably just undesired and due to the already existing directory ("PortGroup Sugar") and the attempt to copy an complete directory to destroot. (I ran into the same issue recently). 

Example:
	doc/py26-pyobjc-cocoa/examples/examples

Here just some arbitrary selection of more complex patterns:

gimp/2.0/help/en/images/dialogs/examples
doc/hadoop-1.2.1/docs/api/org/apache/hadoop/examples
doc/py26-pyobjc/examples/ApplicationPlugins/Colloqui/Colloquy Plugin SDK/examples
texmf-texlive/doc/latex/cals/examples
texmf-texlive/doc/context/third/gantt/examples

and for 'doc':

doc/qtoctave-utils/qtjs/doc
doc/boost/libs/algorithm/doc
doc/boost/libs/utility/identity_type/doc
doc/boost/libs/python/doc/tutorial/doc
texmf-texlive/doc/fonts/phonetic/doc
texmf-texlive/doc/latex/tkz-berge/NamedGraphs/doc


So now my questions:
- Are there any guidelines on where to place documentations and examples?
- Which would be the correct pattern?
- Does the cited PortGroup Sugar make sense at all?
- Wouldn't it make sense to providing variables destroot.doc and destroot.examples (or destroot.dir_doc and destroot.dir_examples, or similar) to provide the correct location?

Thanks!
~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/20131017/e7516906/attachment.p7s>