Skip to content

Docs tweaks #60

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

Merged
merged 2 commits into from
May 13, 2024
Merged

Docs tweaks #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0be209b
Better hint at the package capabilities in readme
tecosaur May 12, 2024
6901610
Mention the importance of semantic names in docs
tecosaur May 12, 2024
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
11 changes: 11 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,14 @@
The `StyledStrings` package builds on top of the `AnnotatedString` type to
provide a full-fledged textual styling system, suitable for terminal and
graphical displays.

This is primarily intended for package authors, who may think of this as
`printstyled` on a (rather potent) steroids 😉. To get a better sense of what
this means in practice, start with the [examples
page](https://julialang.github.io/StyledStrings.jl/dev/examples/) of the
documentation and look for how other packages use `StyledStrings` in the Julia
ecosystem.

This is a standard library as of Julia 1.11. A version compatible with Julia 1.0
through to 1.10 has also been registered in General — allowing `StyledStrings`
to be used anywhere without compromising compatibility.
6 changes: 6 additions & 0 deletions docs/src/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,12 @@ styled"{(underline=warning):this is some minor/slight warning text}"
styled"A very major {(fg=error,bg=warning),bold:warning!}"
```

!!! tip "Focus on semantics, and let style follow"
Note that when using faces, it is generally recommended to focus on the
*semantic intent*, not the specific styling (`cyan`, `bold`, etc.),
introducing new faces when there is no pre-existing semantically appropriate
face.

## Inline face attributes

Should you want to use a particular color just once, the `foreground`/`fg` and `background`/`bg` inline face attributes can be set to hex codes.
Expand Down
10 changes: 8 additions & 2 deletions docs/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,14 @@ easily [customized](@ref stdlib-styledstrings-face-toml).
by the package name, i.e. follow the format `mypackage_myface`.
This is important for predictability, and to prevent name clashes.

There is one set of exemptions to the package-prefix rule, the set of basic
faces that are part of the default value of the faces dictionary.
Furthermore, packages should take care to use (and introduce) *semantic*
faces (like `code`) over direct colours and styles (like `cyan`). This is helpful
in a number of ways, from making the intent in usage more obvious, aiding
composability, and making user customisation more intuitive.

There are two set of exemptions to the package-prefix rule:
- the set of basic faces that are part of the default value of the faces dictionary
- faces introduced by Julia's own standard library, namely `JuliaSyntaxHighlighting`

#### [Basic faces](@id stdlib-styledstrings-basic-faces)

Expand Down