@mflatt I know this is an old one and I just found it by chance. Is it correct to mark here https://github.com/racket/racket/commit/006ffc8ae385407be7fd91b0429becaed43ba677 scribble/srcdoc as deprecated?

I am curious, are there any example usages of scribble/srcdoc in the wild? Racket seems to encourage the separation of source and documention but I still find it easier to document APIs as I code on the same file.

@mbutterick Was the printed version of TfL also created in Pollen? Or since it was not web-based, you had to rely on other tools? https://legalsolutions.thomsonreuters.com/law-products/Practice-Materials/Typography-for-Lawyers-2018-ed/p/105523076

@pocmatos I’ve used scribble/srcdoc in some Frog docs: https://github.com/greghendershott/frog/search?q=srcdoc&unscoped_q=srcdoc (FWIW I found it more convenient to use a define-doc wrapper around proc-doc/names than to use it directly. The macro defines the function, the docs, and some examples/tests.)

Not sure I’d say Racket encourages separation of source and documentation. It’s more the case that it lacked a good way to combine them, until relatively recently. Much like it lacked a good way to combine source and tests, until submodules and (module+ test ___) was added. Then people started to use combined source/tests. scribble/srcdoc is more recent, and the ergonomics aren’t quite as spiffy, and people write fewer docs than tests <— is why I think there are so few examples in the wild.

I was wondering - were there any attempts in Racket to combine scribble + tests -> the tests would then be used as examples in documentation

I would envisage this could encourage people to write docs alongside the code and I always found docs with examples to be more meaningful

@mflatt Oh! I didn’t realize that manual action was needed to make it work the first time. Maybe I did this and forgot it, in an older Racket. And IIUC doing this in DrR would cause the pkg/lib package-suggestions-for-module to then work outside DrR (and in racket-mode).

I’ll try to do the equivalent of this in racket-mode. Probably do what you said: if mismatch then just set db to current catalogs config.

Thanks!

Sounds right. I just pushed a change to “gui-pkg-manager” to make DrRacket’s “Update” button work.

@githree Yes. Please see my message just before yours. :slightly_smiling_face:

Also here’s a direct link to the define-doc macro I wrote: https://github.com/greghendershott/frog/blob/b6acb6cb79555eb92d457cd2f99da1ee9036a5fb/frog/private/define-doc.rkt

(Caveat: I wrote that for my immediate need in Frog. It’s under private/. I’m not offering it as a role model. or correct in all scenarios.)

great - the name could be more meaningful though :stuck_out_tongue: Do you have any examples of its use - I couldn’t find single use on frog repository

oh, sorry, just found it

Again, may I suggest a message above. :smile: https://github.com/greghendershott/frog/search?q=srcdoc&amp;unscoped_q=srcdoc

Yes. :slightly_smiling_face:

No worries

I mean, I don’t love the result. A define-doc usage has a lot going on. There are pros and cons to shoving everything into one form, vs. simple proximity in the file. It’s kind of like using a separate (: ___) annotation form in TR, vs. putting the types in the define signature. Or like define/contract vs. (provide (contract-out ___)). It’s somewhat a matter of taste.

The one added wrinkle with this, though, is duplicating the argument names in two places.

That makes the “proximity” option a lot less appealing, for me.

So IDK all the possibilities for the ergonomics of this. If I thought my private define-doc macro were awesome sauce, I’d make a package. But I don’t and I didn’t. I’m just answering the “are there examples in the wild?” question. Yes, I have one. It is… an example. :slightly_smiling_face:

sure, thanks for the answer

what I am thinking about is more about moving definition of contracts + test to scribble file directly so, e.g. contract definition could be used to also generate scribble defproc + tests would then generate scribble examples. I am not sure it would even work - just an idea

defproc/contract and test-case/example

this would make writing contracts equivalent to writing documentation and writing tests equivalent to writing examples in this documentation so the gravity centre would move in the direction of scribble files.

@greg my suggestion wouldn’t shove everything into one form, instead contracts and tests would sit nicely under specific procedure section in the documentation… if it is at all feasible :grin:

I’m a bit distracted because I need to work on something else now, but. I think that seems like another good way people might want to do it. Feasible? I’m not sure how contracts defined in some.scrbl are effected for definitions in some.rkt. It seems like some.rkt must be the thing that provides the definitions with contract wrappers (e.g. via define/contract, contract-out, or friends). Maybe some.scrbl must provide contracts and some.rkt must require and use those…? I don’t immediately see how the pieces fit together the resulting ergonomics. But I’m not saying it would be impossible or bad. idk.

the crossreference is the main reason why I am not sure about feasibility

Yep. Oh also to run the tests in some.scrbl you need the definitions from some.rkt so um… ¯_(ツ)_/¯

You could just define the function some.scrbl and have no some.rkt at all. Instead of srcdoc you have docsrc. :slightly_smiling_face:

that would be full blown literate programming - I was thinking more about literate testing/contracting

scribble doc -> API to the src

Off the top of their head does anyone know of two packages supplying a module of the same name? e.g. pkg-a and pkg-b both supply a module foo? [Why: I want to exercise a package-suggestions feature for the case (require foo). I know I can write some Racket code to trawl all the supplied modules in catalogs to try to find an example, and this would be a fun exercise if I had more time, but first I’m trying “Dear Lazy Slack”.]

The pkg-build conflicts list has all of those: http://pkg-build.racket-lang.org/conflicts.txt

Thanks! (require no-debug/syntax) is a good test case; package suggestions are mischief and mischief-dev.

add prints to find out where its slow, and maybe cache slow things :/

@mflatt (Or whoever maintains the racket/serialize collection these days), is there a way I can intercept the deserializers dynamic-require and replace it with another module.

Or rather, is there any way I can give it a fallback if it fails to require the module.

deserialize-module-guard looks like it almost does what I want, but only gets run for its effects. (Which seem to be throwing errors.)

And if it doesn’t exist, would it be a bad idea to add a ‘fallback’ hook to the library?

@mflatt Something like this: https://github.com/racket/racket/pull/2147/commits

@leif That idea looks ok to me.

Okay cool. I’ll add docs and tests. Thanks. :slightly_smiling_face:

sad :(

At some point I learned that, when requiring modules within a collection, it’s best to use relative paths. I recall someone (Eli?) explaining why at the time. But… I no longer remember the why. I just keep doing it — even though sometimes it’s a bit ugly. e.g. in collection/private/sub/foo.rkt, something like (require "../../bar.rkt") instead of (require collection/bar.rkt). But recently I’m noticing code that doesn’t use relative paths. Maybe it used to matter, but doesn’t anymore? Or if it does still matter, why?

Is it better only because relative paths will still work even if you haven’t raco linked the collection, or raco pkg installed the collection as a package?

@greg I think the rule is that across your codebase you shouldn’t require the same module twice as both a file path and as a collection, but I’m not sure about that

Lately I’ve switched to exclusively using collection paths and it’s been a pleasant experience