Documentation Categories

[Jay McCarthy]

If you take a look at

http://pkg-build.racket-lang.org/doc/

You'll see that basically all manuals for packages are under the
"Miscellaneous Libraries" category. A small part of this is because
the authors don't know how to use the other categories, described
here:

http://pkg-build.racket-lang.org/doc/raco/setup-info.html?q=getting-started#%28idx._%28gentag._4._%28lib._scribblings%2Fraco%2Fraco..scrbl%29%29%29

However, I think the majority of the reason is that the existing
categories are not appropriate for packages like compiler-goodies,
glob, GLU tessellation, etc.

I've just pushed a commit that allows arbitrary strings to be used as
the categories. These categories are then sorted and put before the
"Miscellaneous" category on the documentation page. Over time, I
expect that we will discover common categories worth coordinating on
(for instance, do we have "Graphics" and "3D Graphics" as separate
ideas?) Here's an example:

(define scribblings '(("openal.scrbl" () ("Audio"))))

I briefly considered enabling a manual to be in many categories and
writing a tag-style interface, but instead went with this smaller
first cut approach.

Please make use of this feature.

Jay

--
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

[Alexis King]

Ooh, this is very nice. I’ve consulted the list of categories a few times,
and I’ve never really found anything obvious to use for any of my packages
aside from the default 'library. Are there plans to move any of the packages
in the main distribution into other, more specific names with this change?
That might be a good way to create some obvious buckets for people to put
their packages in.

> --
> 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/CAJYbDanmBM4CUDXOO-fsrmfw_pXeACPOJHH4Ww2bWuvBBT90Sg%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

[Jon Zeppieri]

On Sat, Dec 19, 2015 at 5:04 PM, Jay McCarthy <jay.mc...@gmail.com> wrote:

If you take a look at

http://pkg-build.racket-lang.org/doc/

You'll see that basically all manuals for packages are under the
"Miscellaneous Libraries" category. A small part of this is because
the authors don't know how to use the other categories, described
here:

http://pkg-build.racket-lang.org/doc/raco/setup-info.html?q=getting-started#%28idx._%28gentag._4._%28lib._scribblings%2Fraco%2Fraco..scrbl%29%29%29

However, I think the majority of the reason is that the existing
categories are not appropriate for packages like compiler-goodies,
glob, GLU tessellation, etc.

I think you're right in both cases.

I didn't know about scribble categories. I *did* know about the tagging feature at http://pkgs.racket-lang.org/ (which is independent of the package info, IIRC).

 

I've just pushed a commit that allows arbitrary strings to be used as
the categories. These categories are then sorted and put before the
"Miscellaneous" category on the documentation page. Over time, I
expect that we will discover common categories worth coordinating on
(for instance, do we have "Graphics" and "3D Graphics" as separate
ideas?) Here's an example:

(define scribblings '(("openal.scrbl" () ("Audio"))))

I briefly considered enabling a manual to be in many categories and
writing a tag-style interface, but instead went with this smaller
first cut approach.

I do think this is a good idea, but I also think it might be confusing for the package server to have its own, completely distinct, categorization scheme.

 

Please make use of this feature.

Will do.

-Jon

 

Jay

--
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

[Vincent St-Amour]

Great idea! Thanks for doing this.

I've just fixed my packages, and introduced "Performance Tools",
"Slideshow Libraries" and "Scribble Libraries" categories.

Vincent

[Jay McCarthy]

On Sat, Dec 19, 2015 at 5:20 PM, Alexis King <lexi....@gmail.com> wrote:
> Ooh, this is very nice. I’ve consulted the list of categories a few times,
> and I’ve never really found anything obvious to use for any of my packages
> aside from the default 'library. Are there plans to move any of the packages
> in the main distribution into other, more specific names with this change?
> That might be a good way to create some obvious buckets for people to put
> their packages in.

Yes, and I consider this message to be an email to those maintainers
as much as others on p.r-l.o :)

Jay

[Benjamin Greenman]

Does the package server support these new categories?
I converted a few of my packages to use string categories,

but now the scribblings don't appear on pkgs.racket-lang.org.

benchmark & feature-profile seem to have the same issue

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-dev/CAJYbDa%3DKh6h6CS%3DiHuz7zNQ0mQSv-Nf9N6gG8WwZeecV%3Dm8KDQ%40mail.gmail.com.

[Matthew Flatt]

At Tue, 5 Jan 2016 12:37:38 -0500, Benjamin Greenman wrote:
> Does the package server support these new categories?

The package-build service doesn't support them, yet, because it uses
the current release.

When version 6.3 encounters the new form, it reports a warning and
continues without rendering the document.

[Matthew Flatt]

Just to emphasize and clarify: Please beware that using a string
category is not compatible with v6.3 and earlier.

Although `raco pkg install` (or `raco setup`) will merely issue a
warning about a `scribblings` entry that it doesn't recognize, not
recognizing the entry means that the documentation will not get
installed for someone using v6.3.

The pkg-build service will start to support categories string with the
v6.4 release. Unfortunately, the compatibility issues with v6.3 and
earlier will remain.

So, if you'd like to use the new category string for your
documentation, consider registering an alternative package source for
v6.3 and earlier releases, or consider delaying the change until
compatibility with v6.3 and earlier (as least as far as documentation
goes) is no longer a concern.

> --
> 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/20160105180002.0C64D650069%40mail-
> svr1.cs.utah.edu.