At Tue, 8 Jul 2014 09:08:34 -0400, Sam Tobin-Hochstadt wrote: > On Tue, Jul 8, 2014 at 8:14 AM, Matthew Flatt <mfl...@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. _________________________ Racket Developers list: http://lists.racket-lang.org/dev
