Skip to content

Minor documentation touch-up #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
aanastasiou wants to merge 3 commits into from
Closed

Minor documentation touch-up #61

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9097579
Minor documentation touch-up by transfering useful snippets from the …
aanastasiou Jul 27, 2025
a4fd979
Minor typos flagged in the notes of the PR and addition of the biblio…
aanastasiou Jul 28, 2025
3a3924a
Correction of the quickstart.scrbl lost indentation of codeblocks
aanastasiou Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion gui-easy/gui/easy/scribblings/escape-hatches.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@
racket/gui/easy
racket/gui/easy/operator))

; Example links cited within this section
@(define example-link-close-window
(link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/close-window.rkt"
@filepath{examples/close-window.rkt}))

@title{Escape Hatches}

Some views take a @racket[#:mixin] argument that can be used to alter
Expand All @@ -14,5 +19,5 @@ as ``escape hatches'' when the library doesn't provide a piece of
functionality you need, but that functionality is available on the
native widget.

See "examples/close-window.rkt" for a example of using a mixin to
See @|example-link-close-window| for an example of using a mixin to
programmatically toggle a window's visibility.
4 changes: 2 additions & 2 deletions gui-easy/gui/easy/scribblings/gui-easy.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
@title{@tt{gui-easy}: Declarative GUIs}
@author[(author+email "Bogdan Popa" "[email protected]")]

This library provides a declarative API on top of
@racketmodname[racket/gui].
The goal of GUI Easy is to simplify user interface construction in Racket
by wrapping the existing imperative API (@racketmodname[racket/gui]) in a functional shell.

@(define-runtime-path youtubestub.tex "youtubestub.tex")
@(define embed-style
Expand Down
18 changes: 17 additions & 1 deletion gui-easy/gui/easy/scribblings/quickstart.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,16 @@

@title{Quickstart}

gui-easy can be broadly split up into two parts: observables and views.

Observables contain values and notify subscribed observers of changes to
their contents and Views are representations of Racket GUI widget trees
that, when rendered, produce concrete instances of those trees and handle
the details of wiring state and widgets together.

The core abstractions of observables and views correspond to a model-view-controller
(MVC) architecture for graphical applications as popularized by Smalltalk-80.

@section{Hello, World!}

@centered[@image[(build-path media "1.1-hello-world.png") #:scale 0.5]]
Expand Down Expand Up @@ -154,5 +164,11 @@ individual counter by passing in a derived observable to its

@(define repo-link
(link "https://github.com/Bogdanp/racket-gui-easy" "Git repository"))
@(define easygui-publications-funarch23
Copy link
Contributor

@benknoble benknoble Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't remember the details offhand, but there are ways to put citations in Scribble documents (the Racket manuals do this, for example).

There may also be a better link than arXiv, although arXiv is potentially more accessible. See also links collected in this Discourse post.

Copy link
Owner

@Bogdanp Bogdanp Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://docs.racket-lang.org/scribble/Bibliography.html#(part._.Bibliography)

Copy link
Contributor Author

@aanastasiou aanastasiou Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the accessibility was what I had in mind when I opted for Arxiv.

When added, the bibliography section stood a bit bare. The repo-link is only used once across the docs so I thought I would turn that into a bib-entry too, which makes it more visible overall, especially when arriving to the docs via DrRacket's context sensitive help. There are not many citations in this document and links would appear more consistent and don't break the flow of reading. But in any case, we now have both versions and can decide which one to go for.

(link "https://arxiv.org/abs/2308.16024" """D. B. Knoble and B. Popa, ‘Functional Shell and
Reusable Components for Easy GUIs’"""))


For more examples, see the "examples" directory in the @|repo-link|.
For more information about the core concepts of gui-easy and its design,
see @|easygui-publications-funarch23|. For more examples, see the "examples"
directory in the @|repo-link|.
30 changes: 27 additions & 3 deletions gui-easy/gui/easy/scribblings/reference.scrbl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,17 @@
racket/gui/easy/operator
(prefix-in gui: racket/gui)))

; Example links cited within this section
@(define example-link-tabs
(link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/tabs.rkt"
@filepath{examples/tabs.rkt}))
@(define example-link-list
(link "https://github.com/Bogdanp/racket-gui-easy/blob/master/examples/list.rkt"
@filepath{examples/list.rkt}))




@title{Reference}
@defmodule[racket/gui/easy]

Expand Down Expand Up @@ -64,6 +75,19 @@

@section{Views}

@deftech{View}s are functions that return a @racket[view<%>] instance.

Views might wrap a specific GUI widget, like a text message or button, or
they might construct a tree of smaller views, forming a larger component.

Views are typically @tech{Observable}-aware in ways that make sense for ach individual view.
For instance the text view takes as input an observable string and the rendered text label updates
with changes to that observable.

Many @racketmodname[racket/gui] widgets are already wrapped by GUI Easy, but programmers can
implement the @racket[view<%>] interface themselves in order to integrate arbitrary widgets, such as
those from 3rd-party packages in the Racket ecosystem, into their projects.

@subsection[#:tag "windows&dialogs"]{Windows & Dialogs}

@defproc[(window [#:title title (maybe-obs/c string?) "Untitled"]
Expand Down Expand Up @@ -285,7 +309,7 @@
selection changes to an adjacent tab). When tabs are reordered, the
choices provided to the action represent the new tab order.

See @filepath{examples/tabs.rkt} for an example.
See @|example-link-tabs| for an example.

@history[
#:changed "0.3" @elem{Added the @racket[#:choice=?] argument.}
Expand Down Expand Up @@ -354,7 +378,7 @@
procedure must return a unique value for each entry in the list, as
compared using @racket[equal?].

See @filepath{examples/list.rkt} for an example.
See @|example-link-list| for an example.
}

@defproc[(observable-view [data (obs/c any/c)]
Expand Down Expand Up @@ -818,7 +842,7 @@

@section{Observables}

@deftech{Observables} are containers for values that may change over
@deftech{Observable}s are containers for values that may change over
Copy link
Owner

@Bogdanp Bogdanp Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I missed this this morning, but deftech works fine with plurals (so you can @deftech{Views} and then use both @tech{view} and @tech{views} to refer to something). I'll fix before merging.

time. Their changes may be observed by arbitrary functions.

@; Require the private module to avoid requiring racket/gui/base.
Expand Down