@cky I found your s/o question about ffi/libusb. did you ever make progress? i’m trying to learn all the ffi stuff now and its overwhelming

overwhelming was the wrong word choice, sorry. the ffi library and documentation are fantastic from what i understand of them, i just haven’t put in the effort to understand it all properly. i am feeling a little overwhelmed with trying to figure it all out :grin:

how do I do a simple hyperlink in scribble?

@danl-ndi: hyperlink

I can’t figure hyperlink out O_o

@url{asdf} works, but I want different text in the doc

@hyperlink{"http://…"} is not it

@hyperlink["http://..."]{text here}

urg I’m so sure I tried exactly that.

yes, that’s it, thanks.

yeah @ expressions are fun … maybe I should have said @hyperlink["http://...." "text here"]

so those are the same?

yes

also @(hyperlink "http://..." "text here")

in the docs, “pre-content” is an opaque term to see when parachuting in to that section.

ah, i see

try http://docs.racket-lang.org/scribble/reader.html

that section is confusing….

it seems to be saying that @asdf[a b c] is the same as (asdf a b c)? but you need an ’@’ for the 2nd expression too…..

I think I go in to scribble docs with the same mindset as markdown or restructured text, but it’s really a steeper learning curve

oh I think those examples are from different #langs

yeah definitely steeper learning curve. I feel like I learned just from examples / trying things, and the docs only make sense in retrospect

@ben: That’s been my experience as well, and of most people I’ve seen learn scribble.

yeah, it’s very powerful and cool, but it’s not simply a markup language…

I find scribble makes a lot of sense if you have used LaTeX before

(and Racket, of course)

yes, it’s more on the level of LaTex

tbh I found scribble much, much easier to understand than LaTeX because it’s a far more predictable/consistent model

once you’ve mastered #lang, that is :stuck_out_tongue:

I think scribble can be relatively easily understood as two modes—expression mode and text mode—and a set of translation rules

in #lang scribble/manual, the top level is in text mode

using @ in text mode transitions into expression mode, and @foo{...} transitions back into text mode

everything inside @foo[...] or @(...) is in expression mode

the @ syntax is still permitted in expression mode, but it isn’t required, and all Racket syntax is permitted

stamourv: thinking more, I guess I had the same experience with LaTeX

hmm… I appreciate that description, but it kind of lost me a little. What I struggle with here (and in other areas of Racket docs, like syntax-parse) is that I’d learn it so much more quickly with a series of basic to intermediate examples.

Yeah, LaTeX is similar, but much much worse.

I agree that both scribble and syntax/parse could use more examples

Maybe it’s a guide vs reference thing?

they’re both missing what LaTeX does have, which is scores of frustrated users who work it out and write tutorials and examples to teach themselves

Good point.

(adding to my todo list)

racket needs more frustrated users :smile:

:)

oh about syntax/parse, I’ve been wanting to put a “syntax/parse recipes” post on the racket blog

and encourage contributions from everyone

wouldn’t a wiki be a better fit?

the syntax-parse docs have the bones of a great set of examples

andreiformiga: good point (maybe just announce it via the blog)

sure

maybe a gh wiki, considering everyone has a github account nowadays

ben: implementing for, cond, and/or struct end-to-end would be great examples

yeah, on racket/racket

If it’s gonna be in a wiki or other more-permanent-than-blog-post kind of thing, I’d rather it be an actual Scribble document included in the docs and linked from the docs for syntax-parse

dear lazy slack how can I prevent conversion of -- to an ndash in Scribble — and do so inline? I tried @tt{--foo}, @tt\|{--foo}\| but no joy. @verbatim\|{--foo}\| works but forces a block.

@greg: I think you want literal

@lexi.lambda thanks!