You are not logged in.

#1 2015-12-06 03:57:14

tknomanzr
BL Die Hard
From: Around the Bend
Registered: 2015-09-29
Posts: 1,029

Manual Page for bl-alternatives

I was able to find the time to build a man page for bl-alternatives based on the help text for the bl-alternatives command as well as johnraff's writeup located in /usr/share/bunsen/bunsendocs/helpfile-bl-alternatives.txt. A few things had to be moved around in order to conform to the man page format specification but it is essentially the same document.
First, the source code:

.TH bl-alternatives 1 "12 December 2015" "Part of bunsen-configs 8.6.2-1"
.SH NAME
.B bl-alternatives 
.R " - Bunsen Alternatives"

.SH SYNOPSIS
.PP
Usage: 
.BI "bl-alternatives" " <action>"
.PP 
Perform the given action to manage BunsenLabs alternatives.  Superuser permission is required to make changes.
.PP
.IR "help" " -- show help (also --help)"
.PP
.IR "install" " -- install BunsenLabs alternatives with default packages."
.PP
.IR "list" " -- list all assigned BunsenLabs alternatives."
.PP
.IR "remove" "-- remove all assigned BunsenLabs alternatives."
.PP
.IR "update" " -- update BunsenLabs alternatives with typical installed packages."

.SH DESCRIPTION
The "Bunsen Alternatives" are four groups added to the Debian Alternatives:
.PP
.I
bl-file-manager
.PP
.I
bl-text-editor
.PP
.I
bl-image-viewer
.PP
.I
bl-media-player
.PP
They can be used in menus, keyboard shortcuts, config files and scripts
just like any other command, and will call up whatever application has been
set as that alternative. Often the setting will be done automatically, but
even done manually it only needs to be done once to cover
all the calls to that command. (See "Editing Alternatives" below.)
.PP
The default settings in a new install of BunsenLabs are:
.PP
.IR "bl-file-manager" " -- Thunar"
.PP
.IR "bl-text-editor" " -- Geany or Leafpad"
.PP
.IR "bl-image-viewer" " -- Mirage"
.PP
.IR "bl-media-player" " -- VLC"
.PP
The only difference from the other Debian alternatives is that they are
not automatically added by packages themselves. For example, when xfce4-terminal is installed, it will add itself to the
available options for x-terminal-emulator. However, even though pcmanfm is
a possible alternative for bl-file-manager the pcmanfm package will not add
itself to that alternatives group. That job is done by the bl-alternatives
script which is called automatically by dpkg after each package install.
(It is very fast and does not significantly slow down the install.)
.PP
The applications which can be added by bl-alternatives are:
.PP
.IR "bl-file-manager:" " thunar pcmanfm spacefm nautilus caja xfe"
.PP
.IR "bl-text-editor:" " geany emacs gedit jedit kate leafpad mousepad scite medit"
.PP
.IR "bl-image-viewer:" " mirage eog eom viewnior"
.PP
.IR "bl-media-player:" " vlc banshee dragonplayer gnome-mplayer kaffeine parole smplayer totem gxine"
.PP
You can change these by editing 
.I /usr/bin/bl-alternatives
or add an app to an alternative group manually (see below).
.PP
.B
.SH Editing Alternatives 
.PP
You can edit any Debian Alternatives (including the bl-* BunsenLabs varieties)
with the command 
.IR "update-alternatives" " (see" 
.IR " man update-alternatives)" " but there is also a graphic front end called"
.IR " Galternatives" " which is easier to use in some ways."
.PP
In the BunsenLabs menu, click 
.B
System > Edit Debian Alternatives.
.PP
You can scroll down the list to see what alternative groups have been
installed on your system, what options are available for each group
and if there is more than one option you can set a different one.
.PP
You can also add a new application to an existing alternative group,
so if the bl-alternatives script has failed to add your favourite
image viewer to bl-image-viewer you can add it manually here.
.PP
It is not possible to remove a whole group with galternatives,
but you can remove an individual option from some group.
.PP
NOTE: These settings are system-wide, affecting all users.
If you want a local version of bl-file-manager set to eg spacefm,
while leaving the system setting unchanged, then put a symbolic link
called 'bl-file-manager' in ~/bin which points to /usr/bin/spacefm.
If ~/bin is in your $PATH and comes before /usr/bin then your symlink
will override the system bl-file-manager.
.SH BUGS
None known at this time.
.SH AUTHOR
.BI "johnraff --" " https://github.com/BunsenLabs/bunsen-configs/blob/master/bl-alternatives"
.SH SEE ALSO
.I update-alternatives(1)

Johnraff, you should really put your credits and also licensing stuff into your sources, even if it is just the wtfpl. If you wrote this script, then you do deserve some credit, even if its just a tag line in a bit of source code tongue. Essentially, I am making my best guess that you authored the script.
A peek into the source for /etc/manpath.config shows that debian enforces some rules for mapping manpaths and keeping them organized:

# set up PATH to MANPATH mapping
# ie. what man tree holds man pages for what binary directory.
#
#		*PATH*        ->	*MANPATH*
#
MANPATH_MAP	/bin			/usr/share/man
MANPATH_MAP	/usr/bin		/usr/share/man
MANPATH_MAP	/sbin			/usr/share/man
MANPATH_MAP	/usr/sbin		/usr/share/man
MANPATH_MAP	/usr/local/bin		/usr/local/man
MANPATH_MAP	/usr/local/bin		/usr/local/share/man
MANPATH_MAP	/usr/local/sbin		/usr/local/man
MANPATH_MAP	/usr/local/sbin		/usr/local/share/man
MANPATH_MAP	/usr/X11R6/bin		/usr/X11R6/man
MANPATH_MAP	/usr/bin/X11		/usr/X11R6/man
MANPATH_MAP	/usr/games		/usr/share/man
MANPATH_MAP	/opt/bin		/opt/man
MANPATH_MAP	/opt/sbin		/opt/man

So we can see that Debian would prefer it to go into /usr/share/man based on the script's location in /usr/bin.

In order to test the man page entry I created, copy the above source into a file named bl-alternatives.1 then:

sudo cp bl-alternatives.1 /usr/share/man/man1
sudo gzip bl-alternatives.1
man bl-alternatives

Critiques are welcome. Additionally, this man page source is posted to:
https://github.com/tknomanzr/docs
for the time being.

Last edited by tknomanzr (2015-12-06 03:57:47)

Offline

#2 2015-12-06 05:16:00

twoion
ほやほや
Registered: 2015-08-10
Posts: 2,600

Re: Manual Page for bl-alternatives

I applaud your effort, but the route to go would IMHO be just to write the man pages in markdown or restructured text and use pandoc to convert them into groff markup big_smile

bunsen-docs needs some work, agreed.


The show must go on.

Offline

#3 2015-12-06 05:34:52

tknomanzr
BL Die Hard
From: Around the Bend
Registered: 2015-09-29
Posts: 1,029

Re: Manual Page for bl-alternatives

Ok. Looking it over, that doesn't seem too difficult. Is the reason for this to make it more portable to other document formats?

Offline

#4 2015-12-06 05:43:40

twoion
ほやほや
Registered: 2015-08-10
Posts: 2,600

Re: Manual Page for bl-alternatives

Just easier to read and write; man page code can be easily translated into other markup formats like HTML by itself. It also has a couple of caveats ; quoting rules come to mind.

I just tried out pandoc on this:

% bl-alernatives(7) User Manual
% John Raff <john@bunsenlabs.org>, Jens John <dev@2ion.de>
% Version 8.0

# NAME

bl-alternatives - update-alternatives(8) configuration for BunsenLabs

# DESCRIPTION

The "Bunsen Alternatives" are four groups added to the Debian
alternatives system:

    bl-file-manager
    bl-text-editor
    bl-image-viewer
    bl-media-player

They can be used in menus, keyboard shortcuts, config files and scripts
just like any other command, and will call up whatever application has
been set as that alternative. Often the setting will be done
automatically, but even done manually it only needs to be done once to
cover all the calls to that command. (See *EDITING ALTERNATIVES* below.)

The default settings in a new install of BunsenLabs are:

`bl-file-manager`
:   Thunar

`bl-text-editor`
:   Geany or Leafpad

`bl-image-viewer`
:   Mirage

`bl-media-player`
:   VLC

The only difference from the other Debian alternatives is that they are
not automatically added by packages themselves.  For example, when
xfce4-terminal is installed, it will add itself to the available options
for x-terminal-emulator. However, even though pcmanfm is a possible
alternative for bl-file-manager the pcmanfm package will not add
itself to that alternatives group. That job is done by the
bl-alternatives script which is called automatically by dpkg after
each package install.  (It is very fast and does not significantly
slow down the install.)

The applications which can be added by bl-alternatives are:

`bl-file-manager`
:   thunar pcmanfm spacefm nautilus

`bl-text-editor`
:   geany emacs gedit jedit kate leafpad mousepad scite

`bl-image-viewer`
:   mirage eog eom viewnior

`bl-media-player`
:   vlc banshee dragonplayer gnome-mplayer kaffeine parole smplayer totem

You can change these by editing */usr/bin/bl-alternatives*, or add an
app to an alternative group manually (see below).

# EDITING ALTERNATIVES

You can edit any Debian Alternatives (including the **bl-\*** BunsenLabs
varieties) with the command **update-alternatives**(8) but there is also a
graphic front end called `Galternatives` which is easier to use in some
ways.

In the BunsenLabs menu, click *"System" > "Edit Debian Alternatives"*.
You can scroll down the list to see what alternative groups have been
installed on your system, what options are available for each group and
if there is more than one option you can set a different one.

You can also add a new application to an existing alternative group, so
if the **bl-alternatives** script has failed to add your favourite image
viewer to **bl-image-viewer** you can add it manually here.

It is not possible to remove a whole group with galternatives, but you
can remove an individual option from some group.

These settings are system-wide, affecting all users.  

## PER-USER CHANGES

If you want a local version of bl-file-manager set to eg spacefm, while
leaving the system setting unchanged, then put a symbolic link called
**bl-file-manager** in *~/bin* which points to */usr/bin/spacefm*.  If
*~/bin* is in your `$PATH` and comes before */usr/bin* then your symlink
will override the system **bl-file-manager**.

# SEE ALSO

**update-alternatives**(8)

Arguably the intransparent handling of man page formatting instructions is not really attractive (for example, it is unclear how to achieve certain layouts in markdown); I need to try out if .rst looks better.


The show must go on.

Offline

#5 2015-12-06 05:53:06

tknomanzr
BL Die Hard
From: Around the Bend
Registered: 2015-09-29
Posts: 1,029

Re: Manual Page for bl-alternatives

That does look a lot better. It appears that I need to re-read the section of man man pertaining to how its sections are structured, however. I seem to have had stuff in the wrong section.

Offline

#6 2015-12-06 10:45:28

twoion
ほやほや
Registered: 2015-08-10
Posts: 2,600

Re: Manual Page for bl-alternatives

I am now working on this; you may track the progress or contribute at https://github.com/BunsenLabs/bunsen-docs/tree/manpages or discuss here.


The show must go on.

Offline

#7 2015-12-08 03:35:17

johnraff
nullglob
From: Nagoya, Japan
Registered: 2015-09-09
Posts: 6,299
Website

Re: Manual Page for bl-alternatives

Re authorship.
I started the bl-alternatives discussion and was deeply involved in its development, and I also wrote that bit of documentation helpfile-bl-alternatives.txt, BUT the bl-alternatives script itself was written for us by cpoakes, a CrunchBang forum member. (I don't think he's visited us here yet.)

In BL packages I've tried to credit all the people involved in the debian/copyright files, but there is no linking of specific people to specific files, except for the very general /* vs /debian/* distinction.

All BL packages are licensed GPL3 already.

Should attribution/license headers be added to each individual file?


...elevator in the Brain Hotel, broken down but just as well...
( a boring Japan blog (currently paused), idle Twitterings and GitStuff )

Introduction to the Bunsenlabs Lithium Desktop

Offline

Board footer

Powered by FluxBB