Author Topic: In Line Help  (Read 12681 times)

0 Members and 1 Guest are viewing this topic.

Offline CAD

  • Older Power User
  • *****
  • Posts: 168
  • I've got my eye on you!
    • View Profile
In Line Help
« on: February 03, 2010, 12:46:52 am »
Hi Nostra,

Would it be feasible to have an inline help function / help hover function.
Something like a "?" that when selected provides a hover help function for different parts of PVD.
This could / should be populated with info from users (so you dont have to do it)  ;)
Perhaps it could reference a text / xml file for info that could be user populated.

This would go some way to providing a help system.
three fingered salutation

Offline nostra

  • Administrator
  • *****
  • Posts: 2852
    • View Profile
    • Personal Video Database
Re: In Line Help
« Reply #1 on: February 03, 2010, 02:50:46 am »
It is a bit simpler for me to provide a standard F1 functionality, so this will be most probably the first help system available. I can also implement a "help hover function" some time later.
Gentlemen, you can’t fight in here! This is the War Room!

Offline rick.ca

  • Global Moderator
  • *****
  • Posts: 3241
  • "I'm willing to shoot you!"
    • View Profile
Re: In Line Help
« Reply #2 on: February 03, 2010, 03:06:56 am »
Is this intended to be different than what I suggested here? If so, why would this be preferable?

If the program can be changed to simply handle any call for context-sensitive help, then nostra can just give us a list of valid objects and well can add whatever we like to a help file with the same topic ID. With full-featured and easy-to-use help authoring software available for free, that would be a more versatile approach—and probably easier for users to implement and maintain.

Hover help is nice for new users, but quickly becomes annoying as the need for tool-tip like help diminishes. And then it's not a good option for the longer, more involved help topics and references more likely to be needed on an ongoing basis. For example, a regex reference—even if it would fit in a hover window—is not going to be of much help in troubleshooting a file scanner configuration. The information needs to be available in a separate window—as it would be in a help file. It also can provide me with hyperlinks to other topics in the help file, forum topics, or other web references. Also, using a help file would provide us with a well defined structure for collaborating on developing help topics.

Hopefully, nostra can answer the same question for both of us: Is either one of these options feasible and easy to implement? I'm not a programmer, but my suggestion was born out of the thought that maybe this is as simple as adding one bit of code that handles a F1 press. Help would be called, and it would do the rest. And see he's answered while I type. Doing his seeing-the-future thing again... ;)

Offline CAD

  • Older Power User
  • *****
  • Posts: 168
  • I've got my eye on you!
    • View Profile
Re: In Line Help
« Reply #3 on: February 03, 2010, 04:41:17 am »
Quote
Is this intended to be different than what I suggested here? If so, why would this be preferable?

Just trying to think outside the box.
If nostra can develop context sensitive help system that we can populate, that would assist in developing a help system.
Dont really care if it is hover help or (context sensitive ??) F1

I have been playing with dumping wiki into pdf or htm format.
It is a bit easier for me to use pmwiki rather than tikiwiki.

see attached (not finished) output. (sorry about the format - this is quick and nasty)
That could be a start of a downloaded help file.


[attachment deleted by admin]
three fingered salutation

Offline rick.ca

  • Global Moderator
  • *****
  • Posts: 3241
  • "I'm willing to shoot you!"
    • View Profile
Re: In Line Help
« Reply #4 on: February 03, 2010, 07:53:57 am »
How are you capturing the wiki topics? I can cut & paste topics from the wiki into a HelpNDoc project topic, but it would be easier to link the topics to HTML files. Do you know if it's possible to download the wiki topics as HTML files?

I'm still curious, but that's probably not a good idea anyway. Help topics can be linked directly to wiki topics. So it would be possible to create a help file that was made up mainly of links to the wiki. That means a help context link might take the user directly a topic that would include one or more wiki topics as child topics. (It doesn't appear possible to link directly because a link topic doesn't have a topic ID.) The same could be done for applicable forum topics.

The wiki topic links are http://www.nimidia.com/pvd_wiki/tiki-index.php?page=...
or for the print format versions http://www.nimidia.com/pvd_wiki/tiki-print.php?page=...

Code: [Select]
About
Add-video-files
Adding-a-New-Episode
Adding-a-New-Movie
Advanced-Searches
Application-Title-Bar
Backup-Database
Bookmarks
Change-Episode-Number
Clear-movie-details
Configuring-PVD
Connect-to-server
Creating-a-Log-File
Creating-a-New-Database
Delete-a-Movie
Download-PVD
Duplicate-a-Movie
Edit-a-Movie
Exit
Exporting
Filter-by-Bookmarks
Filter-by-Drives
Filter-by-Loaned
Filter-by-MovieSeries
Filter-by-No+Poster
Filter-by-Owned
Filter-by-Viewed
Filtering-Movies
Getting+Started
HomePage
How-to-Add-a-Movie
How-to-Install-Plugins
Importing-movie-details
Installing-PVD
Introduction
Launching-PVD-for-the-First-Time
Loan-a-Movie
Menu-Bar
Movies-View
New-Movie-Master
Open-a-Database
Open-containing-folder
Optimize-Database
Organize-files-by-episode
Password-Protect
People-View
Permissions
Play-a-Movie
Read-Video-Info
Repairing-a-PVD-database
Reset-Filters
Restoring-a-Database
Saving-a-Database
Screenshot-Maker
Search
Seen
Set-ID
Support
Switch-to-People-View
Toolbar
Undelete-a-Movie
View-Full-Screen
Wish

Maybe I'll try putting these links in a help project, and seeing if I can arrange them in some sort of logical, hierarchical arrangement suitable for context-sensitive access. :-\
« Last Edit: February 04, 2010, 08:22:45 am by rick.ca »

Offline CAD

  • Older Power User
  • *****
  • Posts: 168
  • I've got my eye on you!
    • View Profile
Re: In Line Help
« Reply #5 on: February 03, 2010, 11:50:00 pm »
Quote
How are you capturing the wiki topics?

I edit  each page and copy /paste wiki text into pmwiki.
It needs some modification as the markup language it not exactly the same.

Quote
Do you know if it's possible to download the wiki topics as HTML files?
Yes - each page is its own html file and can be linked to.
I guess you could use - download website type software.

The file I posted is all the individual pages pulled together and dynamically "published" as one large html file.
This can then be saved/downloaded - converted to a PDF etc.

Unfortunately I don't have hosting facilities. I'll have a hunt around and see if I can find something.
three fingered salutation

Offline nostra

  • Administrator
  • *****
  • Posts: 2852
    • View Profile
    • Personal Video Database
Re: In Line Help
« Reply #6 on: February 04, 2010, 02:57:20 pm »
Quote
Is this intended to be different than what I suggested here? If so, why would this be preferable?

No, it's pretty much the same thing.

Quote
If the program can be changed to simply handle any call for context-sensitive help, then nostra can just give us a list of valid objects and well can add whatever we like to a help file with the same topic ID. With full-featured and easy-to-use help authoring software available for free, that would be a more versatile approach—and probably easier for users to implement and maintain.

It is in fact very easy to implement context sensitive help with keywords or IDs, but I need to know which help format will be used (HTML, HLP) to execute help in the right way.
Gentlemen, you can’t fight in here! This is the War Room!

Offline rick.ca

  • Global Moderator
  • *****
  • Posts: 3241
  • "I'm willing to shoot you!"
    • View Profile
Re: In Line Help
« Reply #7 on: February 04, 2010, 09:55:46 pm »
Quote
It is in fact very easy to implement context sensitive help with keywords or IDs, but I need to know which help format will be used (HTML, HLP) to execute help in the right way.

HTML is clearly preferable. I had better explain fully, as I could easily be making some incorrect assumptions. Attached is a "proof of concept" I'm working on. This is an HTML compiled help file (.CHM) created with HelpNDoc. It includes hyperlink topics for all existing wiki topics, organized by the PVD menu layout. The idea here is simply to provide access points into the wiki. Once a hyperlink topic is selected, the wiki topic appears in the window, just as it would in a browser. The user can then use wiki hyperlinks or the TOC for navigation. The beauty of this, of course, it all of the content is provided by the wiki. And the links, of course, can be to anything on the web.

Unfortunately, hyperlink topics don't have a Topic ID, and therefore cannot be used directly for context sensitive help. Regular topics, however, presumably can be accessed by referring to their Topic ID. The hyperlink topics can then be added as child topics. I've illustrated how this might be done by adding two topics to the help file—"New Movie Master" with the Topic ID TMovieMaster, and "Preferences" with Topic ID TPrefsForm. These topic ID's are what I believe are called the Window Class of the respective program dialogs. So this is my biggest assumption—that context sensitive help can be implemented simply by using the Window Class of the source as the Topic ID in the help file. Have I got this right?

A significant problem with this approach is the Window Class may not provide a specific enough reference for a help topic. The Preferences dialog, for example, has the same Window Class regardless of what part of it is being used. So I don't know how we might provide different context sensitive help topics for the many different things handled within that window. Is there another more specific reference that might be used—without making the whole thing too complicated? It is, of course, not so difficult to navigate to a specific sub-topic in the help file.

Quote
No, it's pretty much the same thing.

But wouldn't the hover help topics have to be created and maintained separately from the wiki and any help documentation? I assume it would be similar to a language file—where text is associated with specific objects in the program. That would be nice too, but (if my imaginings are correct) doesn't really have the same functionality as a help system.

[attachment deleted by admin]

Offline nostra

  • Administrator
  • *****
  • Posts: 2852
    • View Profile
    • Personal Video Database
Re: In Line Help
« Reply #8 on: February 04, 2010, 11:38:28 pm »
In this chm file you have an Index (a list of keywords). I can assign these keywords to a specific control, so that when a user presses F1 when a control is focused he will get help according to this control. It is also not too difficult to add some additional logic to generate keywords dynamically.

Quote
Quote
No, it's pretty much the same thing.

But wouldn't the hover help topics have to be created and maintained separately from the wiki and any help documentation? I assume it would be similar to a language file—where text is associated with specific objects in the program. That would be nice too, but (if my imaginings are correct) doesn't really have the same functionality as a help system.

I meant context sensitive help. Hover help is really a bit different and in fact I am not sure if its really needed at this point.
Gentlemen, you can’t fight in here! This is the War Room!

Offline CAD

  • Older Power User
  • *****
  • Posts: 168
  • I've got my eye on you!
    • View Profile
Re: In Line Help
« Reply #9 on: February 04, 2010, 11:51:55 pm »
It doesn't really matter what sort of help system there is (IMO)
But users (especially new users) suffer from a lack of a help system.

A single large html file or PDF is simplest to implement.
F1 opens the file.

An context sensitive help file could simply reference the relevant wiki page. Just need to make sure page names dont change.

also note .chm files are becoming more and more frowned upon due to securty risks the pose. A lot of systems block execution by default.
three fingered salutation

Offline nostra

  • Administrator
  • *****
  • Posts: 2852
    • View Profile
    • Personal Video Database
Re: In Line Help
« Reply #10 on: February 05, 2010, 12:02:34 am »
We also could use a single HTML file with anchors, I suppose.
Gentlemen, you can’t fight in here! This is the War Room!

Offline rick.ca

  • Global Moderator
  • *****
  • Posts: 3241
  • "I'm willing to shoot you!"
    • View Profile
Re: In Line Help
« Reply #11 on: February 05, 2010, 01:29:58 am »
In this chm file you have an Index (a list of keywords). I can assign these keywords to a specific control, so that when a user presses F1 when a control is focused he will get help according to this control.

I hope I'm not getting hung up on terminology...but it seems to me a "Topic ID" must be something used to reference a specific topic (i.e., I imagine it being passed as a parameter when the help file is called). Just to verify how they worked, I did add "Keywords" to each topic. They end up in the "Index" of the help file, and reference the topics they are associated with via the index. A keyword can be associated with more that one topic, so I'm assuming it can't be used to access one topic directly. If a keyword is only associated with one topic, maybe it will effectively display that topic, but probably in the index tab rather than the content tab. That wouldn't be desirable because the TOC is critical in providing the associated links to the wiki (or elsewhere).

The idea of using "Windows Class" is rather restrictive, if that's what you're getting at. But I'm not sure what you mean "specific control." If that's something more specific than a window class, and you can use that to call the associated topic (not keyword), that would be perfect. I only suggested window class because I see it exists and can be determined but the user (I'm using my AHK "Window Spy"). What would be really cool is if pressing F1 would load help and display an associated topic—if there is one—but also display the control name (or keyword or whatever you want to call it) in the status bar. Then, if there were no topic associated with that control, the user would be able to create one simply by adding a topic with that Topic ID.

A single large html file or PDF is simplest to implement.

It's only simplest if one of those already exist. I think we've already established neither is particularly easy to create, and the result is not nearly as useful as the wiki itself.

Quote
An context sensitive help file could simply reference the relevant wiki page. Just need to make sure page names dont change.

The primary benefit of what I'm suggesting is that it can reference an existing source. Using a wiki is still the most effective way to provide collaborative help authoring. The main purpose of the help file will be to provide the contextual links to the relevant wiki topics. It can also be used in the same way to provide links to discussion topics or anything else here (e.g., the download page). Yes, it's important page names aren't changed. In most cases, there's no reason to change the name of a page once it has been created. What will be more of an issue is updating the help file for new wiki topics. HelpNDoc only provides for the manual addition of topics. It would be nice if it would import a list on new hyperlink topics.

Quote
also note .chm files are becoming more and more frowned upon due to security risks the pose.

Maybe we could add a warning the help file should be save for browsing the wiki and this site, but should not be used as a browser.

 

anything