manpages: portfile: document keyword use_dmg

[mascguy]

Add info for keyword use_dmg, which is presently undocumented:

     use_dmg
         Use a disk image (dmg).
         Sets extract.suffix to ``.dmg''.
         Sets extract.cmd to ``hdiutil''.
         Sets extract.pre_args to ``attach''.
         Sets extract.post_args to ``-private -readonly -nobrowse -mountpoint ...etc...''.
         Type: optional
         Example:
               use_dmg yes

There's just one caveat, for extract.post_args: The number of arguments is significant, and things vary slightly due to necessary logic behind it:

set dmg_tmp_dir [exec mktemp -d -q "/tmp/mports.XXXXXXXX"]
set dmg_mount ${dmg_tmp_dir}/${worksrcdir}
file mkdir ${dmg_mount}
option extract.cmd [binaryInPath "hdiutil"]
option extract.pre_args attach
option extract.post_args "-private -readonly -nobrowse -mountpoint  ${dmg_mount} && [binaryInPath "cp"] -Rp ${dmg_mount}  ${extract.dir} && ${extract.cmd} detach ${dmg_mount} &&  [binaryInPath "rmdir"] ${dmg_mount} ${dmg_tmp_dir}"

As a result, I truncated the details for extract.post_args. But thoughts welcome as to what we should include for that.

Corresponding PR, for MacPorts Guide:

PR 61 - guide: phase: document use_dmg

[mascguy]

Added @jmroot, @ryandesign, and @neverpanic for thoughts/feedback. (Particularly related to what details we include - or don't include - for extract.post_args.)

[neverpanic]

I think we should include a paragraph describing what the extract.post_args line does, rather than the full invocation, which is indeed quite complicated.

[mascguy]

I think we should include a paragraph describing what the extract.post_args line does, rather than the full invocation, which is indeed quite complicated.

Sounds good, I'll try to get this updated shortly. Thanks for the feedback Clemens!

[mascguy]

I think we should include a paragraph describing what the extract.post_args line does, rather than the full invocation, which is indeed quite complicated.

Sounds good, I'll try to get this updated shortly. Thanks for the feedback Clemens!

Done

[mascguy]

Merging these changes in their current state. We'll have time to refine before the next release, if anyone would like to see further changes/additions.

Feedback welcome and appreciated, as always.