REVISION: Some corrections to the portfile(7) man page

[jmpp@…]

Some revisions/corrections to the portfile(7) man page. Mainly typo corrections, mentioning of the new "port:foo" dep type and scrapping any mention to the XXX hack, note about file(n) as a TCL extension... and others.

Chris: review/comment/flame the attached patch so we can commit it. Thanks!

-jmpp

[jmpp@…]

base/doc/portfile.7.diff

[cjr@…]

This looks good to me.

It might be an artifact of the diff, but there should be a blank line after every line ending "\e\", otherwise the backslash doesn't appear on the line.

Otherwise you've fixed a lot of little goofs on my part, which is good :-)

[cjr@…]

Actually, one thing - there are a couple of references to "Portfile" and "portfile" in the text which ought to be marked up. For example:

--- is run in. This is often overridden on a per Portfile basis. ---

but ought to be:

--- is run in. This is often overridden on a per .Nm basis. ---

Alright, two things. Since file(n) is a standard Tcl command, should it be mentioned as a Tcl extension in portfile.7? I don't think so.

[jmpp@…]

Hey Chris!

(In reply to comment #3)

Actually, one thing - there are a couple of references to "Portfile" and "portfile" in the text which

ought

to be marked up. For example:

--- is run in. This is often overridden on a per Portfile basis. ---

but ought to be:

--- is run in. This is often overridden on a per .Nm basis. ---

Great, thanks for pointing that out, I'll take care of it ASAP!

Alright, two things. Since file(n) is a standard Tcl command, should it be mentioned as a Tcl

extension

in portfile.7? I don't think so.

Well, granted, I'm not too sure if it should be mentioned as a dp tcl extention because it really isn't one, but I firmly believe a note to it should be added at least somewhere (and I'm not referring to just the "see also" section). What do you suggest? Other opinions anyone?

-jmpp

[jberry@…]

portfile is missing:

destroot.keepdirs -- Specifies a list of directories that shouldn't be deleted following destroot even if they are empty. This is useful for directories that must be present in the installation but which receive no contents until runtime. The /var/run directory is one common example. In the absense of this directive, empty directories in the destroot are deleted following the destroot phase.

[jberry@…]

Also missing description of port dependency.

Note that this dependency has two fields, not three as for bin, lib, and path.

Format of the port dependency is port:<portname>. It specifies a simple unqualified dependency onto another port.

[jmpp@…]

base/doc/portfile.7.diff

[jmpp@…]

OK, here's a new patch. In it I take care of the .Nm issues pointed out by Chris (while not addressing the "\e\" issue because I don't see it), also added "destroot.keepdirs" as pointed out by James, explained a bit better the new "port:foo" dep type (which was already there in my first patch, James ;-), added some comments to the "system" Tcl extension about the practices we favor and left the file(n) comment right where it was (while also adding a note to it in the "SEE ALSO" section), but added a "standard TCL command" leading comment to make things clearer. If this last fix is not satisfactory please speak up, I am not too sure where else I could talk about "file" (and I firmly believe we should mention it, because we favor its use way over equivalent "system" calls, as one of my additions in this new patch points out). Ohhh, I also added you Chris as an author, you belong there :-) (as I just did to the port(1) man page, enjoy!)

Review/comment/flame.... g'me the green light to commit! ;-)

-jmpp

[cjr@…]

One minor change - since destroot is a command, the new text:

upon destroot completion

should be marked up as

upon .Cm destroot completion

The additions to the system extension are good. I'm still puzzled about file. Even though it is a command built-in to Tcl, there's a file implementation built into base/pextlib. I suppose that means we should document it here, but I'd like to know why we've got a duplicate implementation of the file command...

I think this is good to commit, once you add the markup I mentioned above. Nice work!

[cjr@…]

Shouldn't these changes be going on the HEAD too?

[jmpp@…]

Chris, I made the last correction you suggested, thanks! I'm also Cc'ing Jordan here for some comments with respect to the file(n) issue, I don't know how its implementation in Pextlib plays along with the Tcl builtin and where we should document either one. Jordan, thoughts? I'll be uploading a new patch shortly. (if no further comments are made I'll just commit this and correct as we go along, when someone steps up with the necessary explanations).

Lastly, Chris: could you please take care of committing to HEAD? Or you Jordan? Thanks!

-jmpp

[cjr@…]

I can integrate your changes back to the head, no problems.

[jmpp@…]

base/doc/portfile.7.diff

[jmpp@…]

Changes committed, closing bug. As per jkh's comments on IRC, there is no "file" implementation in pextlib, so I'm leaving the reference to file(n) where it currently is in lack of any better ideas.

Chris, could you please commit to HEAD? Thanks! And thanks for reviewing!

-jmpp

[cjr@…]

Done. I'm not sure why I thought we had another file implementation!