add package-source style property

[bennn]

If a part has the package-source property, then attach a URL to the HTML output so that the manuals can show a link to the "Document source" for editing / pull-requesting.

For example:

That picture came from this code:

@title[#:tag "top" #:style (make-style #f (list (github-source-url 'bennn 'with-cache)))]{with-cache}

---

Another example, using GitLab:

Source code:

@title[#:style (make-style #f (list (gitlab-source-url 'bengreenman 'pict-abbrevs)))]{Pict Abbrevs}

---

Both the above work very nicely because the source is a single file. If a document uses include-section, then sub-parts inherit the parent's URL.

For example these two links in the redex docs:

Come from one line of code, but sadly point to the same source file:

@title[#:style (make-style #f (list (github-source-url 'racket 'redex #:path 'redex-doc)))]{Redex: Practical Semantics Engineering}

---

A sub-part can manually give a more specific URL:

@title[#:style (make-style #f (list (exact-source-url "https://github.com/racket/redex?path=redex-doc/redex/scribblings/ref.scrbl")))]{The Redex Reference}

But I haven't figured out a nice way to infer a better URL.

And really, ideally, I'd like to put one base URL in the scribblings entry of an info.rkt and get precise URLs without any changes to the document. So, suggestions are definitely welcome.

[bennn]

related issues: #208 #76

[samth]

I think we should close racket/racket#874 since this subsumes that, and we should merge this as the first step.

[samth]

Note that another possibility is to do this entirely with JavaScript -- just query the pkg server for the source package.

[bennn]

JavaScript sounds better. If we merged this as-is, we'd need to edit every Scribble file that needs a link.

[samth]

Here's the algorithm we want:

Look at the x-source-pkg attribute of the element. For https://docs.racket-lang.org/reference/More_Path_Utilities.html for the top title that's racket-doc. Then you fetch https://pkgd.racket-lang.org/pkgn/pkg/racket-doc.json. Then that JSON document has a "versions" key which has a "default" key which has a "source" key, which is "git://github.com/racket/racket/?path=pkgs/racket-doc" for that document.

Then we probably need to process that URL a little, to get: https://github.com/racket/racket/tree/master/pkgs/racket-doc and then add in the value of the x-source-module attribute. That's (lib "scribblings/reference/reference.scrbl") in this case, which we need to extract the string, and then combine them, to get https://github.com/racket/racket/tree/master/pkgs/racket-doc/scribblings/reference/reference.scrbl which is what we want to link to.

[samth]

That's basically the simplest case we need to handle, although some source URLs won't have ?path. Other URLs will have a specification for the branch as well, and some will not be on GitHub where we won't know what to do. In general, a basic implemenation that just handled that example and ones without ?path, only for GitHub, would be a great start.

[gregid]

Since this PR and renewed discussion has been one of the reason for me outlining the proposal for the possible long term solution in the issue: #228, I am referencing it here. It doesn't address the solution to be implemented right away unlike the one proposed by @samth but once overhauled it would make implementing this type of changes really simple with RDFa + JSON-LD.