diff --git a/.gitignore b/.gitignore index 6240da8b..e5bc5793 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,5 @@ pnpm-debug.log* # macOS-specific files .DS_Store + +bun.lockb diff --git a/bun.lockb b/bun.lockb new file mode 100755 index 00000000..45b83642 Binary files /dev/null and b/bun.lockb differ diff --git a/src/consts.ts b/src/consts.ts index bd2a8761..6fefade7 100644 --- a/src/consts.ts +++ b/src/consts.ts @@ -37,6 +37,7 @@ export const SIDEBAR: Sidebar = { { text: "Getting Ultramarine", link: "en/installation/getting" }, { text: "Installation", link: "en/installation/installation" }, { text: "Post-Installation", link: "en/installation/postinstall" }, + { text: "Advanced Post-install steps", link: "en/installation/post-advanced" } ], Contributing: [ { text: "Overview", link: "en/contributing/contributorguide" }, @@ -62,7 +63,10 @@ export const SIDEBAR: Sidebar = { { text: "The Shell", link: "en/linux/shell" }, ], - Usage: [{ text: "Gaming on Ultramarine", link: "en/usage/gaming" }], + Usage: [ + { text: "Gaming on Ultramarine", link: "en/usage/gaming" }, + { text: "Localization", link: "en/usage/l10n" }, + ], "Release Notes": [{ text: "Errata", link: "en/release/errata" }], // Chromebook: [ diff --git a/src/content/docs/en/installation/post-advanced.mdx b/src/content/docs/en/installation/post-advanced.mdx new file mode 100644 index 00000000..22f4f15f --- /dev/null +++ b/src/content/docs/en/installation/post-advanced.mdx @@ -0,0 +1,89 @@ +--- +title: Advanced Post-Installation Steps +description: Learn how to further configure your Ultramarine Linux installation. +--- + +import Alert from "../../../../components/Docs/Alert.astro"; + +## Use systemd-boot as the bootloader + +Ultramarine Linux currently still uses GRUB as the default bootloader for compatibility reasons. However, if you have a UEFI system, you can simply switch to +systemd-boot, which is a more modern bootloader. + + + This step is optional. You can skip this step if you don't want to use systemd-boot. + Make sure to back up your data and have a live USB ready in case something goes wrong. + Incorrectly configuring a new bootloader can make your OS unbootable. + + +1. Make sure you turn off Secure Boot in your UEFI settings for now, You can re-enable it later after [Setting up Secure Boot](#set-up-secure-boot) +2. Remove GRUB from protected packages: + ```bash + sudo rm /etc/dnf/protected.d/grub* + ``` +3. Start uninstalling GRUB: + ```bash + sudo dnf remove -y grubby grub2\* memtest86\* && sudo rm -rf /boot/grub2 && sudo rm -rf /boot/loader + ``` +4. Install unsigned systemd-boot binaries and the `sdubby` tool: + ```bash + sudo dnf install systemd-boot-unsigned sdubby + ``` +5. Install systemd-boot to the ESP: + ```bash + # Copy your current cmdline options just in case + cat /proc/cmdline | cut -d ' ' -f 2- | sudo tee /etc/kernel/cmdline + # Install systemd-boot + sudo bootctl install + # Now, reinstall and regenerate the current kernel entry + sudo kernel-install add $(uname -r) /lib/modules/$(uname -r)/vmlinuz + # Reinstall the kernel again, just in case we need to trigger some hooks + sudo dnf reinstall -y kernel-core + ``` +6. Reboot your system and make sure it boots correctly, run `sudo bootctl` to check if the boot process is correct. +7. (Optional) Proceed to [Set up Secure Boot](#set-up-secure-boot) if you want to re-enable Secure Boot. + + + +## Set up Secure Boot + +[Secure Boot] is a UEFI security protocol that secures the boot process by ensuring that +only signed executables are allowed to boot. While Ultramarine Linux's bootloader shim is signed by Microsoft and Red Hat, +you may want to use a different bootloader (i.e systemd-boot or rEFInd) or kernel. In that case, you will need to manually enroll +and sign the files with your own keys. + +Fortunately, there's a tool to automate this called [sbctl]. You can install it from the Terra repository: + + + `sbctl` is only available on Ultramarine/Fedora 40 and later. + + +```bash +sudo dnf install sbctl +``` + +After installing `sbctl`, you can use it to enroll, sign, and manage your Secure Boot keys. For example, to generate a new key and enroll it in your UEFI firmware: + +```bash +# Generate a new key +sudo sbctl create-keys +# Enroll the key +sudo sbctl enroll-keys +``` + +You can then use `sbctl sign` to sign your kernel, initramfs, and bootloader binaries. For example: + +```bash +# Sign the kernel +sudo sbctl sign /boot/vmlinuz-$(uname -r) +``` + +However, once you have installed sbctl, it should've already set up a hook to sign the kernel, initramfs and bootloader binaries automatically on kernel updates. + +After signing the necessary files and enrolling them in your firmware, you can re-enable Secure Boot in your UEFI settings. + + +[Secure Boot]: https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/oem-secure-boot +[sbctl]: https://github.com/Foxboron/sbctl + +#### [← Back To: Post-installation](/en/installation/postinstall) diff --git a/src/content/docs/en/installation/postinstall.mdx b/src/content/docs/en/installation/postinstall.mdx index 3dbe81ae..432c7292 100644 --- a/src/content/docs/en/installation/postinstall.mdx +++ b/src/content/docs/en/installation/postinstall.mdx @@ -42,7 +42,22 @@ Then reboot your system. ## Install Codecs -Ultramarine Linux includes codecs for most of the media you'll come across. You shouldn't need to install any additional codecs. +Ultramarine Linux includes codecs for most of the media you'll come across. **You shouldn't need to install any additional codecs.** Most of these packages below should be installed by default, excluding +the VLC and MPV media players, and the `libdvdcss` library. + +However, if you find yourself in the situation where you do not have those codecs, or require additional codecs other than we have provided (i.e obscure formats, or proprietary codecs not included in any repositories), you can look into the following packages: +- `x264` and `x265` for better H.264 and HEVC video support - Developed by the VideoLAN (VLC) project. +- [FFmpeg](https://ffmpeg.org/) (`ffmpeg`) - A cross-platform multimedia framework that can manipulate, convert and transcode to and from various media formats. +- [VLC Media Player](https://www.videolan.org/vlc/) (`vlc`) - A free and open-source media player that can play most multimedia files, can also be used to test out the codecs' functionality. +- [MPV](https://mpv.io/) (`mpv`) - A free and open-source media player that can also play most multimedia files. Can be used as a lightweight alternative to VLC. +- [libvpx](https://www.webmproject.org/) (`libvpx`) - A free and open-source codec for VP8 and VP9 video formats. +- [libdvdcss](https://www.videolan.org/developers/libdvdcss.html) (`libdvdcss`) - A library that can be used to read encrypted DVDs. This is not legal in some countries, so please check your local laws before using it. We also do not provide decryption keys for any encrypted DVDs. +- [Opus](https://opus-codec.org/) (`opus`) - A free and open-source audio codec that can be used for both speech and music. Should be installed by default. +- [OpenH264](https://www.openh264.org/) (`openh264`) - A free and open-source codec for H.264 video formats. Should be installed by default, required for WebRTC and partially Firefox. +- [aptX](https://www.aptx.com/) (`pipewire-codec-aptx`) - A proprietary codec for high-quality audio streaming over Bluetooth. Required for wireless Bluetooth audio devices that support it. +- `nv-codec-headers` - NVIDIA's codec headers for encoding and decoding video on NVIDIA GPUs. Required for hardware-accelerated video encoding and decoding on NVIDIA GPUs. May not be used by default assuming you do not have an NVIDIA GPU. +- [LAME](https://lame.sourceforge.io/) (`lame`) - A free and open-source MP3 encoder. Required for encoding MP3 files. +- `PackageKit-gstreamer-plugin` - PackageKit plugin that helps you install the above codec packages using GNOME Software/KDE Discover. ## Set up Backups @@ -53,4 +68,6 @@ Instructions are available on the [Pika Backup] and [Déjà Dup] websites. [Déjà Dup]: https://wiki.gnome.org/Apps/DejaDup [Pika Backup]: https://apps.gnome.org/PikaBackup/ +#### [Next Up: Advanced Post-installation steps →](/en/installation/post-advanced) + #### [← Back To: Installation](/en/installation/installation) diff --git a/src/content/docs/en/release/upgrade-to-ultramarine-40.mdx b/src/content/docs/en/release/upgrade-to-ultramarine-40.mdx new file mode 100644 index 00000000..0da11d0d --- /dev/null +++ b/src/content/docs/en/release/upgrade-to-ultramarine-40.mdx @@ -0,0 +1,36 @@ +--- +title: Upgrade to Ultramarine 40 +description: "A temporary notice for the 39 to 40 upgrade path." +--- + +This page is a temporary notice for upgrading Ultramarine 39 to 40. +For this release cycle, we've decided to release an upgrade path before the full distrbution release. +This should let existing users enjoy the new set of packages in 40 sooner. +A full blog post detailing changes will be published for the full distrbution release. + +## Flagship, GNOME, and KDE Editions + +You can use the editon's graphical app store to upgrade your system to 40. +On Flagship and GNOME, this will be GNOME Software, while on KDE, this will be Plasma Discover. + +You might need to update your system normally before the upgrade to 40 shows up in the app store. + +## Pantheon Edition + +The Pantheon upgrade path isn't ready yet. +While all of the required packages are in the UM and Terra repositories, the Pantheon desktop enviroment is broken for a variety of reasons. +We are currently working with upstream and other partners to resolve this, but it's possible that Pantheon may be skipped, deprecated, or defered until mid-cycle. +If you are interested in contributing to Ultramarine Pantheon, please join [our chats](en/community/community) and let us know! + +## Command line + +In case the above doesn't work, you can always upgrade through the command line, using `dnf system-upgrade`. + +Run the following and follow the prompts: + +```sh +sudo dnf upgrade --refresh +sudo dnf install dnf-plugin-system-upgrade +sudo dnf system-upgrade download --releasever=40 +sudo dnf system-upgrade reboot +``` diff --git a/src/content/docs/en/usage/l10n.mdx b/src/content/docs/en/usage/l10n.mdx new file mode 100644 index 00000000..5f881692 --- /dev/null +++ b/src/content/docs/en/usage/l10n.mdx @@ -0,0 +1,316 @@ +--- +title: Localization, Internationalization and Multilingualization +description: How to make your Linux system support other languages and even improve the support +--- + +import Alert from "../../../../components/Docs/Alert.astro"; + +Localization (l10n) and internationalization (i18n) support in Ultramarine Linux is crucial as +half of the project team speaks something other than English natively. This page contains details on +how i18n works and how it can be set up on Ultramarine. + +# Fonts + +Ultramarine should come with fonts for most if not all languages by default. Fonts for CJKV, Thai, +Indic languages are installed out of the box. If you find any glyphs supported by Unicode not +rendered correctly, [file a bug report]. + +## Font Priorities + +Chinese users might experience issues where Japanese fonts are preferred over Chinese ones simply +because the locale code `ja_JP` is before `zh_*` when sorted alphabetically. To solve this issue, +edit `~/.config/fontconfig/fonts.conf` (or `/etc/fonts/local.conf` for global changes): + +```xml + + + + + sans-serif + + Noto Sans CJK TW + Noto Sans + HanaMinA + + + + serif + + Noto Serif CJK TW + Noto Serif + HanaMinA + + + +``` + +# Inputting in another language + +You may change your key maps / keyboard layout in the settings applet. Refer to documentations for +your chosen Desktop Environment (DE) or Window Manager (WM) for more details. + +## IMFs, IMEs and IMs + +Special tools are required to type in CJKV (Chinese, Japanese, Korean and Vietnamese) and other +specific languages. + +**Input Method Frameworks (IMFs)** are software that enable users to type in numerous different input +methods. They provide a unified experience and user interface between IMEs and the DE/WM. + +**Input Method Editors (IMEs)** are software that convert user inputs into actual texts in different +languages. + +**Input Methods (IMs)** refer to the actual conversion between the input keys and the output text. IMs +are not actual software; there must be an IME that intercepts the inputted keys and map them into +output texts, where the mapping is specified by the IM. + +As an example, a Japanese KDE user would install `fcitx5-mozc` in order to type Japanese. In this +case, Fcitx5 is the IMF, Mozc is the IME, and the IM can be Romaji or Kana input depending on the +user's preference. + +A Cantonese GNOME user from Hong Kong learning Korean would install `ibus-rime` with Jyutping and +Cangjie support alongside `ibus-hangul` for Korean support. Here, IBus is the IMF, Rime IME provides +support for the Jyutping IM and Cangjie IM, while libhangul IME provides support for the Hangul IM. + +In most typical cases, only 1 IMF is installed in a system. However, multilingual users may choose +to install multiple IMEs so that they can type in multiple languages. + +## Fcitx5 vs IBus + +**IBus** (Intelligent Input Bus) is an IMF usually used in GTK-based desktop environments. If you +are using GNOME/Budgie, you most likely will choose IBus over Fcitx5 due to GNOME Desktop's tight +integration with IBus. Even though IBus's initial release was back in August 2008, releases are +still rather frequent and the project is still being maintained. + +**Fcitx5** is a newer IMF implementation and provides support for many different languages with a +slim core extensible with different addons and IMEs. It is the successor to Fcitx. If you are using +DEs that are not GTK-based (such as KDE Plasma which uses Qt) or any WMs, you should choose Fcitx5. + +There are no strict rules on which one to choose, you can install Fcitx5 even though you use GNOME, +and you can also install IBus on a KDE system. Things come down to personal preferences. + + + IBus will not work inside Window Managers. + + +## Setting up Fcitx5 on KDE + +1. Install your chosen IMEs (see the table below) alongside `kcm-fcitx5` and `fcitx5-configtool`. + + `kcm-fcitx5` is only available starting from Fedora 40. + + +- Install `fcitx5-qt` and `fcitx5-gtk` for Qt/GTK support. + +2. Enable Fcitx 5: + + - On Wayland (default), go to _Settings > Input Devices > Virtual Keyboard_, and select _Fcitx 5_. + - If Fcitx 5 does not work even after a reboot, try running `im-chooser` and select _Fcitx 5_. + - On X11, install `fcitx5-autostart`. + - If Fcitx 5 does not work even after a reboot, try setting the following in `/etc/environment`: + ``` + GTK_IM_MODULE=fcitx + QT_IM_MODULE=fcitx + ``` + +3. Head to _Settings > Regional Settings > Input Method_, then start configuring Fcitx 5. + +## Setting up Fcitx5 on other DEs/WMs + +1. Install your chosen IMEs (see the table below) alongside `fcitx5-configtool`, `fcitx5-autostart`. + - Install `fcitx5-qt` and `fcitx5-gtk` for Qt/GTK support. +2. Fcitx 5 should be enabled via the autostart package. If not, + + - try running `im-chooser` and select _Fcitx 5_. + - try setting the following in `/etc/environment`: + ``` + GTK_IM_MODULE=fcitx + QT_IM_MODULE=fcitx + ``` + +3. When Fcitx 5 is running, right click on the new "en" icon on the system tray > Settings. +4. Start configuring Fcitx5. + +## Setting up IBus + +1. Install your chosen IMEs (see the table below). +2. On GNOME, Budgie/Flagship and similar DEs, go into Settings > Keyboard. +3. On other DEs, run `ibus-setup`. +4. If IBus does not work correctly, + - try running `im-chooser` and select _IBus_. + - try setting the following in `/etc/environment`: + ``` + GTK_IM_MODULE=ibus + QT_IM_MODULE=ibus + ``` + +## List of IMEs and IMs + +Credits to Arch Wiki contributors for a [complete list of IMs]. The table is filtered and amended +such that it better represents Ultramarine's support on different IMs: + +``` + ┌─────────────────────┬─────────────────────┐ + ↓IM/IME IMF→ │ Fcitx5 │ IBus │ +┌──────────────┴─────────────────────┴─────────────────────┤ +│ CHINESE │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ Rime │ fcitx5-rime │ ibus-rime │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Pinyin │fcitx5-chinese-addons│ ibus-pinyin │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Zhuyin │ fcitx5-chewing │ ibus-chewing │ +│ Libzhuyin │ fcitx5-zhuyin │ ibus-libzhuyin │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Cangjie │ │ ibus-table-chinese- │ +│ Sucheng/Quick│ fcitx5-table-extra⁵ │ {cangjie,quick,scj} │ +│ SmartCangjie │ (and More…) │ /ibus-table-chinese │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Haifeng Wubi │ fcitx5-table-extra⁵ │ ibus-table-chinese- │ +│ Jidian Wubi │ (and More…) │wubi-{haifeng,jidian}│ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Others │ fcitx5-table-extra? │ ibus-table-chinese? │ +├──────────────┴─────────────────────┴─────────────────────┤ +│ JAPANESE │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ Mozc │ fcitx5-mozc │ ibus-mozc │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Anthy¹ │ fcitx5-anthy │ ibus-anthy │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ SKK² │ fcitx5-skk │ ibus-skk │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ KKC³ │ fcitx5-kkc │ ibus-kkc │ +├──────────────┴─────────────────────┴─────────────────────┤ +│ KOREAN │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ Libhangul │ fcitx5-hangul │ ibus-hangul │ +├──────────────┴─────────────────────┴─────────────────────┤ +│ VIETNAMESE │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ Unikey │ fcitx5-unikey │ ibus-unikey │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ ViQR │ fcitx5-m17n │ ibus-table-tv │ +├──────────────┴─────────────────────┴─────────────────────┤ +│ INDIC │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ m17n │ fcitx5-m17n │ ibus-m17n │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ OpenBangla │ fcitx5-openbangla │ ibus-openbangla │ +├──────────────┼─────────────────────┼─────────────────────┤ +│Sayura Sinhara│ fcitx5-sayura │ ibus-sayura │ +├──────────────┴─────────────────────┴─────────────────────┤ +│ OTHERS │ +├──────────────┬─────────────────────┬─────────────────────┤ +│ Thai │ fcitx5-libthai │ ibus-table-tv │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Math Symbols │ Compose Key⁴? │ibus-table-mathwriter│ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Completion │ *builtin* │ ibus-typing-booster │ +├──────────────┼─────────────────────┼─────────────────────┤ +│ Everything │ fcitx5-m17n │ ibus-m17n │ +└──────────────┴─────────────────────┴─────────────────────┘ +``` + +**Notes**: + +1. Anthy (the IM, not IME) is unmaintained, Mozc is usually preferred. +2. https://github.com/ueno/libskk +3. https://github.com/ueno/libkkc +4. See [#Compose Key](#compose-key). There is also LaTeX support in `fcitx5-m17n`. +5. See below for more IMs supported by `fcitx5-table-extra`. + +### List of IMs supported by `fcitx5-table-extra` + +- boshiamy +- cangjie-large +- cangjie3 +- cangjie5 +- cantonese +- cantonhk +- easy-large +- jyutping-table +- quick-classic +- quick3 +- quick5 +- scj6 +- stroke5 +- t9 +- wu +- wubi-large +- wubi98-large +- wubi98-pinyin +- wubi98-single +- wubi98 +- zhengma-large +- zhengma-pinyin +- zhengma + +### List of packages for `ibus-table*` + +- `ibus-table-code`: Ibus-Tables for Latex, CNS11643 & Emoticons +- `ibus-table-cyrillic`: Ibus-Tables for Cyrillic +- `ibus-table-extraphrase`: Extra phrase for ibus-table +- `ibus-table-latin`: Ibus-Tables for Latin +- `ibus-table-mathwriter`: Ibus-Tables for Unicode mathematics symbols +- `ibus-table-mongol`: Ibus-Tables for Mongol Script +- `ibus-table-others`: Various tables for IBus-Table +- `ibus-table-translit`: Ibus-Tables for Russian Translit +- `ibus-table-tv`: Ibus-Tables for Thai and Viqr (Vietnamese) +- `ibus-table-chinese`: Chinese input tables for IBus +- `ibus-table-chinese-array`: Array input methods +- `ibus-table-chinese-cangjie`: Cangjie based input methods +- `ibus-table-chinese-cantonese`: Cantonese input methods +- `ibus-table-chinese-cantonyale`: Cantonese input method based on yale romanization +- `ibus-table-chinese-easy`: Easy input method +- `ibus-table-chinese-erbi`: Erbi input method +- `ibus-table-chinese-quick`: Quick-to-learn input methods +- `ibus-table-chinese-scj`: Smart Cangjie +- `ibus-table-chinese-stroke5`: Stroke 5 input method +- `ibus-table-chinese-wu`: Wu pronunciation input method +- `ibus-table-chinese-wubi-haifeng`: Haifeng Wubi input method +- `ibus-table-chinese-wubi-jidian`: Jidian Wubi 86 input method, JiShuang 6.0 +- `ibus-table-chinese-yong`: YongMa input method + +### Rime + +[Rime](https://rime.im/) is an input method engine / IME for typing Chinese. It supports a wide +range of IMs and is highly customizable. + +You may refer to [ArchWiki](https://wiki.archlinux.org/title/Rime) regarding how Rime could be +configured. Note that Fedora/Ultramrine does not provide `rime-*` packages in our repositories. +You will need to use [plum](https://github.com/rime/plum) (aka. `rime-install`) to install schemas. +`rime-install` defaults to `ibus`; append `rime_frontend=fcitx-rime` to the front of the command if +you are using Fcitx5: + +``` +rime_frontend=fcitx-rime bash rime-install rime-aca/rime-cangjie6 +``` + +## Compose Key + +See [Compose Key on Wikipedia](https://en.wikipedia.org/wiki/Compose_key) and +[on ArchWiki](https://wiki.archlinux.org/title/Compose_key). + +# Translations + +Users that speak less popular languages might face issues where their system shows text in English +even though the language settings are configured properly. Do not report this issue to us. This is +due to lack of translation efforts from upstream (either the DE/WM or the app in concern). You may +help by visiting the translation platform provided by upstream and be a translator. Your +contributions would improve the entire Linux ecosystem experience for minorities. + +## Ultramarine Components + +If projects / software provided by Ultramarine (such as the Readymade installer) are untranslated +in your language, or you would like to improve the translations, please visit +[our Weblate translation platform](https://weblate.fyralabs.com/). + +There are cases where your language is not shown in the list of languages. This might be because no +one has made efforts on translating the software, or it is not supported by the i18n libraries used +by the software. For example, there is no Cantonese language option in Readymade because the i18n +library provided by GNOME Desktop does not support it. In this case, you should report this issue +to the upstream library. If you have a hard time determining where to report, you may join one of +our communities and reach out. + +[file a bug report]: https://github.com/Ultramarine-Linux/ultramarine/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D+Issue+Report +[complete list of IMs]: https://wiki.archlinux.org/title/Input_method#List_of_available_input_method_editors