Minimal change to documentation #6229
Open
+8
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Author
|
Fixes issue #5011 |
willmcgugan
requested changes
Dec 6, 2025
docs/getting_started.md
Outdated
| ## Requirements | ||
|
|
||
| Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs. | ||
| Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs. You also need a unicode font that includes the line drawing and block characters, which are used to render the controls. |
Member
There was a problem hiding this comment.
This is going to confuse many developers who aren't familiar with these terms. I think we can drop this sentence.
docs/getting_started.md
Outdated
|
|
||
| All Linux distros come with a terminal emulator that can run Textual apps. | ||
|
|
||
| The linux console is more limited and not all fonts are suitable. See [Linux console]](./linux-console.md) for details. |
Member
There was a problem hiding this comment.
May devs will not know the difference between the linux console and the terminal on their desktop.
Suggest clarification:
"If you are using the Linux console (rather than a desktop environment), see Linux Console ...]"
docs/linux-console.md
Outdated
| @@ -0,0 +1,5 @@ | |||
| ## Linux Console | |||
|
|
|||
| The Linux console has limited capabilities, to maintain back compatibility with legacy VGA hardware. It supports unicode but colours are restricted and the fonts have very limited numbers of glyphs. There is a choice of 256 glyphs with 16 colors or 512 glyphs with 8 colors. Textual really needs more than 8 colors, so a font with 256 glyphs is needed. The console uses fonts in a special PSF file type; these are often in the directory /usr/share/consolefonts/. | |||
Member
There was a problem hiding this comment.
Sorry, but this copy is difficult to parse. Many people reading this will be far less technical that you.
Let's keep it simple. Something along these lines:
The Linux console is less graphically capable than the terminal emulator on your desktop.
If you find your app does not look great with the default configuration, see font-for-textual for a possible solution.
You can be as technical as you like in your repo!
Author
|
Happy with all of that, completely agree.
I will re-sync with main, make the suggested changes, and update the PR.
Thank you for your help.
…On Sat, Dec 6, 2025 at 4:57 PM Will McGugan ***@***.***> wrote:
***@***.**** requested changes on this pull request.
------------------------------
In docs/getting_started.md
<#6229 (comment)>:
> @@ -3,14 +3,16 @@ All you need to get started building Textual apps.
## Requirements
-Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs.
+Textual requires Python 3.9 or later (if you have a choice, pick the most recent Python). Textual runs on Linux, macOS, Windows and probably any OS where Python also runs. You also need a unicode font that includes the line drawing and block characters, which are used to render the controls.
This is going to confuse many developers who aren't familiar with these
terms. I think we can drop this sentence.
------------------------------
In docs/getting_started.md
<#6229 (comment)>:
>
!!! info "Your platform"
### :fontawesome-brands-linux: Linux (all distros)
All Linux distros come with a terminal emulator that can run Textual apps.
+ The linux console is more limited and not all fonts are suitable. See [Linux console]](./linux-console.md) for details.
May devs will not know the difference between the linux console and the
terminal on their desktop.
Suggest clarification:
"If you are using the Linux console (rather than a desktop environment),
see Linux Console ...]"
------------------------------
In docs/linux-console.md
<#6229 (comment)>:
> @@ -0,0 +1,5 @@
+## Linux Console
+
+The Linux console has limited capabilities, to maintain back compatibility with legacy VGA hardware. It supports unicode but colours are restricted and the fonts have very limited numbers of glyphs. There is a choice of 256 glyphs with 16 colors or 512 glyphs with 8 colors. Textual really needs more than 8 colors, so a font with 256 glyphs is needed. The console uses fonts in a special PSF file type; these are often in the directory /usr/share/consolefonts/.
Sorry, but this copy is difficult to parse. Many people reading this will
be far less technical that you.
Let's keep it simple. Something along these lines:
The Linux console is less graphically capable than the terminal emulator
on your desktop.
If you find your app does not look great with the default configuration,
see font-for-textual <https://github.com/jsatchell/font-for-textual> for
a possible solution.
You can be as technical as you like in your repo!
—
Reply to this email directly, view it on GitHub
<#6229 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AC4N6MFGSXUCS6WVTMVB5KL4AMDGRAVCNFSM6AAAAACMDYVK2OVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTKNBXHEYDENBZGQ>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Author
|
My head is updated with changes that, I hope, fix your concerns. Will also make sure the README for font-for-textual is as clear as possible! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Please review the following checklist.
Small change to introduction of documentation, calling out to more detail in new Markdown file.