Path names need to be documented

[bsalem]

The man page and other documentation with this tool is so poor I am considering uninstalling the software even though I like what it does.

The Preferences page does not report the path to the favorites and other folders. I should.

The manaual page should report the default paths to the folders uses for the images, the downloaded and favorites dirs.

Not putting this information in the files shipped with the application and deferring the information to a manual that might not be included in the package is the wrong way to document software. At least the man page needs to be updated with defaults.

[Peter Levi (peterlevi)]

"The Preferences page does not report the path to the favorites and other folders. I should." - clicking the buttons opens the folder selector where you see the full path, the tooltips of the buttons also show the full path. Showing the full paths all the time in the dialog is an overkill, as you only set these once, afterwards the paths become visual pollution.

Regarding man pages, Variety installs to /opt/extras.ubuntu.com/variety/, does not put files elsewhere (apart from creating user data in ~/.config/variety) and I'm not sure there's a way to provide a man page with such a setup. So, I agree with you having a man page would be good, but I can't provide one with the current deployment setup.

[bsalem (bruce-euphon)]

Then, maybe the path needs to be reported in the preferences GUI. I just
couldn't remember ~/.config/Variety, that was all. The Preferences GUI
seems too vague.

On Wed, Mar 12, 2014 at 6:00 AM, Peter Levi <email address hidden>wrote:

> "The Preferences page does not report the path to the favorites and
> other folders. I should." - clicking the buttons opens the folder
> selector where you see the full path, the tooltips of the buttons also
> show the full path. Showing the full paths all the time in the dialog is
> an overkill, as you only set these once, afterwards the paths become
> visual pollution.
>
> Regarding man pages, Variety installs to
> /opt/extras.ubuntu.com/variety/, does not put files elsewhere (apart
> from creating user data in ~/.config/variety) and I'm not sure there's a
> way to provide a man page with such a setup. So, I agree with you having
> a man page would be good, but I can't provide one with the current
> deployment setup.
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1268053
>
> Title:
> Path names need to be documented
>
> Status in Variety wallpaper changer:
> New
>
> Bug description:
> The man page and other documentation with this tool is so poor I am
> considering uninstalling the software even though I like what it does.
>
> The Preferences page does not report the path to the favorites and
> other folders. I should.
>
> The manaual page should report the default paths to the folders uses
> for the images, the downloaded and favorites dirs.
>
> Not putting this information in the files shipped with the application
> and deferring the information to a manual that might not be included
> in the package is the wrong way to document software. At least the man
> page needs to be updated with defaults.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/variety/+bug/1268053/+subscriptions
>

[Peter Levi (peterlevi)]

I'm not sure I understand your new suggestion - it seems the same as the previous one. By "Preferences page" and "Preferences GUI" do you mean different things?

My last argument was that Variety's preferences GUI does show the full paths in tooltips and also if you click the buttons (thus opening the folder selector) and I don't want to write the full path directly in the GUI, as it becomes visual clutter. Also, selecting individual folders in the Images list (e.g. Favorites, Fetched) gives you the option to open the folder directly, so that is a third way to get to it.

Keep in mind that a big part of the users won't ever need to know the paths to the folders and a path like "~/.config/variety" will actually look scary to them if placed on a prominent place on the most central part of Variety's GUI.

[bsalem (bruce-euphon)]

First, when a directory you maintain grows to a couple of GB on MY $HOME I
need the ability to find the relative path to the dir so I can mv the files
there to some other backup. If I bother to save wall papers to Favorites,
it isn't enough just to show me a tab and it doesn't make sense that your
preferences doesn't show the full path to Favorites, even if the argument
is that doing so would intimidate novices, it should still be available in
some way.

Second, If your design is trying to be "simple" then maybe it shouldn't be
part of Ubuntu as eventually users should know the hierarchy of the file
system even to the point that they should have to find out about hidden
files and dirs. At least getting the info should be optional and not hidden
behind a tab as is is in the Preferences. And, yes, that was my original
complaint. It would be simple to put somewhere on the Preferences that "The
path to the files Variety users is ~/.config/Variety", that is all I
needed. I can do all of the rest. Maybe a tab "Path to files" is all that
is needed ir something in the man page $PATHTOVARIETY with the settable
environment variable and an option to display that environment variable,
and this is but standard UNIX convention. So there are lots of choices here.

On Wed, Mar 12, 2014 at 9:13 AM, Peter Levi <email address hidden>wrote:

> I'm not sure I understand your new suggestion - it seems the same as the
> previous one. By "Preferences page" and "Preferences GUI" do you mean
> different things?
>
> My last argument was that Variety's preferences GUI does show the full
> paths in tooltips and also if you click the buttons (thus opening the
> folder selector) and I don't want to write the full path directly in the
> GUI, as it becomes visual clutter. Also, selecting individual folders in
> the Images list (e.g. Favorites, Fetched) gives you the option to open
> the folder directly, so that is a third way to get to it.
>
> Keep in mind that a big part of the users won't ever need to know the
> paths to the folders and a path like "~/.config/variety" will actually
> look scary to them if placed on a prominent place on the most central
> part of Variety's GUI.
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1268053
>
> Title:
> Path names need to be documented
>
> Status in Variety wallpaper changer:
> New
>
> Bug description:
> The man page and other documentation with this tool is so poor I am
> considering uninstalling the software even though I like what it does.
>
> The Preferences page does not report the path to the favorites and
> other folders. I should.
>
> The manaual page should report the default paths to the folders uses
> for the images, the downloaded and favorites dirs.
>
> Not putting this information in the files shipped with the application
> and deferring the information to a manual that might not be included
> in the package is the wrong way to document software. At least the man
> page needs to be updated with defaults.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/variety/+bug/1268053/+subscri...

[Peter Levi (peterlevi)]

Please see comments below.

On Wed, Mar 12, 2014 at 8:56 PM, bsalem <email address hidden> wrote:

> First, when a directory you maintain grows to a couple of GB on MY $HOME I
> need the ability to find the relative path to the dir so I can mv the files
> there to some other backup. If I bother to save wall papers to Favorites,
> it isn't enough just to show me a tab and it doesn't make sense that your
> preferences doesn't show the full path to Favorites, even if the argument
> is that doing so would intimidate novices, it should still be available in
> some way.
>
Well, it is available - I gave you three different ways you can find out
the path to these folders. The first one - clicking the button - is
absolutely intuitive. Hanging around with the mouse till you get the
tooltip is also fairly standard and obvious. And what can we say about
selecting "The Favorites folder" in the sources list and clicking the
button labeled "Open folder"...
Play it in your mind - you have this button labeled "Favorites" and you
think - "Hm, I wonder what's the full path to this folder..." - it seems
your behaviour here is to open the man page and look there. I'd bet 99% of
Ubuntu's users would NOT do this, they would rather click the button in
such a situation.

I agree that it would be more obvious if the button was labeled with the
full path, not the name of the folder, but I played with this when I worked
on this part and those cryptic paths there shown all the time do look bad
and distracting - not worth for something that is set once and left alone.

Perhaps the real problem here is that Variety is using folders within the
hidden ~/.config by default, instead of, say, ~/Images/, but Variety arose
as an entry in a software competition which mandated to keep all
application files within /opt/extras.ubuntu.com/appname, and all data
within ~/.config/appname, so no choice here. This is also the policy of the
Ubuntu Software Center.

>
> Second, If your design is trying to be "simple" then maybe it shouldn't be
> part of Ubuntu as eventually users should know the hierarchy of the file
> system even to the point that they should have to find out about hidden
> files and dirs.

Not sure I understand the logic behind "it shouldn't be part of Ubuntu".
First, Variety is not part of Ubuntu, it is simply an application for
Ubuntu and other Linux distributions. Second, one of Ubuntu's main goals IS
to be friendly to novices and part of this is providing working intuitive
solutions which don't require users to know about hidden folders or the
established folder structure. Actually the OS is irrelevant here - I think
any software targeted at the general public should be friendly to novices,
yet allow tinkering from more advanced users and it should NOT require
anybody to read any sort of documentation to get the basics working.

> At least getting the info should be optional and not hidden
> behind a tab as is is in the Preferences. And, yes, that was my original
> complaint. It would be simple to put somewhere on the Preferences that "The
> path to the files Variety users is ~/.config/Variety", that is all I
> needed. I can do all of the rest. Maybe a tab "Path t...

[bsalem (bruce-euphon)]

OK, fine, if the default path is put somewhere, anywhere then do so. If you
don't want it to clutter up the Preferences window, might I suggest that it
be documented in the man page? That might be a good solution here, since if
you don't want to distract novice users, you should not prevent power
users, for example system administrators, from getting it.

I would recommend that the default path should be settable either as a
command line argument or as an environment variable, if not in the
preferences, and the value of this has nothing to do with the idea of
hiding info from novices, which I think is ultimately a bad practice. It
has to do with configuring a system that has to take care of more than one
user. I worked at one time on UNIX systems that supported hundreds of
users, and although Ubuntu might not routinely do that, it could. In that
case a system administrator might well have to configure the location of
the wallpaper files to be other than the default or even on a disk other
than the boot disk. Even if you don't want to expose an environment
variable in the preferences window, there is nothing to stop you from
having it is the configuration file that can be edited by hand by a power
user. So if you don't want joe user editing it, a system administrator or a
power user might want to. Give them the means.

On my system I have a smallish root partition, about 70 GB and my home dir
is about half that size. The reason is not that I am too lazy to move files
out of there but that most of that is in hidden dirs as config and cache
files. Web browsers are particularly gluttonous about caching to disk but
your program is one of the offenders too. It would be nice to be able to
configure your program to put some of its stuff on a different device than
the home dir on the boot disk or root disk. I am not saying that what your
program saves is bad, only that I'd like the ability to know where it is
and to decide where to put it. I think that I can have that and you can
keep your preferences interface as simple as it is now.

I think that the power of *nix systems is that we can have as much
complexity as we need. You can hide it from novices, if you wish, but if
you have power users, system administrators, you must them the means.
Really, all this takes if for you to write a .configure file in several
places in the filesystem. /etc/variety/.configure for the system and
~/.variety for the user, and that is standard UNIX practice.

I think the idea that you should avoid that convention is bad practice and
regardless of how such matters are handled by Microsoft Windows or some
idea at Canonnical. The practice in Windows was to hide details and control
from the uses until quite recently, even as their OS was available to third
parties and hackers all the while, that hardly enabled their users. It
bothers me to hear the same philosophy voiced by Linux developers. There
was always good reason to expose complexity to users on UNIX and yet it is
easy to not to. It is only a question of design.

Keep your preferences window as simple as it is, but allow for manual
config and put the info in the man page or online-help. I prefer that man
pages not be...

[Peter Levi (peterlevi)]

"It would be nice to be able to configure your program to put some of its stuff on a different device than the home dir on the boot disk or root disk." - The app allows you to configure where to put all the space-consuming files - you can configure via the GUI or the configuration file the paths to Favorites, Downloaded and Fetched files. Variety is in no way forcing you to leave them in your home. The remaining configuration and cache files that you currently can't move out to a custom location are less than 50 kb total.

Changeable path to config folder - I agree on this point - the path to the configuration files is currently hardcoded to ~/.config/variety, not settable, and I have myself long ago reported a bug that this should be settable via a command-line parameter, but it is lower priority than most other things, and I probably won't get to it too soon: https://bugs.launchpad.net/variety/+bug/1067663

Hiding _unnecessary_ complexity from users is essential if you want to provide a usable-by-most application. Canonical, Microsoft or UNIX have nothing to do here - this is a universal principle. HOWEVER this is NOT the same as ripping advanced users of the control they can have. You can be both novice and geek-friendly. Variety is actually extremely hackable for a number of reasons - command-line controlling of a running instance, configuration in editable plain text files, user-editable bash scripts for changing the wallpaper, etc, etc. But exposing the user directly to every possible option or piece of information, even those options which 99% of the users will never need, is not good design in my view. Things need to be prioritized.

[bsalem (bruce-euphon)]

Unless I misread the Preferences, it does not make clear that it can use a
different absolute path than the default. The space usage under
~/.config/variety on my system had grown to 2.5 GB because of what I saved
to Favorites, lots of the beautiful images from Astronomy Picture of the
Day. Even if paths are configurable, that fact is not properly documented
either in Preferences or in the man page. I understand that you have to set
priorities. If there are features in the source code that allow for
config'ing of the paths to dits, THAT must be documented. Or If save lots
to Favorites, it might be desirable to point the link in the Preferences to
different copies of that dir, or to point it at a dir on a different device
than the book disk,

On Fri, Mar 14, 2014 at 2:04 AM, Peter Levi <email address hidden>wrote:

> "It would be nice to be able to configure your program to put some of
> its stuff on a different device than the home dir on the boot disk or
> root disk." - The app allows you to configure where to put all the
> space-consuming files - you can configure via the GUI or the
> configuration file the paths to Favorites, Downloaded and Fetched files.
> Variety is in no way forcing you to leave them in your home. The
> remaining configuration and cache files that you currently can't move
> out to a custom location are less than 50 kb total.
>
> Changeable path to config folder - I agree on this point - the path to
> the configuration files is currently hardcoded to ~/.config/variety, not
> settable, and I have myself long ago reported a bug that this should be
> settable via a command-line parameter, but it is lower priority than
> most other things, and I probably won't get to it too soon:
> https://bugs.launchpad.net/variety/+bug/1067663
>
> Hiding _unnecessary_ complexity from users is essential if you want to
> provide a usable-by-most application. Canonical, Microsoft or UNIX have
> nothing to do here - this is a universal principle. HOWEVER this is NOT
> the same as ripping advanced users of the control they can have. You can
> be both novice and geek-friendly. Variety is actually extremely hackable
> for a number of reasons - command-line controlling of a running
> instance, configuration in editable plain text files, user-editable bash
> scripts for changing the wallpaper, etc, etc. But exposing the user
> directly to every possible option or piece of information, even those
> options which 99% of the users will never need, is not good design in my
> view. Things need to be prioritized.
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1268053
>
> Title:
> Path names need to be documented
>
> Status in Variety wallpaper changer:
> New
>
> Bug description:
> The man page and other documentation with this tool is so poor I am
> considering uninstalling the software even though I like what it does.
>
> The Preferences page does not report the path to the favorites and
> other folders. I should.
>
> The manaual page should report the default paths to the folders uses
> for the images, the downloaded and favorites dirs.
>
> Not putt...

[Peter Levi (peterlevi)]

You definitely misread the Preferences... At the bottom of the main tab (the one you see first when opening Preferences) there is the "Favorites" section which contains "Copy favorite wallpapers to [BIG FOLDER BROWSING BUTTON]". Nothing here needs any more documenting, the UI is self-descriptive. Same goes for the other folders - you can change them all directly from the GUI, just spend some time to check the whole GUI and read the labels there before reporting a bug.

[bsalem (bruce-euphon)]

I see what you are talking about, and maybe I should rethink things a bit,
since I could have just created a dir on one of my secondary devices in the
first place and set it as the place to put the things that by default go
into ~/.config/Favorites. You are right, the hook is there. We can close
the question, maybe I do that, yes.

However the question began that I had difficulty finding the full path to
Favorites as it is configured by default and asked for that to be better
documented either in the web page or the preferences window. You may now be
doing that and I hope that the info is more readily available as a result
of my question.

The issue was that I saw growth of my home dir on a smallish filesystem and
was able to see that it was partly due to the Favorites folder. Once I knew
its path it was trivial for me to move the contents to a secondary place,
that was never an issue. Having the path to Favorites was the issue and
hopefully you have resolved it in some way. You are right that I could have
redirected Favorites at any time. So, thank you for taking the time to talk
to me.

On Sun, Mar 16, 2014 at 2:00 PM, Peter Levi <email address hidden>wrote:

> You definitely misread the Preferences... At the bottom of the main tab
> (the one you see first when opening Preferences) there is the
> "Favorites" section which contains "Copy favorite wallpapers to [BIG
> FOLDER BROWSING BUTTON]". Nothing here needs any more documenting, the
> UI is self-descriptive. Same goes for the other folders - you can change
> them all directly from the GUI, just spend some time to check the whole
> GUI and read the labels there before reporting a bug.
>
> ** Changed in: variety
> Status: New => Invalid
>
> --
> You received this bug notification because you are subscribed to the bug
> report.
> https://bugs.launchpad.net/bugs/1268053
>
> Title:
> Path names need to be documented
>
> Status in Variety wallpaper changer:
> Invalid
>
> Bug description:
> The man page and other documentation with this tool is so poor I am
> considering uninstalling the software even though I like what it does.
>
> The Preferences page does not report the path to the favorites and
> other folders. I should.
>
> The manaual page should report the default paths to the folders uses
> for the images, the downloaded and favorites dirs.
>
> Not putting this information in the files shipped with the application
> and deferring the information to a manual that might not be included
> in the package is the wrong way to document software. At least the man
> page needs to be updated with defaults.
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/variety/+bug/1268053/+subscriptions
>

[Peter Levi (peterlevi)]

Version 0.4.18 displays the full path to the folders inside the browse buttons, not just the folder name.