Local versus github links in scribble

Questions & Answers
1

local versus github links in scribble

defmodule and hyperlinks act differently when installing from github or locally.
I resolved the problem as follows:

@(define-for-syntax local #f)
@; set to #t when installing locally

@(define-syntax (nbhll stx)
   (syntax-case stx ()
     ((_ x y ...)
      (if local
        #'(nb (hyperlink x y ...))
        #'(nb (hyperlink (string-append "../../" x) y ...))))))

@(define-syntax (Defmodule stx)
   (if local
     #'(defmodule "some-file.rkt" #:packages ())
     #'(defmodule some-file/some-file #:packages ())))

(nb stands for non-breaking)
I guess there is a simpler method, may be a variable to be defined in an info file???

2

Can you elaborate more on what the problem is?

IIRC, someone said that the module path to defmodule should never be relative, so I am skeptical that (defmodule "some-file.rkt" #:packages ()) will work well.

3

I am almost certain that you need to use one of the command line options from:

https://docs.racket-lang.org/scribble/running.html#(part._xref-flags)

But I am not sure which one.

4

I don’t personally do anything to make my scribblings (package documenation) behave differently for local vs other forms of installation. Even my GitHub Actions to deploy docs use the same files.

5

Well, I’ll stick to my two syntaxes. After making and testing all locally, the only thing I have to do when transferring my stuff to GITHUB, is to change variable local from #t to #f. Easy enough.

324ADA0EF8D34B2E9DDEC96E1494687E.png