[racket-dev] current packages' docs, errors, and conflicts

At Tue, 8 Jul 2014 09:08:34 -0400, Sam Tobin-Hochstadt wrote:
> On Tue, Jul 8, 2014 at 8:14 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> > At Tue, 08 Jul 2014 14:08:27 +0200, Jan Dvořák wrote:
> >> On Tue, 2014-07-08 at 12:46 +0100, Matthew Flatt wrote:
> >> > The rightmost column of the table may need some explanation. The column
> >> > highlights conflicts among names of package-installed executables,
> >> > foreign libraries, and documents. Currently, all the conflicts are
> >> > document names, because several packages have a documents named simply
> >> > "manual" or "main".
> >>
> >> Can you provide some guidelines on docs naming?
> >> I am responsible for half of the conflicts. :-)
> >
> > A package "X" that provides a collection "X" of the same name should
> > probably also call its documentation "X".
> >
> > If the package provides both "guide" and "reference" documentation,
> > then "X-guide" and "X-reference" are good choices.
> >
> >
> > Thanks for looking into this! I've recently updated the Racket
> > documentation, but I expect that more is needed. As far as I can tell,
> > nothing in our documentation previously suggested that documentation
> > names needs to be distinct.
> 
> Is there a reason we can't just make this work with duplicate names
> instead? Perhaps disambiguiating by collection name?
> 
> I think this would change all the current URLs on
> docs.racket-lang.org, so we'd have to fix that, but it seems better to
> make us do a fixed amount of work rather than push this coordination
> problem onto everyone who writes packages in the future.

I think that documentation names could be disambiguated in that way,
but it's a significant chunk of work to switch. To pick one non-obvious
interaction, the way that "local-redirect" plugs in to link documents
would have to be adjusted.

A more compatible and probably easier direction would be a variant of
`scribblings` that tends to distinguish document names and that becomes
the preferred form.

Since it's not a huge burden on package authors or an especially big
obstacle for existing packages, I'd prefer to put this problem aside
for now.