From cb8be67631eaf8e74c2dbb8ac4bbe7bc47419bca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20COUDERC?= Date: Fri, 4 Nov 2016 23:37:28 +0000 Subject: [PATCH] Overhaul README.Debian --- debian/README.Debian | 323 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 264 insertions(+), 59 deletions(-) diff --git a/debian/README.Debian b/debian/README.Debian index 9286948..ff3e0d6 100644 --- a/debian/README.Debian +++ b/debian/README.Debian @@ -1,81 +1,101 @@ README for desktop-base ======================= -1. Images - 1.1. Emblems - 1.2. Pixmaps - 1.3. Wallpapers - 1.4. Boot splash -2. Desktop files -3. Changing desktop-base images -4. Window Managers -5. Boot splash +1. What’s provided + 1.1. Themes packs + 1.2. Debian logos + 1.3. Desktop files + 1.4. Default configurations overrides + 1.5. SDDM meta-theme + 1.6. Plymouth boot splashes +2. How to switch themes + 2.1. Global theme alternative + 2.2. Individual alternatives +3. Theme pack structure +4. Contributing + 4.1. Artists + 4.2. Desktop environment maintainers + 4.3. Notes and references -1. Images -1.1. Emblems -/usr/share/icons/hicolor/48x48/emblems/emblem-debian.png -/usr/share/icons/hicolor/48x48/emblems/emblem-debian.icon +1. What’s provided -1.2. Pixmaps +1.1. Theme packs + +Four theme packs are currently provided: +- Soft Waves (default for Stretch) +- Lines (default for Jessie) +- Joy (default for Wheezy) +- Spacefun (default for Squeeze) + +These themes contain customization for GRUB, Plymouth, login managers like +SDDM and LightDM, wallpapers and lock screen for desktop environments like +Gnome, KDE’s Plasma 5, XFCE, Mate… +See below for how to switch between themes and a detailed description of the +theme packs structure. + +1.2. Debian logos + +Several sizes of the Debian logo are shipped as: +/usr/share/icons/hicolor/${size}x${size}/emblems/emblem-debian.${ext} +/usr/share/icons/hicolor/${size}x${size}/emblems/emblem-debian.icon + +The sizes currently provided are 36, 64, 128 as PNG, and scalable for the SVG +version. Each has a side .icon descriptor file. + +A Debian security logo is also shipped in: /usr/share/pixmaps/debian-security.png -1.3. Grub, boot, login and wallpapers themes - -Wallpapers are provided in two svg variant, one standard aspect (4/3) and one -widescreen (16/9). You can switch from one another using the alternatives. -Using the same system you can select one of the older theme variant. Beware -that changing alternative means at the next package upgrade it won't be -automatically reverted to the default choice. - -For wallpaper you can run: - sudo update-alternatives --config desktop-background - -For login screen (only SDDM for now) you can run: - sudo update-alternatives --config desktop-login-background - -For grub, you can select standard or widescreen version too. Widescreen can be -better in particular for UEFI firmwares: - sudo update-alternatives --config desktop-grub - -2. Desktop files +1.3. Desktop files /usr/share/desktop-base/debian-homepage.desktop /usr/share/desktop-base/debian-reference.desktop /usr/share/desktop-base/debian-security.desktop -3. Changing desktop-base images +1.4. Default configurations overrides -We need professional looking Debian artwork in the -Desktop. If you want to help changing some desktop-base -images, that would be good consider the following notes: +desktop-base ships different files to override default theme configurations of +various parts of the system and prefer the active Debian theme. +See below « How to switch themes » for directions on how to configure these +overridden defaults. -- The swirl Debian logo is red; -- The Debian font is Poppl Laudation Condensed (unfortunately, - commercial font) -- Blue (#5F92C9 and some others) fits with GNOME default - clearlooks theme that we use in your default desktop - environment and looks good in KDE too; -- Black and White are welcome colors too. +- GRUB background: +/usr/share/desktop-base/grub_background.sh -If you've suggestions for a better artwork, create or edit -the images and open a 'wishlist' bug against desktop-base in our -Bug Tracking System (http://bugs.debian.org/). Please attach the -'svg' or 'xcf' and don't violate copyright. +This file is used by /etc/grub.d/05_debian_theme provided by grub-common to +correctly update the GRUB background with the Debian theme when running +update-grub. -4. Window Managers -desktop-base is used by GNOME/KDE/Xfce. +- Gnome desktop wallpaper and lock screen: +/usr/share/glib-2.0/schemas/10_desktop-base.gschema.override -If you're responsible for a WM in Debian and wants to use -desktop-base artwork or add your own image (wallpaper, splash, -whatever) use the layout described above and send your patch -through the Bug Tracking System to us. +- Plasma 5 desktop wallpaper: +/usr/share/plasma/shells/org.kde.plasma.desktop/contents/updates/desktop-base.js -5. Boot splash +Plasma ensures this JavaScript script is run for every user once and only once +for each Plasma version. It is run at user login time. See: +http://userbase.kde.org/KDE_System_Administration/PlasmaDesktopScripting -desktop-base ships several plymouth themes. To activate the default theme, +1.5. SDDM meta-theme + +desktop-base provides and SDDM theme called DebianTheme directly derived from +the default Plasma 5 theme Breeze. +This theme is mostly made of Breeze theme code but adjusts the background to +the currently selected desktop-login-background alternative (see below). + +Currently the package cannot set this theme as the default automatically so to +use it you’ll have to edit: + /etc/sddm.conf + +And add the following configuration section/directive: +[Theme] +Current=debian-theme + +1.6. Plymouth boot splashes + +desktop-base ships several Plymouth themes. To activate the default theme, install the plymouth and plymouth-themes packages and run: - plymouth-set-default-theme lines + plymouth-set-default-theme softwaves and update the initrd by running: update-initramfs -u @@ -85,5 +105,190 @@ To do that permamently, edit /etc/default/grub and add splash to the GRUB_CMDLINE_LINUX_DEFAULT variable. For example: GRUB_CMDLINE_LINUX_DEFAULT="quiet splash" -You may also keep the grub background and hide the kernel boot messages with: - GRUB_CMDLINE_LINUX_DEFAULT="quiet splash fbcon=vc:2" + +2. How to switch themes + +2.1. Global theme alternative + +The package provides a global alternative to switch themes all relevant +elements to a given theme. +This alternative is called « desktop-theme » and currently supports GRUB +background, login manager background (SDDM, LightDM), Desktops wallpapers +(Gnome, Plasma 5, XFCE, Mate…). + +You can change the theme pack selection with: + update-alternatives --config desktop-theme + +Following a theme switch you’ll also need to run the GRUB menu update command: + update-grub + +Plymouth theme switching is currently not supported. + +2.2. Individual alternatives + +In addition do the global theme alternative, desktop-base provides a series of +finer grained alternatives to override specific elements of the theme packs. + +Each alternative can be switch with: + update-alternative --config $alternative-name + +Selecting 0 will revert to the initial default of an alternative. + +- desktop-grub, alternative for: +/usr/share/images/desktop-base/desktop-grub.png + +This PNG file is used by the update-grub script to define the background for +the GRUB boot menu. +It defaults to the active theme selected via the desktop-theme alternative, +and on top of that: +- To the 16x9 / 1920x1080 version of the background for systems where EFI is + in use (grub-efi installed). +- To the 4x3 / 640x480 version otherwise. +It’s possible to override this default behaviour by selecting the other +ratio alternative pointing to /usr/share/desktop-base/active-theme/grub/* +while still keeping the GRUB background automatically switching via the global +desktop-theme alternative. + +- desktop-login-background, alternative for: +/usr/share/desktop-base/active-theme/login/background.svg + +This alternatives switches the login background for LightDM (default) and SDDM +when the SDDM theme DebianTheme is configured in sddm.conf. It defaults to the +login background of the active theme selected via the desktop-theme +alternative. + +- desktop-background, alternative for: +/usr/share/images/desktop-base/desktop-background + +This is a single SVG file used by desktop environments that don’t require a +more complex wallpaper setup (XFCE, MATE…). +It defaults to the 1920x1080 version of the active theme wallpaper selected +via the desktop-theme alternative. + +- desktop-background.xml, alternative for: +/usr/share/images/desktop-base/desktop-background.xml +- desktop-lockgreen.xml, alternative for: +/usr/share/images/desktop-base/desktop-lockscreen.xml + +These two XML files are used by Gnome to set the wallpaper and lock screen for +all users who didn’t otherwise chose a wallpaper or lock screen themselves. +It defaults to the wallpaper and lock screen for the active theme selected via +the desktop-theme alternative. + +- desktop-plasma5-wallpaper, alternative for: +/usr/share/wallpapers/DebianTheme + +This alternative folder is used by Plasma 5 in Debian to select the wallpaper +for all users who didn’t otherwise select a wallpaper themselves. It defaults +to the wallpaper of the active theme selected via the desktop-theme +alternative. + + +3. Theme pack structure + +A certain theme pack structure is expected in order to provide drop-in +replacements for the default Debian theme that can be selected with the +desktop-theme alternative. + +A theme pack should contain the following elements: + +./gnome-wp-list.xml +-> To make the wallpaper and lock screen selectable in Gnome preferences. + This file describes a list of XML files, one for each image packs provided. + Gnome uses these image packs to select the most appropriate version of a + wallpaper depending on the user’s screen resolution. + +./login/background.svg +./login/sddm-preview.jpg +-> To provide the login background alternative for LightDM, SDDM… + The SDDM-preview.jpg will make the theme recognizable from the Plasma 5 + preferences. + +./lockscreen/gnome-background.xml +./lockscreen/contents/images +./lockscreen/contents/images/2560x1440.svg +./lockscreen/contents/images/1280x720.svg +./lockscreen/contents/images/1920x1080.svg +… +./lockscreen/metadata.desktop +-> Lock screen background image pack. + The gnome-background.xml describes the available resolutions for the image, + for use by Gnome. + The metadata.desktop contains the description and license of the image pack + for use by Plasma 5. + The various files in the images folder are the provided resolutions and + ratio of the image. They can be either PNG or SVG, and should be name + according to their width and height as the example above so that Plasma 5 + can select the correct version. + There is no strict rule on which resolution and ratio should be provided + and a single version could suffice as long as it’s appearance is not broken + when cropped at different resolutions. + +./wallpaper/gnome-background.xml +./wallpaper/contents/images/2560x1440.svg +./wallpaper/contents/images/1280x720.svg +./wallpaper/contents/images/1920x1200.svg +./wallpaper/contents/images/1920x1080.svg +./wallpaper/contents/images/1280x800.svg +./wallpaper/contents/images/2560x1600.svg +… +./wallpaper/metadata.desktop +-> Wallpaper image pack, similar to the lock screen pack described above. + +./grub/Makefile +./grub/grub-4x3.svg +./grub/grub-16x9.svg +-> SVG and Makefile used to produce the GRUB background images. The Makefile + can be copy-pasted from and existing theme pack and should generate the + PNGs corresponding to each SVG in the GRUB folder. + + +4. Contributing + +4.1. Artists + +We need professional looking Debian artwork in the Desktop. If you want to +help improve themes in Debian or provide additional theme proposals, you +should monitor the Wiki page for artwork contests we run for each new Debian +release: +https://wiki.debian.org/DebianArt/Themes + +The debian-desktop mailing list (see below) is also a low-traffic source of +information about what’s going on with desktop themes in Debian. + +If you’ve suggestions for a better artwork, create or edit the images and open +a 'wishlist' bug against desktop-base in our Bug Tracking System +(http://bugs.debian.org/). Please attach the source file, preferably in SVG or +XCF format, and only propose work for which you’re the author. + +For us to be able to distribute your work in Debian, it will need to be under +a free and open source licenses which permits reuse and modifications as +required by the Debian Free Software Guidelines. + +See a more complete list of requirements here: +https://wiki.debian.org/DebianDesktop/Artwork/Requirements + +4.2. Desktop environment maintainers + +desktop-base is used by Gnome, KDE’s Plasma 5, XFCE, Mate… + +If you’re responsible for a desktop environment in Debian and want to use +desktop-base artwork, improve the support for your DE, or add additional +theming options use the layout described above and send your patch through the +Bug Tracking System, or ping us on debian-desktop@lists.debian.org. + +We’re glad to help with theme packaging and improving the consistency of +Debian themes over the desktop environments available in the archive. + +4.3. Notes and references + +If you’re interested in working on Debian theming, you may be interested in +the following references. + +- Information about the Debian Logo: +https://www.debian.org/logos/ +https://wiki.debian.org/DebianLogo + +- Archive and subscriptions to the debian-desktop mailing list: +https://lists.debian.org/debian-desktop/ +