By default, Bugzilla does not search the list of RESOLVED bugs.
You can force it to do so by putting the upper-case word ALL in front of your search query, e.g.: ALL tdelibs
We recommend searching for bugs this way, as you may discover that your bug has already been resolved and fixed in a later release.

Bug 1826

Summary: [Help Handbooks] Applets don't populate in help handbook
Product: TDE Reporter: Darrell <darrella>
Component: other (any)Assignee: Timothy Pearson <kb9vqf>
Status: NEW ---    
Severity: normal CC: bugwatch, darrella, michele.calgaro
Priority: P5    
Version: R14.0.x [Trinity]   
Hardware: Other   
OS: Linux   
Compiler Version: TDE Version String:
Application Version: Application Name:

Description Darrell 2014-01-15 20:30:23 CST 
In the help handbook some of my user accounts have access to applet manuals, other accounts do not.

I discovered that user accounts with the following directory in their user profiles are unable to see the applet manuals:

$TDEHOME/apps/kicker/applets

Experimenting indicates the behavior of the help handbook table of contents depends upon how those directories are populated.

The user's $TDEHOME directory structure mimics the Trinity system directory structure. When the user's applets directory does not exist then there is nothing to override the system directory. All applet handbooks appear in the table of contents. When the user has an applet directory, then that directory overrides the system directory.

When I populate the user's applet directory with *.desktop files from the system directory, then those items appear in the handbook table of contents, but only those *.desktop files I copy. When the user's applet directory is empty, then none appear in the handbook table of contents.

A possible solution:

Regardless of how the user's $TDEHOME/apps/kicker/applets is populated, or empty, the help handbook should not be affected. The help handbook should list all applets handbooks available in the system directory _and_ any different applets in the user's $TDEHOME/apps/kicker/applets directory.
Comment 1 Michele Calgaro 2014-01-16 01:47:15 CST 
As a side note, only 6 applet handbooks appears.
What about all the other applet handbooks?
Comment 2 Darrell 2014-01-16 16:14:46 CST 
>What about all the other applet handbooks?
None exist.
Comment 3 Michele Calgaro 2014-01-17 09:09:27 CST 
(In reply to comment #2)
> >What about all the other applet handbooks?
> None exist.

Then would be good to write something :) 
http://trinity.etherpad.trinitydesktop.org/43 lists all docbooks (available and missing/not existing)
Comment 4 Darrell 2014-02-08 16:04:06 CST 
Part of the problem is resolved with a work-around as described in the original comment but is not resolved globally in the source code.

The problem is resolved for applets that compile with a respective handbook. I now find 10 links under the Applet Manuals heading.

For the remaining applets:

1. Write a handbook.
2. Ensure the respective *.desktop file has a correct DocPath key.

We can (and should) write "We Apologize" template handbooks for the remaining applets. I did that for klcddimmer, which used an original docbook template, which contained a bunch of snarky commments by somebody who thought he or she was being cute, which looked horribly unprofessional, which nonetheless a few developers used as their bonafide handbook.

Currently I find 35 applets (*.desktop files) installed in /opt/trinity/share/apps/kicker/applets. That means 25 applets have no handbook and have no DocPath defined. If there was a DocPath defined, the applet would appear in the handbook table of contents but would result in a "Help Documentation Not Found" page. Ignoring compile times to verify correct results, adding a "We Apologize" page takes about five minutes for any app. Basic grunt work. Adding that page is only one step removed from the "Help Documentation Not Found" page, but at least indicates to users we are aware of the shortcoming rather than creating the appearance that we forgot documentation altogether.

Not adding a DocPath key in the desktop files keeps all respective applets (and apps) from appearing in the handbook table of contents. While this might seem cleaner, to me is unprofessional because all we are doing is hiding the fact that nobody has written a handbook and is unlikely to do so. Not adding a DocPath key is basically "sweeping the problem under the carpet." To me, not finding the item in the handbook table of contents is more frustrating than seeing a "Help Documentation Not Found" or "We Apologize" page.

Lastly, When nothing appears at all in the table of contents, then users are never made aware of a problem. A "Help Documentation Not Found" result does not inform users whether the problem is a bug or a missing handbook. Adding a "We Apologize" page provides some nominal motivation to users to help write a handbook.