[MacPorts] #39051: The example portfile in the "doc" folder of base should pass lint
#39051: The example portfile in the "doc" folder of base should pass lint ---------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Keywords: | Port: exampleport ---------------------+-------------------------------- `port -v lint --nitpick` reports the following problems for doc/exampleport/Portfile: {{{ Warning: Line 1 is missing RCS tag ($Id$) Warning: Variant puredarwin does not have a description Warning: Maintainer email address for ryandesign includes @macports.org Warning: no license set Error: Portfile parent directory doc does not match primary category devel Error: Portfile directory exampleport does not match port name glib2 ---> 2 errors and 4 warnings found. }}} Also `port lint` doesn't warn about missing modelines, but it'd probably be a good idea to add one. -- Ticket URL: <https://trac.macports.org/ticket/39051> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by ryandesign@…): I vote for deleting the exampleport directory. I have no recollection of seeing it before and it hasn't been updated since 2007 and is clearly completely out of touch with our current practices, which are already documented in the guide. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:1> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by egall@…): If we're going to remove the example port, then I'd at least like to see my portfile for `portfile-gen` to be committed to trunk, so that we can tell users who want to see an example port to just use `portfile-gen` to output one. (My ticket for it is #37797 btw) -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:2> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by larryv@…): Replying to [comment:2 egall@…]:
If we're going to remove the example port, then I'd at least like to see my portfile for `portfile-gen` to be committed to trunk, so that we can tell users who want to see an example port to just use `portfile-gen` to output one.
Or we could just keep pointing them [http://guide.macports.org/chunked/development.examples.html to the Guide]. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:3> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by ryandesign@…): Replying to [comment:1 ryandesign@…]:
I vote for deleting the exampleport directory.
#39321 wants to delete the entire old "doc" directory. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:4> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by egall@…): Replying to [comment:4 ryandesign@…]:
Replying to [comment:1 ryandesign@…]:
I vote for deleting the exampleport directory.
#39321 wants to delete the entire old "doc" directory.
That's a different one. That's browser:trunk/doc (which I'm okay with because that's replaced by browser:trunk/doc-new with pretty much the same thing), while this is in browser:trunk/base/doc which is different. I agree though that having so many redundant "doc" directories can be kinda confusing... I would like one to remain in base though, as it's useful to have docs in the source tarball. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:5> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by larryv@…): Replying to [comment:5 egall@…]:
I would like one to remain in base though, as it's useful to have docs in the source tarball.
Useful to whom? If we deleted trunk/base/doc, I would bet a very large amount of money that no user would ever complain about it. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:6> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by cal@…): Replying to [comment:6 larryv@…]:
Useful to whom? If we deleted trunk/base/doc, I would bet a very large amount of money that no user would ever complain about it.
I'm willing to call that bet. Have you even looked at source:trunk/base/doc? It contains manpages, and all config file templates. Deleting it will render MacPorts unusable. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:7> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by egall@…): Replying to [comment:6 larryv@…]:
Useful to whom?
People who've downloaded the source tarball and don't want to open a web browser just to view documentation? It's common practice to include documentation in source tarballs; people expect docs to be in source tarballs, or else they wouldn't keep including them in their own source tarballs. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:8> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by ryandesign@…): Replying to [comment:5 egall@…]:
Replying to [comment:4 ryandesign@…]:
#39321 wants to delete the entire old "doc" directory.
That's a different one.
Oh... you're right, my mistake. Replying to [comment:8 egall@…]:
Replying to [comment:6 larryv@…]:
Useful to whom?
People who've downloaded the source tarball and don't want to open a web browser just to view documentation? It's common practice to include documentation in source tarballs; people expect docs to be in source tarballs, or else they wouldn't keep including them in their own source tarballs.
MacPorts documentation is fractured into many different sources: the guide, the main web site, the trac wiki, the manpages, and some random text files. Only the latter two have been included in our source tarballs thus far, and I have no especially urgent interest in including documentation from the other sources in the tarball. To my knowledge nobody has ever requested that. And as was stated, most of what's in the doc directory today is not intended for the user to look at directly. The only files that are are the INTERNALS file and the exampleport directory. Everything else is there to be installed with `make install`. There is a wide variety of software in the world, with many different ways of being built, and a correspondingly huge number of things that could appear in a portfile, limited only by the extents of the Tcl language. I really don't feel that a single so-called example port is useful, especially as it gets out of date over time. If the exampleport directory is to be kept at all, I'd prefer to replace its contents with a README that names a half dozen or so ports in the ports tree that would serve as good simple examples of various techniques. But the guide would probably be a more natural place for such documentation to go. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:9> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by larryv@…): Replying to [comment:7 cal@…]:
I'm willing to call that bet. Have you even looked at source:trunk/base/doc? It contains manpages, and all config file templates.
Hm, you’re right. I must have been thinking about one of the other 15 million “doc” directories, because I’ve definitely looked at these manpage sources before. My fault. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:10> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by larryv@…): Replying to [comment:8 egall@…]:
People who've downloaded the source tarball and don't want to open a web browser just to view documentation? It's common practice to include documentation in source tarballs; people expect docs to be in source tarballs, or else they wouldn't keep including them in their own source tarballs.
There’s a difference between the documentation that is //installed// and the documentation that is //only in the tarball//. I maintain that removing whatever documentation is not installed (e.g., moving `INTERNALS` somewhere else in the repository and deleting `exampleport`) would result in negligible, if not zero, complaints. (Excluding documentation that’s actually relevant to the distributing the source, like `LICENSE` and `NEWS`.) -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:11> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by egall@…):
There’s a difference between the documentation that is ''installed'' and the documentation that is ''only in the tarball''.
At least in my view, this is more of an argument for actually installing the documentation that is currently only in the tarball instead of one for deleting it. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:12> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by larryv@…): Replying to [comment:12 egall@…]:
At least in my view, this is more of an argument for actually installing the documentation that is currently only in the tarball instead of one for deleting it.
Or it’s an argument for considering whether this “documentation”—which by most accounts is not worth installing—should be kept around at all, especially when there is better documentation elsewhere. -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:13> MacPorts <http://www.macports.org/> Ports system for OS X
#39051: The example portfile in the "doc" folder of base should pass lint --------------------------+-------------------------------- Reporter: egall@… | Owner: macports-tickets@… Type: defect | Status: new Priority: Normal | Milestone: Component: base | Version: 2.1.3 Resolution: | Keywords: Port: exampleport | --------------------------+-------------------------------- Comment (by egall@…): anyway tabs were changed to spaces in r106666 so that's kind of a step, even if it doesn't actually silence any lint warnings -- Ticket URL: <https://trac.macports.org/ticket/39051#comment:14> MacPorts <http://www.macports.org/> Ports system for OS X
participants (1)
-
MacPorts