Local scribble HTML versus package installation from github

Questions & Answers
1

Hi

I have a directory without subdirectories. It contains a.scrbl and a.rkt. a.scrbl has:

@(defmodule "a.rkt" #:packages ())
@hyperlink["a.rkt"]{source-code}

I open a.scrbl in DrRacket and click scribble HTML. Works fine.
Now I upload the two files in a GITHUB repository my-repo and use the package manager of DrRacket to install the package. However, this does not work. In order to make it work I have to make two changes:

@(defform my-repo/a #:packages ())
@hyperlink["../../a.rkt"]{source-code}

Works fine too, but I find the necessary changes somewhat cumbersome. When I develop a package I work locally on my PC only in order to check that all goes well. When I agree with my updates, I upload all related files to my GITHUB repository, often forgetting to make the two changes shown above. I do have some kind of solution by adding variable local? to a.scrbl and defining two macros Defmodule and Hyperlink that render the correct forms depending on local? being true or false. This way I only have to make sure that the repository has local?=#f. Nevertheless, is there a simple solution to avoid the discrepancy between local work and installing from GITHUB? I have looked for a way that a scrbl file can detect whether it is used locally or for installation from GITHUB, but found nothing. How do others handle the discrepancy?

Thanks, Jos

1 Like
2

You can keep the second form only, and, on your local machine install the package as a directory link using raco pkg install ./package-folder, and use raco setup --pkgs package-name to build the documentation and raco doc package-name to check the documentation.

In the first case, you are using scribble to build a simple document, so the HTML file is generated in the same folder as the original scribble file and the "a.rkt" file. When installed as a package, the scribble document is built as package documentation and the HTML is placed in the "doc/package-name" subfolder, so you need to reference the file as "../../a.rkt".

However, I am not sure if this would work when the package documentation is published to "docs.racket-lang.org", as I don't believe the source files are copied to the documentation server, so the link will break there.

Alex.

2 Likes
3

Sounds like a job for define-runtime-path.

https://docs.racket-lang.org/reference/Filesystem.html#(part._runtime-path)

1 Like
4

Hi Alex and Jens Axel S

Thanks for your info.

Because you mention the possibility of a break I think I’ll stick to my macros and variable -local?-.

Not much of a problem, because usually I have a separate file with these and other macros.

I only have to check variable -local?- in this separate file. This makes local rendering easy by means of the Scribble HTML button in DrRacket. Installation from GITHUB remains easy by means of the package manager in DrRacket. The one and only difference between local and GITHUB being that on GITHUB I have to change #t to #f in the line (define local? #t). It would be nice, though, if I could replace this by (define local? (where-am-I?)) using a procedure or macro that can see whether I am local or installing from GITHUB. May be -current-directory- can help me.

Thanks again, Jos

DC369554041A4649A528B20B10730B39.png
DC369554041A4649A528B20B10730B39.png708×1 76 Bytes

5

I concocted the following.

#lang scribble/manual

@; Define constant -local?-.
@; Must be #t when running from local directory.
@; Must be #f when installing package from GITHUB.
@; Make sure the local directory-path does not contain both \Racket\ and \pkgs\.

@(require (for-syntax racket))

@(define-for-syntax local?
  (not
   (regexp-match
    (regexp ".*[\\]Racket[\\].*[\\]pkgs[\\].*")
    (path->string (current-directory)))))

@(begin-for-syntax
  (displayln
   (if local?
    "local rendering"
    "package installation from GITHUB")))

@;etc.

I work with Windows and the above code works for me. However, would this work on all platforms? Id est, does the current directory when installing from GITHUB contain both \Racket\ and \pkgs\ on all platforms?

6

Hi,

Does the following work?

@(require racket/runtime-path)
@(define-runtime-path source "a.rkt")
@(defform my-repo/a #:packages ())
@hyperlink[source]{source-code}
7

The hyperlink works.

You mean defmodule in stead of defform, I think.

However, I need another defmodule for local and for GITHUB.

(defmodule “a.rkt” #:packages ()) versus

(defmodule my-repo/a #:packages ())

My macro Defmodule (mark the capital D) uses -local?-.

I may have more hyperlinks to local files, for which I use my macro Hyperlink, which adds ../../.

I may change Hyperlink such as to use define-runtime-path.

DC369554041A4649A528B20B10730B39.png
DC369554041A4649A528B20B10730B39.png708×1 76 Bytes

8

@joskoot

I ran into the same problem today.
For a while I tried to make "myfile.rkt" work both locally and on the server, but I couldn't make it work.

Then I replaced the path with package/myfile and that worked fine for both locations.

Have you tried this?

(defmodule your-package-name/a #:packages ())
9

@soegaard
Yes. I use syntaxes Defmodule and nbhll, For example:

@(define-for-syntax local?
  (not
   (regexp-match
    (regexp ".*[\\]Racket[\\].*[\\]pkgs[\\].*")
    (path->string (current-directory)))))

@(define-syntax (Defmodule stx)
  (if local? #'(defmodule "interpreter.rkt" #:packages ())
             #'(defmodule another-tll/interpreter #:packages ())))

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

@(define nb nonbreaking)