contributing fixes to documentation

Stephen De Gabrielle

unread,

Apr 30, 2020, 5:49:33 AM4/30/20

to Racket Users

Yo Racketeers!

Someone recently mentioned that is was tricky to update documentation. it can be.

I thought I'd provide the steps I took to create a PR for the DrRacket documentation in the hope that they are useful for others who see an issue with documentation but finding locating the right scribble file a problem.

In my case I wanted to create a PR to update the 'Extending DrRacket' part of the DrRacket manual.

My steps were

1. click on the header of the heading in the manual, it opens up with a little link on how to link to that section note the path: scribblings/drracket/drracket.scrbl

Link to this section with

@secref["extending-drracket"

#:doc '(lib "scribblings/drracket/drracket.scrbl")]

2. go to the DrRacket repo and look for something matching that path.

It was buried a little but I found it at https://github.com/racket/drracket/blob/master/drracket/scribblings/drracket/drracket.scrbl

3. this scribble file is a list of includes, but I was able to match

https://docs.racket-lang.org/drracket/extending-drracket.html

with

@include-section["extending.scrbl"]

4. opening extending.scrbl I find the section I want to change

https://github.com/racket/drracket/blob/master/drracket/scribblings/drracket/extending.scrbl

#lang scribble/doc
	@(require "common.rkt"
	(for-label compiler/cm setup/parallel-build racket/promise))

	@(define racodoc '(lib "scribblings/raco/raco.scrbl"))

	@title[#:tag "extending-drracket"]{Extending DrRacket}

	DrRacket supports two forms of extension to the programming
	environment:

	@itemize[

(gmail formatted this weirdly)

5. For simple changes (e.g. typos) you can just list in place and create a PR

- for more complex changes you will need to fork the repo and rebuild the scribble to ensure it works before submitting the PR. e.g https://github.com/racket/drracket/pull/372

6. if you run into trouble ask here on racket-users, or on the Racket slack - there are many helpful racketeers out there.

Kind regards

Stephen

Stephen De Gabrielle

unread,

Apr 30, 2020, 5:55:20 AM4/30/20

to Racket Users

I'd forgotten the tutorial to contributing - someone kindly reminded me recently

https://blog.racket-lang.org/2017/09/tutorial-contributing-to-racket.html

This covers everything from fixing a typo to contributing to the racket language and the main distribution.

it is worth the read!

S

Dexter Lagan

unread,

Apr 30, 2020, 9:16:10 AM4/30/20

to Stephen De Gabrielle, Racket Users

Thanks, this guide is great. I'll make sure I fix whatever problem I find when I scour the docs. I do have a question however: say I find a typo in a function definition, is there any part of the doc that is automatically generated, and should not be updated, or updated with specific attention?

Dex

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/9e7438ef-0a7d-4660-a5ba-c2bb41928a3c%40googlegroups.com.

Stephen De Gabrielle

unread,

Apr 30, 2020, 12:58:02 PM4/30/20

to Dexter Lagan, Racket Users

I think there are tiny bits of documentation that are automatically generated(OpenGL?), but I think they are well labeled.