Documentation

johnraff · 2023-04-24 06:32:59

This is a huge topic, and how much we can achieve in time for the Boron release is very much an unknown unknown. Linux developers are notoriously unfond of writing documentation, and software tends to get ahead of users' ability to make best use of it because they don't know what it can do

One big thing that could be very useful is to rewrite Damo's "Introduction to the Bunsenlabs Lithium Desktop" for Beryllium, and then for Boron.
(discussion about the Lithium guide)

If anyone felt like taking this on (would be really ultra appreciated) they could:
1) Check over the text. I think most of it applies equally to Beryllium as to Lithium, though a couple of utilities' names might have changed. You might possibly run into errors that need correcting.
2) Re-do the images for Beryllium. That's probably the most work.
3) Maybe you can see things that could usefully be added, or removed, or rearranged.
4) I don't think users have posting permissions in "Getting Started" but if you posted a Beryllium Desktop guide here in "Development & Suggestions" a mod can move it to "Getting Started".

---------
There are also a few small notes I'd like to put up somewhere, but I'm not sure of the best place.
ie:
note about the two commented-out menu items (dropbox and choose language)
---
note about the extra geany Build menu items
---
note about enabling steppers
---
note about enabling conky weather script
---
note about the bunsen calendar
---
How to tweak bl-* executables (copy to ~/bin)

Would a single "tweaks" post work? Or a "tweaks" topic with separate posts?
Or a help file shipped with the distro that appeared in the Help menu?

EDIT: There is now a dedicated "Post install settings and tweaks" thread, started by @rbh:
https://forums.bunsenlabs.org/viewtopic.php?id=7788
I'll add some things there, others please join in.

Last edited by johnraff (2024-01-25 06:05:31)

deleted0 · 2023-04-24 12:03:08

johnraff wrote:

This is a huge topic...
One big thing that could be very useful is to rewrite Damo's "Introduction to the Bunsenlabs Lithium Desktop" for Beryllium, and then for Boron.
(discussion)

How can one use the original thread as a template for a new one? For example, if I could 'edit' the original thread - would be easier than creating everything from scratch.

8bit

johnraff · 2023-04-25 02:44:40

^Does the "Quote" button work for you on that post? If so hit it and do a copy/paste of the contents into a post in this forum, maybe start a new topic. Remove the (quote=Damo) tag at the start and the (/quote) at the end and you'll have a new post to edit. (Had to change the square brackets to round here to keep the software happy.)

If there's no Quote button for you in the Getting Started section, I'll post a copy in this forum which you should be able to Quote OK so it'll become your post that you can edit.

deleted0 · 2023-04-25 03:02:41

^The thread is closed.

I'll need to host the images and when the thread is moved to it's home, you can upload them to BL's server and fix the links? Only about 6 images.

8bit

johnraff · 2023-04-25 04:01:30

eight.bit.al wrote:

^The thread is closed.

No Quote button?
I don't think you'll need to re-host the images. The links should work as they are.
EDIT What am I talking about?? Of course the Beryllium guide will need new images.
If you create new ones and host them on imgur or somewhere the links should work even after the post is moved. But it wouldn't hurt anyway to have copies on our own server from now on, in case the image host goes down - as happened with scrot.moe.

Last edited by johnraff (2023-04-25 04:19:35)

johnraff · 2023-04-25 04:15:07

Anyway, here's a copy of Damo's post, with the quote tags removed.

To get edit permissions you'll need to quote this post again and post it as your own.

---

The Bunsenlabs Lithium Desktop

Default Lithium background, Conky and Tint2 panel with Menu launcher and system tray

Window Manager Sessions

Bunsenlabs provides several options when logging in: A Bunsenlabs session, an Openbox session and a Default session (bunsenlabs-session).
https://imgur.com/pdHlLmpl.jpg
These are set from the Settings icon at the top right of the login screen, and will persist for the next login.

Bunsenlabs Session
This is the default:

BUNSENLABS(1)               General Commands Manual              BUNSENLABS(1)

NAME
       bunsenlabs-session — Starts a BunsenLabs session.

DESCRIPTION
       bunsenlabs-session  runs  a  BunsenLabs  session,  calling  openbox and
       starting the necessary auxiliary applications.  There is no  full  ses‐
       sion  manager,  so you will not be able to save your state from one log
       in to the next.  Although openbox is the default BunsenLabs window man‐
       ager,  users  can  select others while continuing to use the BunsenLabs
       menu, keyboard shortcuts and autostarted applications (see below).

       bunsenlabs-session does not take any command line arguments.

       On log in, bunsenlabs-session will run  the  ~/.config/bunsen/autostart
       script   if  it  exists,  and  will  copy  in  the  default  file  from
       /usr/share/bunsen/skel/.config/bunsen/autostart  otherwise.   You   may
       place anything you want to run automatically in this file, for example:

              xset -b off
              clipit &

       Make sure that each command that does not return quickly is followed by
       a "&" or else the script will stop there and further commands will  not
       be  executed. You can use the /usr/share/bunsen/skel/.config/bunsen/au‐
       tostart file as an example for creating your own.

       Window Manager: users can choose another window manager  than  the  de‐
       fault openbox by editing the line:

              window_manager=openbox

       near  the  top  of  ~/.config/bunsen/autostart. In such cases they will
       probably want to adjust the autostarted applications, likely with a new
       "case" clause for the new window manager. (See autostart for examples.)

Other useful information can be found in the Comments in ~/.config/bunsen/autostart

The menu is run with jgmenu, keybinds for commands are set by xbindkeys, and Openbox keybinds are set with bl-rc.xml.

Openbox Session
This is provided as a legacy for those users who wish to recreate their old Helium setup (specifically, so that users can have a separate Openbox setup). ~/.config/openbox/autostart is a template, and any autostart settings need to be added.

The menu is set with ~/.config/openbox/menu.xml, and keybinds with ~/.config/openbox/rc.xml.

For a guide on editing the Openbox menu and keybinds, please refer to Introduction to the Bunsenlabs Helium Desktop

if a particular user never logs in to bunsenlabs-session - even if it's installed - then they won't get the BL default user config files imported from /usr/share/bunsen/skel. Again, this is so a completely bunsen-free user can co-exist with a standard BL setup.

NB Many settings changes require Openbox to be reconfigured:
Menu -> Preferences -> Openbox -> Reconfigure, or use the command

openbox --reconfigure

________________________________________________________________________

Default BunsenLabs user configs

Package bunsen-configs, contains some default user configs, to give the user a functional and aesthetic desktop experience "out of the box".
The config-files are stored in /usr/share/bunsen/skel/* and are copied to users home on first login.

When user-configs is upgraded, the script bl-user-setup will popup a question if you want to import files into ~/.
If you have made significant changes to your config files, you can decline the popup's invitation and run 'bl-user-setup' in a terminal to make decisions for each file separately.
Or, you can allow all imports, open file ~/.cache/bunsen/bl-setup/log, to get the list of overwritten config files and use a diff program like meld to examine the differences and eventually copy back some settings.
Delete old backups to facilitate maintenance.

More info with command 'bl-user-setup --help'

________________________________________________________________________

Main Menu

(The following section assumes the default bunsenlabs-session is running.)

Lithium uses jgmenu as a replacement for the Openbox menu. It auto-updates, has a search facility, and is very configurable.
https://imgur.com/NbKlBkdl.jpg
There are 4 ways to Activate the menu:

by R-clicking on an empty area of the desktop
using the "Super key"
using "Super key + spacebar"
clicking on the Bunsenlabs icon on the left of the Tint2 panel

You are encouraged to explore the menu, especially the Help options - many questions can be resolved there. What isn't answered there, please search the forums, and if it is still unanswered, ask your question in an appropriate area on the forum.

Editing the Menu: Menu -> Preferences -> jgmenu gives access to help on configuration:

menu content is set with /.config/jgmenu/prepend.csv
menu settings are set with ~/.config/jgmenu/jgmenurc

Comprehensive help is provided by the commands man jgmenu and man jgmenututorial, also accessible from the menu.

Guide to jgmenu

Basic Introduction to jgmenu on BL Lithium

________________________________________________________________________

Screen settings

BunsenLabs has a Screen layout editor:

The command "arandr"
Menu -> Preferences -> Display -> ARandR Screen Layout Editor

ARandr is a visual front end for xrandr.
You can configure multiple monitors, set size, resolution and orientation.
If you want configured settings to load at start, you can save the settings as a script, to be loaded by autostart:

On menu "Layout", choose "Save As", save as screen.sh in the default folder: ~./screenlayout/.
Open file ~/.config/bunsen/autostart in your editor.
After text "### SETTINGS START", add:
$HOME/.screenlayout/screen.sh

________________________________________________________________________

Tint2 panel

Tint2 is a simple but highly configurable panel. BL default configuration includes a task list, a button to launch the jgmenu, a logout button, a clock and a system tray (systray or notification area) with an audio mixer, a clipboard, power manager and network-manager.
Hovering the mouse over Tint2 icons gives a "tooltip", with some status information. Left and right mouseclick can give additional alternatives.

The Tint2 -> Tint2 Manager sets default tint2 configfile in ~/.config/tint2/tint2-sessionfile.
Alternative Tint2 configs are shipped with Bunsenlabs, and you can add your own to ~/.config/tint2/.

Tint2 configuration: Menu -> Preferences -> Tint2 -> Edit Tint2sloads choosen tint2 configuration files in geany texteditor.

The program (command) tint2conf is a gui editor, although using a text editor to modify an existing tint2rc is not difficult (and often easier).

Clock - Tooltip gives weekday and date. Right mouse click, for setting alarms. Left mouse click gives mini calendar for a month

Default icons in Tint2 Systray
Mixer - Right click: Menu to settings, reload sound and launch the mixer. Left click: set the volume/mute and launch the mixer
Clipboard - Gives opportunity to reuse previous content from the clipboard.
Power Management - Right click: generell settings and "Presentation Mode" - temporarily disable power savings.
NetworkManager (nm-applet) - Right click: List of available and connected networks. Left click: temporarily disable network and notifications. Information about current connection and edit connections.

NOTE: Icons in the system tray are set by installed applications.

Menu -> Help & Resources -> Tint2 provides links to various sources of help.

________________________________________________________________________

Conky

A huge subject, with almost infinite possibilities. The Bunsenlabs forum is probably the best Conky resource on the web, where the experts hang out: Show us your Conky

The Conky can be changed with the Conky Chooser script: Menu -> Preferences -> Conky, and you can add your own to ~/.config/conky/
Multiple conkys can be run together and saved as a conky session, which is started at login.

Menu -> Help & Resources -> Conky provides links for configuration.

________________________________________________________________________

Desktop Background

Set with nitrogen, accessed with Menu -> Preferences -> Choose Wallpaper

________________________________________________________________________

Windows, Fonts and Icons

The window decorations and settings are set by Openbox, and the theme can be set with the Openbox Configuration Manager (obconf): Menu -> Preferences -> Openbox -> WM Preferences. This is also where you can change the number of Desktops ("workspaces"), which will be shown in the Tint2 panel.

GTK themes, fonts and icons can be set with lxappearance: Menu -> Preferences -> Appearance.

Changing the GTK font via lxappearance means it will also have to be adjusted in obconf, text editors etc, in order to have consistency. Changing the default fonts in ~/.config/fontconfig/fonts.conf is a way to keep everything in synch, by editing a single file: Menu -> Preferences -> Font Configuration.
There is a forum HowTo here: Setting monospace, serif & sans-serif default fonts

If the theme has been changed, then don't forget to synchronize jgmenu by running Menu -> jgmenu -> Sync Theme w. Openbox.

Editing or Installing themes: It is suggested that before editing any installed themes in /usr/share/themes/ they are first copied to ~/.local/share/themes/. This is where downloaded themes should also be placed, unless there are multiple users.

The same can be done for fonts (~/.local/share/fonts) and icons (~/.local/share/icons).
The font cache needs to be refreshed if a new font is installed, either on the commandline, or by logging in again.

sudo fc-cache -fr

Link to Theme sites: http://openbox.org/download-themes.php

________________________________________________________________________

Installing Software

Bunsenlabs has the gui Synaptic Package Manager: Menu -> System -> Synaptic Package Manager, but using apt, apt-get or aptitude on the commandline is worth learning.

Package details - source, versions etc - can be found with Menu -> Help & Resources -> Debian -> Package Search.

Heed the warnings on the website and in the bl-welcome script! Remember that you had to enter "I understand", to say you are aware of the risk of system breakage if you use non-Debian or non-Stable sources.

DontBreakDebian. You get to keep the pieces if you do!

________________________________________________________________________

Run applications

https://imgur.com/VpJL28ql.jpg

The Run box is gmrun, started with "Alt-F2".
Commands can be entered here, and like in the terminal you can use tab for auto-complete.

Configuration: Menu -> Preferences -> gmrun

The Alt Menu is dmenu, started with "Alt-F3".
The default dmenu opens along the top of the screen, and blocks other actions until you use "Enter" or "Esc".
Any executables in your $PATH will appear here. Start typing to show matching commands in the list, then highlight (Arrow keys) the command and use "Enter" to start it.

Configuration: Menu -> Preferences -> dmenu

Obviously, applications can also be started on the commandline, and this is a good way of looking for any error messages if you have problems.

gksudo is now deprecated by Debian, so to start gui applications with root privileges requires pkexec and policykit configuration, or some familiarity with the inner workings of permissions or root commands.

________________________________________________________________________

Autostart applications

Applications can be autostarted when added last to file ~/.config/bunsen/autostart
Add “&” after the command, so the application can be started in the background and the script continue to the end. Example:

thunar &
x-terminal-emulator &

Some programs, such as 'nm-applet' are run via XDG autostart, from .desktop files in /etc/xdg/autostart and ~/.config/autostart.

The command "bl-xdg-autostart --list", will list all autostarted programs and list where they are autostarted from.

________________________________________________________________________

Change theme

To change theme in BunsenLabs, and configure specific aspects, you must use two programs.

lxappearance: Menu -> Preferences -> Appearance

obconf: Menu -> Preferences -> Openbox -> WM Preferences
and choose the same theme in both programs.

As Openbox is not a desktop environment (DE), both programs are needed to alter different aspects of the desktop. See https://wiki.debian.org/Openbox, for info of the difference between a window manager and a desktop environment.

In Openbox, GTK programs look best. QT-programs can be run, but they will not always look so good. In the worst case, icons and/or menus may be indistinguishable. Changing the theme and/or specific elements like system font, icon-theme etc, should solve your problem.

________________________________________________________________________

BLOB Themes Manager

https://imgur.com/JAxXzNCl.jpg

The BunsenLabs OpenBox theme management script: Menu -> BL Utilities -> BLOB Themes Manager

Each saved collection of settings ("blob") is stored in ~/.config/blob/, and backups of important config files are also saved. A screenshot is stored with each blob, so you can remember what it looks like

When you have set up the looks of your desktop and windows how you like them, all the settings can be saved as a single collection for future restoration.

The following settings can be saved together, and restored individually or collectively:

Openbox theme
GTK theme
Icon theme
Wallpaper
Conky session
Tint2 panel
dmenu
lightdm login screen
Certain X files
Terminal configuration

Several BLOBs are shipped with Bunsenlabs, if you want to try out that retro look
________________________________________________________________________

Comments and suggestions can be posted HERE

Last edited by johnraff (2023-04-25 04:21:11)

deleted0 · 2023-04-27 01:09:50

This is a lot of work and I'd be interested in doing it for Boron; Beryllium can catch up some day.

8bit

johnraff · 2023-04-27 03:25:31

Boron would be great!
You won't be able to make desktop images for a while though.

deleted0 · 2023-04-27 12:07:26

I won't start 'till I have what's needed.
How soon for a alpha .iso?

8bit

edit1; Yeah, I said it.

edit2: setting up a dedicated computer; installing Be and upgrading to B.
In order to adequately write about it, I'll need to know it adequately.

Last edited by deleted0 (2023-04-27 13:57:22)

johnraff · 2023-04-28 02:57:09

I'm - maybe over-optimistically - hoping to build an early alpha in a couple of weeks.
The packages will just go in the way they are at that time. But a rough approximation of the desktop appearance - wallpaper, icons and themes - will be needed if it's to have meaning.

I'll be AFK for a bit from mid-May so it would be nice to get something out before then if possible.

#1 2023-04-24 06:32:59

Documentation

#2 2023-04-24 12:03:08

Re: Documentation

#3 2023-04-25 02:44:40

Re: Documentation

#4 2023-04-25 03:02:41

Re: Documentation

#5 2023-04-25 04:01:30

Re: Documentation

#6 2023-04-25 04:15:07

Re: Documentation

The Bunsenlabs Lithium Desktop

Default BunsenLabs user configs

Main Menu

Guide to jgmenu

Screen settings

Tint2 panel

Conky

Desktop Background

Windows, Fonts and Icons

Installing Software

Run applications

Autostart applications

Change theme

BLOB Themes Manager

#7 2023-04-27 01:09:50

Re: Documentation

#8 2023-04-27 03:25:31

Re: Documentation

#9 2023-04-27 12:07:26

Re: Documentation

#10 2023-04-28 02:57:09

Re: Documentation

Board footer