EDIT 2013 06 29; No more updates of the active handbook here. The help system prototype is now part of the inofficial portable distribution with plugins

In the attachment you find an extended active handbook prototype.

You may unzip the file preferrably in the book directory of your SMath installation.
Then, the contents page of the internal math referenc book contains a link to the handbook.
Hint: To follow links, just Ctrl-click (files are in edit mode)

EDIT: The interactive book is now available via Extension manager


Here comes the feature request.

Provide a mechanism for easy access to function description files.
- Specify a location in the directory structure, where such files go (similar to other extension handling)
- Whenever the cursor is on a function name, provide link to the corresponding description file (if it exists). That might be a special keyboard shortcut, just like F12 goto definition: FI might mean: goto description.
- Such linking would need to open a separate window, in order not to destroy the currently edited file.
- in a first step, it would be sufficient to provide this for math regions or input placeholders in other regions. One might extend this to text regions.

The feature would allow for independent yet accessible doc spaces. Jump in is always easy via function name. Plugin-providers could provide function description files with backlinks to an also provided overview article.

This linking feature would also significantly reduce the effort for cross references in the handbook files. Linking to a function description would simply be reduced to just mentioning this function. Currently, in order to add a function to the function index, I need to copy an existing link, change the visible text and then edit the link target in a source code editor.

The handbook prototype is mainly bilingual (german, english). As the function descriptions mostly are taken from my pdf manual, not all of them are translated to english yet. Feel free to do so and to provide additional material. This perhaps will need go to the SVN repository.

Edited by user 27 March 2014 16:23:42(UTC)  | Reason: Not specified

Radovan, thanks for the demo video of the handbook.

Handbook updated (file in first post exchanged)
- Added page "Howto add linked handbook pages"
- Added templates for handbook pages
- minor corrections and added function descriptions.

I cannot reproduce the solver problem in the screencast. The default precision is 4 decimal places, whatever that means: 4 significant digits (would be the preferred and only unit-independent variant) or an epsilon setting of 10^-4.

I would not mind having this prototype being the seed for an official help system. But that decision is up to Andrey. At least I feel supported by him in that he corrected some nasty bugs with link and page editing.

Martin

Hi Martin

First of all, wonderful job, that's the most closer attempt to a SMath's embedded guide

2nd (@Andrey) I think that an additional attribute could be added to enable/disable an "Handbook mode"; f.e. that option can enable the toolbar that you have provided for the reference book

3rd (@Martin) IMHO, as for now, a tree-based structure for the files is needed (at least a simple double level structure) to make the Handbook file easier to find (I've attached a couple of screenshots); in the other hand if Andrey found a better way to handle SMath's handbooks, an additional attribute "Handbook root" applied to the main file would be enough


Best regards,

Davide

Edited by user 14 June 2013 17:08:22(UTC)  | Reason: Not specified

That is because all files are in "editible" mode for now. You can't edit links, if clicking them jumps to the target. Andrey has added that upon request by me. You can reset that in the file properties dialog. Before that change, you also had to change the visible text in the editor, it was extremly tedious and error-prone. If Andrey some day includes the handbook in the official distribution, then best would be to reset automatically all involved files to non-editible.

I guess that the handbook can easily be hooked into the reference book by adding an appropriate link into the contents page of the reference book. But I shall do structural changes (nested directories and the like) only after efficient link target editing is available. For now, the need to find the handbook root is mitigated by all pages having the back link included.

Strange, this is not happening on my Win7 32bit

Regards,
Radovan

How about this one. Just unpack the contents of the zip file in post #1 to a subdir activebook in your smath book directory and exchange the attached contents.sm. Then you have handbook access via Help.

Edited by user 14 June 2013 21:00:32(UTC)  | Reason: Not specified

Exactly.

In fact this was enabled by latest changes in link handling. Andrey obviously has decided to focus on extension handling and integration of user contribution instead of, let's say, more basic features like correct symbolic computation or boldfacing vectors. Had he gone the other way around, we would surely admire and appreciate the progress, but would still fight with no consistent way to use community contributions.

@ Andrey: can you provide SVN access for storing the handbook there? A good point in time for that would be the availability of GUI support for link editing. By then I expect other users to contribute pages and they need to be able to integrate their stuff without me being the bottleneck.

Updated, see post #1.

Let me share my current idea on how a help system could be set up.

First, what are the requirements:

• Easy access and navigation for users
  
• Easy extension by content providers without dependence on third party management work
  
• Easy restructuring

How could that be made or what features would be required for that?
1. Easy access:

• If the cursor is on any name, F12 now brings up the dynamic assistant. Additionally, F1 might bring up the Function description sheet, simply a sm file in a dedicated folder
  
• The "insert function" dialog might offer link to the function description or even provide a preview of that (I don't know where currently the examples come from)
  
• The help sytem, invoked by FI (if cursor is not on a function name) or by the reference material button, could be the entry point for the handbook.
  

2. Easy extension

• store user contributions in a hierarchical directory structure under, let's say, installdir/book/activebook
  
• provide a navigation toolbar in the help system with a navigation drop down menu, dynamically reflecting the directory and file structure and taking the entry names from the file properties of dedicated index files (for directories) or the individual files. If these tags are not available, the filename is used.
  
• all function descriptions should go as individual files to a special folder "function index" EDIT: This requires to resolve function names, which differ just by uppercase/lowercase letters. Windows file system cannot handle that difference.
  
• the navigation bar might know what plugin a particular function belongs to and provide dynamic backlink to the index file of a correspondingly named directory if that exists. Otherwise backlinks of items in the function index could go to next, or previous.
  
• in order to document a plugin you (or somebody else ;-) would create a directory named according to the official plugin name (as in extension manager), provide an index file (index.sm) in that directory with file properties set for the desired navigation menu entry in the help system (could be used as name for the function category as well). Finally, funcion descriptions could be provided and stored in the function index.
  In order to link from the index page to the functions of the plugin, it is sufficient to just mention them in a math region, the rest is done by F1.
  

3. That system would provide comfortable browsing without any particular backlink required within the files. This way, restructuring would be extremly easy and the danger of stale links is reduced to a minimum.

Edited by user 21 June 2013 00:15:56(UTC)  | Reason: Not specified

I'd be happy even for a simple and common link managment via context menu+popup window...

Edited by user 21 June 2013 01:19:10(UTC)  | Reason: Not specified

what about "nameplugin.namefunction.sm"
this way you can sort by name in winexplorer and it is not required function name convention