documenting PortGroups?

[Ryan Schmidt]

On Sep 3, 2013, at 13:30, Peter Danecek wrote:

> I realise, that there are may PortGroups available (which probably do a lot of useful stuff) but are currently not documented. Sure, there are the source codes e it may be my poor knowledge of TCL, but I fail to understand it in detail and only from the source one might miss the intended use.
> 
> So what about documenting them? If it's not documented, it does not exists, right?
> In particular, I would be interested in PortGroup github.


Yes, we should document more of the portgroups. There are already some tickets filed for some of them. Anyone is welcome to contribute the documentation, but I realize there are some barriers to entry, such as first needing to understand them and then understanding our docbook xml syntax.

Some portgroups are documented with comments in the code, so I would encourage you to read the portgroups. Also, search the ports tree for other ports using that portgroup and see what they do.

In the case of the github portgroup, as the portgroup file itself says at the top:

# This PortGroup sets up default behaviors for projects hosted at github.
#
# Usage:
#
#   PortGroup               github 1.0
#   github.setup            author project version [tag_prefix]

When you use this line, the portgroup sets up other variables for you, which means you often don't need to then manually set the version, name, homepage, master_sites, distname and livecheck. Certain other github-specific variables are also set and made available to you, should you need them, such as (again, reading the portgroup) github.author, github.project, github.version, github.homepage, github.raw, github.master_sites.

If the project has no released versions or if for some other unusual reason you must fetch a specific commit instead of a released version, you may specify that in place of the version in the github.setup line.

If the project absolutely must download from git instead of from a tarball (e.g. if it uses git submodules) you can set "fetch.type git".

Any other questions, please ask.