scribble

scribble copied to clipboard

Goal: pages on docs.racket-lang.org should have a button labeled "Edit on GitHub" that opens the scribble file that generated the HTML file that's displaying the button.

This is an issue and not a PR because I'm not sure how to implement it.

Idea 1 (the dream) change Scribble to automatically add "edit on github" links to the drop-down that appears when you click headings (just below "link to this section"). ~~Guess this would only work for cloned packages.~~

Idea 2 (the less-wild dream) implement a --github <url> flag for the scribble command that uses the given url to generate the "edit on github" links for every page title / section.

Idea 3 (the easy-to-hack) put an @github-link[url] function in a scriblib library. Documentation authors need to explicitly call this function to put a button on their pages. (Instead of a button, maybe add a keyword to @section or @title)

The motivation is to increase the number of passing-by contributions—or, at least, make them easier. This started as a conversation on Slack with David Storrs, Ben Greenman, Sam Tobin-Hochstadt and myself.

---

I want to vouch for Idea 3. But, as someone that doesn’t host their Racket packages on GitHub—I use my own Git server—I’d say we add @edit-link instead of @github-link. No reason to tie the feature to GitHub, I believe. Also, I think it’s more principled. It is always correct and doesn’t rely on magic. At the cost of adding a burden to documentation authors, it’s true.

Alternatively, another idea that Sam Tobin-Hochstadt gave: have a form like the one in http://beautifulracket.com/explainer/lang-line.html. What it would do is up to debate. Send emails to the mailing list, maybe? The content/noise ratio could be a problem.

Idea 1 (the dream) change Scribble to automatically add "edit on github" links to the drop-down that appears when you click headings (just below "link to this section"). Guess this would only work for cloned packages.

Could you clarify why this only works for cloned packages? I'm not understanding that point. Can't this be inferred from the package name-to-source-URL mapping? Or is that not available during document rendering?

I would prefer option 1 or 2 with option 3 as an override, in the event of a section that presents some strange corner case.

Could you clarify why this only works for cloned packages? I'm not understanding that point. Can't this be inferred from the package name-to-source-URL mapping? Or is that not available during document rendering?

Oops, I didn't realize there was a package-name-to-source-URL mapping. (I see pkg-catalog-show can get the github url for packages like htdp, and (find-user-pkgs-dir) returns a directory with URLs for user packages.) Seems like the URL should be available when building Scribble documents in raco setup.

Some time ago on Racket Users I suggested a simple solution (last message in the thread): Correcting documentation à la Beautiful Racket

The idea is to simply use a hyperlink that will prepopulate the new github issue form with a title, possibly a location of the text to correct, etc. It could be done similar to the current Beautiful Racket implementation - but by clicking flag icon on the margin of the text it will lead the user to the github prepopulated form, eg: https://github.com/mbutterick/pollen/issues/new?title=foo&body=bar

Related: https://github.com/racket/racket/pull/874

This seems like a nice idea.

Does it work for non-github users too?

/Jens Axel

Den tir. 24. jan. 2017 kl. 19.36 skrev gregid [email protected]:

Some time ago on Racket Users I suggested a simple solution (last message in the thread): Correcting documentation à la Beautiful Racket https://groups.google.com/forum/#!topic/racket-users/HymtbQ7GEM0

The idea is to simply use a hyperlink that will prepopulate the new github issue form with a title, possibly a location of the text to correct, etc. It could be done similar to the current Beautiful Racket implementation - but by clicking flag icon on the margin of the text it will lead the user to the github prepopulated form, eg: https://github.com/mbutterick/pollen/issues/new?title=foo&body=bar

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/racket/scribble/issues/76#issuecomment-274894313, or mute the thread https://github.com/notifications/unsubscribe-auth/AAcLxdeW4zez4PBmnu_Y7cHUg_CujZI2ks5rVkSagaJpZM4LrhW- .

--

Jens Axel Søgaard

yes, I think that's a must for whatever we end up merging

EDIT: sam is right, I was thinking about source links (not editing) when I wrote this comment

I think enabling non-github editing in the browser would be a lot of extra work, and we should aim for that only after we have a solution that first just links to the source code.

I have started a proposal that is related to the discussion: #228

@soegaard: as to the github link - this would only work for registered github users.

is this still an issue? Please consider adding the label good first issue so it is findable:

Issues labeled good first issue in in Racket GitHub repositories