Is there any interest in having the help system dynamically load the table of contents for each of the help files you specify in the program options? I haven't seen this on the list of feature requests but I personally would like see it in their.
I'm willing to do the coding and submit it as either:
1) A component (descendent of the TTreeView already being used) that encapsulates all of the logic to parse, build, and manage the MultiCHM process with events for selection of the items that provide all of the information necessary to load the topic in the webbrowser via a call to uHelpDisplay, etc. Basically you just register CHM files. e.g. "TMultiCHMTreeView.RegisterCHMFile( 'c:\someplace\css-2.1.chm' );". My initial thoughts were to do this in a multi-threaded fashion so the registration of any CHM is a non-blocking call but I haven't seen much use of threads in the project and I wouldn't want to submit something everyone isn't comfortable with supporting.
2) A utility unit (or modification to uHelp) that you can call with a path to a CHM file and a reference to some "top" Treeview node and it will fill it in the necessary sub nodes and items. e.g. "ParseCHMTOC( 'c:\someplace\css-2.1.chm', MyNode );".
Alternately I can just provide a tool to assist whoever is maintaining the MultiCHM.xml file but I think the dynamic generation of the table of contents makes for an easier develolper maintenance situation (i.e. maintance of the MultiCHM.xml file goes to nil as it is no longer used), allows for the flexibility to create something like a "floating" help system via something like NewComponent.Assign or reassigning parent, decouples the "build logic" from the actual uHelp unit code thereby streamlining it, and allows the help system to actually be dynamic and include any number of CHM files instead of the specific list now hard coded.
Whichever works with the roadmap of the project. All options are fine by me or even if someone else wants to do it I'm happy to bounce ideas and/or help in whatever way I can.
Give me some feedback.
--Michael
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Firstly, sincerely thank you for writing about your intentions.
Preamble.
As you probably noticed, there's an undocumented feature there.
1. Load the multiCHM.xml file by selecting the 'Help' tabsheet
2. Use the tree structure and Search via <F2>-key.
History and features of multi help file.
I started to work with an xml file, because I couldn't figure out how to do otherwise.
- Treeview icons may vary depending on the node,
- Help file may depend on user language,
- Not all nodes are searchable,
- Some keys need special conversions (replace '-' by '_') and some keys don't,
- Search results may need something like a completion proposal, as soon as several results are available (eventually coming from different help files).
Consequently, *you're right*, this xml file is an endless story : hard-coded (not easily expandable) and difficult to maintain.
To be complete, we don't know anything about the future of the .chm format, and we don't integrate the help provided by a phpdocumentor from user's files or any bazaar like that O:-).
Technically speaking.
Well, using threads will undoubtedly be very valuable : ready to go.
A cache system (based upon an embedded database, or not ;) could be essential to speed up searches ; mainly if we're planning to integrate any help file whose pathname could be defined elsewhere, inside a configuration file for example.
Component or utility unit ? A component could be more easily reusable by another project. Its licence could be different from the one of Dev-PHP. Seems much better, but I'm afraid that this « freedom / independance » implies more efforts.
It's your turn.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I started to work with an xml file, because I couldn't figure out how to do otherwise.
- Treeview icons may vary depending on the node,
Recommendation: Use simple rules for the icons as follows: If there are children then make the icon a "book" icon, otherwise use the "document" icon. It doesn't need to be perfect or match the CHM specification exactly. This can be enhanced later if, say for instance the keyword file is pulled as well.
- Help file may depend on user language,
Language shouldn't matter as the strings in the CHM are unicode.
- Not all nodes are searchable,
Who says they can't be searchable? This all depends on what information is pulled from each node as you parse the file.
- Some keys need special conversions (replace '-' by '_') and some keys don't,
I don't think this is an issue as parsing the actual CHM file pulls characters in a HTML encoded manner (e.g. '&' is actually encoded as "&" within the link in the HHC file.
- Search results may need something like a completion proposal, as soon as several results are available (eventually coming from different help files).
If you wanted to integrate the search functionality into the control I would make the control be based on a Panel instead and embed the TTreeview and build the other controls on instantiation.
I won't be able to communicate for a while. I just found out my mother died so I apologize for not responding more fully.
--Michael
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Is there any interest in having the help system dynamically load the table of contents for each of the help files you specify in the program options? I haven't seen this on the list of feature requests but I personally would like see it in their.
I'm willing to do the coding and submit it as either:
1) A component (descendent of the TTreeView already being used) that encapsulates all of the logic to parse, build, and manage the MultiCHM process with events for selection of the items that provide all of the information necessary to load the topic in the webbrowser via a call to uHelpDisplay, etc. Basically you just register CHM files. e.g. "TMultiCHMTreeView.RegisterCHMFile( 'c:\someplace\css-2.1.chm' );". My initial thoughts were to do this in a multi-threaded fashion so the registration of any CHM is a non-blocking call but I haven't seen much use of threads in the project and I wouldn't want to submit something everyone isn't comfortable with supporting.
2) A utility unit (or modification to uHelp) that you can call with a path to a CHM file and a reference to some "top" Treeview node and it will fill it in the necessary sub nodes and items. e.g. "ParseCHMTOC( 'c:\someplace\css-2.1.chm', MyNode );".
Alternately I can just provide a tool to assist whoever is maintaining the MultiCHM.xml file but I think the dynamic generation of the table of contents makes for an easier develolper maintenance situation (i.e. maintance of the MultiCHM.xml file goes to nil as it is no longer used), allows for the flexibility to create something like a "floating" help system via something like NewComponent.Assign or reassigning parent, decouples the "build logic" from the actual uHelp unit code thereby streamlining it, and allows the help system to actually be dynamic and include any number of CHM files instead of the specific list now hard coded.
Whichever works with the roadmap of the project. All options are fine by me or even if someone else wants to do it I'm happy to bounce ideas and/or help in whatever way I can.
Give me some feedback.
--Michael
> Give me some feedback.
Firstly, sincerely thank you for writing about your intentions.
Preamble.
As you probably noticed, there's an undocumented feature there.
1. Load the multiCHM.xml file by selecting the 'Help' tabsheet
2. Use the tree structure and Search via <F2>-key.
History and features of multi help file.
I started to work with an xml file, because I couldn't figure out how to do otherwise.
- Treeview icons may vary depending on the node,
- Help file may depend on user language,
- Not all nodes are searchable,
- Some keys need special conversions (replace '-' by '_') and some keys don't,
- Search results may need something like a completion proposal, as soon as several results are available (eventually coming from different help files).
Consequently, *you're right*, this xml file is an endless story : hard-coded (not easily expandable) and difficult to maintain.
To be complete, we don't know anything about the future of the .chm format, and we don't integrate the help provided by a phpdocumentor from user's files or any bazaar like that O:-).
Technically speaking.
Well, using threads will undoubtedly be very valuable : ready to go.
A cache system (based upon an embedded database, or not ;) could be essential to speed up searches ; mainly if we're planning to integrate any help file whose pathname could be defined elsewhere, inside a configuration file for example.
Component or utility unit ? A component could be more easily reusable by another project. Its licence could be different from the one of Dev-PHP. Seems much better, but I'm afraid that this « freedom / independance » implies more efforts.
It's your turn.
I started to work with an xml file, because I couldn't figure out how to do otherwise.
- Treeview icons may vary depending on the node,
Recommendation: Use simple rules for the icons as follows: If there are children then make the icon a "book" icon, otherwise use the "document" icon. It doesn't need to be perfect or match the CHM specification exactly. This can be enhanced later if, say for instance the keyword file is pulled as well.
- Help file may depend on user language,
Language shouldn't matter as the strings in the CHM are unicode.
- Not all nodes are searchable,
Who says they can't be searchable? This all depends on what information is pulled from each node as you parse the file.
- Some keys need special conversions (replace '-' by '_') and some keys don't,
I don't think this is an issue as parsing the actual CHM file pulls characters in a HTML encoded manner (e.g. '&' is actually encoded as "&" within the link in the HHC file.
- Search results may need something like a completion proposal, as soon as several results are available (eventually coming from different help files).
If you wanted to integrate the search functionality into the control I would make the control be based on a Panel instead and embed the TTreeview and build the other controls on instantiation.
I won't be able to communicate for a while. I just found out my mother died so I apologize for not responding more fully.
--Michael
Time is the best healer. We shall be waiting for you.