pkgs catalog docs manuals namespace

[Neil Van Dyke]

I think there should be a little more guidance/vigilance on file naming
of manuals, for packages that are listed in the official catalog.

I've seen a few instances of problems with this, including, something like:
* package "<a>-<b>" defining its sole manual with name "<b>", and there
was soon a package reasonably named "<b>";
* package "<a>" defining its manual with name "<b>", where "<b>" was a
not-unlikely name for a different package;
* package "<a>" defining its manual with name "<a>-doc", when what they
probably wanted was for the manual to be named "<a>" (even if they later
moved it from package "<a>" to a package named "<a>-doc").

Going slightly further, I think the defaults *for almost every non-core
package* should be emphasized more in the documentation:
* package is named "<a>";
* module is named "<a>" (no trying to do taxonomies in the name, nor
naming it differently than the package);
* files are all under directory "<a>/" (and no other package's files are
under that directory, and no trying to do taxonomies here);
* manual is named "<a>" (maybe don't even mention what to do about
multiple manuals per package, because you'll have a bigger problem with
inappropriate creation of multiple manuals, than for the rare instance
that that's actually appropriate)

I think, given the core-oriented flexibilities of the package system,
emphasizing these less-confusing default guidelines to the third-party
masses (like me) is a simple way to reduce fouling of the various
namespaces' stream, upstream of other developers.

Neil V.

[Jay McCarthy]

I suggest turning these comment into a pull request that updates the
docs on package creation ---
http://docs.racket-lang.org/pkg/getting-started.html#%28part._how-to-create%29
--- and maybe change that "raco pkg new" tool to enforce them.

Jay

> --
> You received this message because you are subscribed to the Google Groups
> "Racket Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-dev+...@googlegroups.com.
> To post to this group, send email to racke...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-dev/57153032.8020600%40neilvandyke.org.
> For more options, visit https://groups.google.com/d/optout.



--
Jay McCarthy
Associate Professor
PLT @ CS @ UMass Lowell
http://jeapostrophe.github.io

"Wherefore, be not weary in well-doing,
for ye are laying the foundation of a great work.
And out of small things proceedeth that which is great."
- D&C 64:33

[Neil Van Dyke]

I'm just proposing this Band-Aid idea, and leaving it to you guys'
discretion, whether you want to implement it.

(The package system and I keep cordial working relationship.)

Thanks,
Neil V.