Documentation categories

General
,
1

Hi all

I recently noticed that we have documentation for many collections/packages listed in the Miscellaneous Libraries section of https://docs.racket-lang.org/

There are lots of useful categories available so if you maintain a package or want to help a maintainer help users find their package please make a PR to set an appropriate category.

I’ve put some examples and copied the list of categories below to help you get started but please don’t hesitate to ask if you need a hand.

Best regards
Stephen :beetle:

The example I noticed was SICP (#lang sicp) was not listed in the category “Other Languages in the Racket Environment”, but ended up in the catch-all of Miscellaneous Libraries.

This is easy to fix by adding the category to the third part of the definition of scribblings in info.rkt file for the collection/package documentation.

Some examples of setting a category:

#lang info

(define scribblings '(("sicp-manual.scrbl" (multi-page) (language))))

This is documented in raco: Racket Command-Line Tools section 6.3 Controlling raco setup with "info.rkt" Files:

The category list specifies how to show the document in the root table of contents. The list must start with a category, which determines where the manual appears in the root documentation page. A category is either a string or a symbol. If it is a string, then the string is the category label on the root page. If it is a symbol, then a default category label is used. The available symbols and the order of categories on the root documentation page is as below:

  • 'getting-started : High-level, introductory documentation, typeset at the same level as other category titles.
  • 'language : Documentation for a prominent programming language.
  • 'tool : Documentation for an executable.
  • 'gui-library : Documentation for GUI and graphics libraries.
  • 'net-library : Documentation for networking libraries.
  • 'parsing-library : Documentation for parsing libraries.
  • 'tool-library : Documentation for programming-tool libraries (i.e., not important enough for the more prominent 'tool category).
  • 'interop : Documentation for interoperability tools and libraries.
  • All string categories as ordered by string<=?.
  • 'library : Documentation for libraries; this category is the default and used for unrecognized category symbols.
  • 'legacy : Documentation for deprecated libraries, languages, and tools.
  • 'experimental : Documentation for an experimental language or library.
  • 'other : Other documentation.
  • 'omit : Documentation that should not be listed on the root page or indexed for searching.
  • 'omit-start : Documentation that should not be listed on the root page but should be indexed for searching.
2

On the topic of categories...

If use a string for the category in scribblings you can create a category for the package,
e.g. (define scribblings '(["scripty.scrbl" () ("Scripting")])) in https://github.com/lexi-lambda/scripty/blob/master/scripty-doc/scribblings/info.rkt creates

image
image1332×416 31.4 KB

Please do this! - but check for other packages that and use the same category string.

Best regards,

Stephen

3

I got excited and started creating PR's to specify categories, but @sorawee suggested:

A perhaps better approach is to introduce a new symbol that raco setup understands. This would be better discussed on Discourse.

I've made a PR that adds a category drracket-plugin to be rendered as "Dr Racket Plugins" (https://github.com/racket/racket/pull/4687) for discussion as suggested.

best regards,
Stephen

1 Like
4

I'm thinking a bit about this PR and the upcoming release. I'm a bit worried that this creates a compatibility problem where libraries that use this symbol will now cause errors when installed on earlier versions of Racket, because they use an unknown symbol. This is not really a problem with this PR, so much, it's a general problem with adding any symbols to the list of acceptable ones.

Perhaps someone has already anticipated this problem; does the current racket build ignore unknown symbols, or signal an error? I will investigate, if I don't hear back from y'all.

5

I raised this backward compat issue in https://github.com/Metaxal/quickscript/pull/69. IIUC, it defaults to "Misc" if the symbol is not recognized.

6

Oh, excellent. That solves that problem, thanks!

7

I’ve been meaning to add a note to the manual to make it clear

Libraries using symbols not in the list below are added to the Miscellaneous Libraries category on the documentation index page.

S.