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.

---

activebook 2013 06 22.zip (280 КиБ) скачан 128 раз(а).

Thank you Martin

I enjoyed this very much (see here). Although I did not fully understand how was this made, I support Martin in all his suggestions in order to make this procedure more user friendly.

Martin, I hope that you would not mind if I say that your Handbook made in this way (including the mentioned suggestions) could be an official Help for SMath .

Regards,
Radovan

Wrote

Thank you Martin

I enjoyed this very much (see here). Although I did not fully understand how was this made, I support Martin in all his suggestions in order to make this procedure more user friendly.

Martin, I hope that you would not mind if I say that your Handbook made in this way (including the mentioned suggestions) could be an official Help for SMath .

Regards,
Radovan

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

You are very welcome Martin

I just like these screencasting thing (thanks to kilele).

Your ideas about templates and Handbook organization is something SMath just needs. I fully accept that. Help file inside SMath based on the Handbook principles made by you, would be something great. I would very gladly translate it into my native language and keep tracking about it.

Thank you for the explaining about links. I new something was about that. It still does not seem to be attractive for some other users. The most desirable behavior would be just to make this linking thing the as simple as possible, without manual file editing in some HTML,XML editor. We should concentrate on files and links and their organizations. I hope that Andrey will find the way to add some feature regarding the links in order to make it simpler to insert and use.

One minor observation. I still do not understand why I should use CTRL+click for using the links, while in the Reference Book just simple mouse click will do the thing. Keeping the finger on CTRL button while browsing the files and contents is not quite appealing.

About the FindRoot() in your example. I do not know why I get different result (Win7 64bit), but I messed up with different Nonlinear Solvers by Davide (some of them were totally unofficial). I think we should not worry about this at the moment. We will see when Davide announce the official version.

Regards,
Radovan

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

---

I might exaggerating a bit. But just imagine the possibility to open a Handbook (similar to Reference Book) from within SMath Viewer

Regards,
Radovan

Wrote

One minor observation. I still do not understand why I should use CTRL+click for using the links, while in the Reference Book just simple mouse click will do the thing. Keeping the finger on CTRL button while browsing the files and contents is not quite appealing.

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.

Wrote

One minor observation. I still do not understand why I should use CTRL+click for using the links, while in the Reference Book just simple mouse click will do the thing. Keeping the finger on CTRL button while browsing the files and contents is not quite appealing.

Wrote

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-editable.

As soon as I posted this, I remembered that the files from the Reference Book are not editable. I asked that Andrey long time ago, he explained and I forgot - as usual. I also understand your point now. Thank you.

Regards,
Radovan

Wrote

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.

Strange, this is not happening on my Win7 32bit

Regards,
Radovan

---

Wrote

For now, the need to find the handbook root is mitigated by all pages having the back link included.

You're right

BTW a 3rd way could be to add all the worksheets inside a folder and to add an additional "cover" worksheet outside this folder with a link to the HandBook.sm; this not require many efforts and help to have a clear front-end.

Wrote

Strange, this is not happening on my Win7 32bit

I've seen now your video, I do not understand from where the initial results come...

---

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.

---

contents.sm (3 КиБ) скачан 62 раз(а).

That is quite close to the desired Help system

It seems to me that now the crucial things are (I might repeating myself)
- managing links and "contents" files
- revise Home, Back, Copy - add new ones etc.

For instance, Back button will delete part of the file under Area region. It is not happening when the file attribute is "non-editable". We can open many instances of the Reference book. I am not sure if this is good or not. Maybe to have only two of them open at the same time. The official one, and the user one. That means there is a way to make a user reference book-handbook as well. For instance, File|Open| might have "Handbook" option which will open a dedicated "contents" file into the "Reference book" environment. (borrowed from Mathcad of course). Examples could be self contained and put in the Area region. This way we can copy the entire region into the working sheet and play with it. I suppose there are some other glitches and worth considering ideas, some already mentioned, about this as well.

This way we are quite close to make our own Handbooks as well in a quite acceptable and user friendly manner. Do you agree

Regards,
Radovan

Wrote

This way we are quite close to make our own Handbooks as well in a quite acceptable and user friendly manner. Do you agree

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.

mkraska, you're absolutely right. Please see PM.

Regards.

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.

While making more handbook pages, a problem popped up, which I was not aware when making the topic starter feature request.

The function names in SMath do not form unique file names under Windows. Quite frequently, there are function names which just differ by case difference of the first letter, as in Min() and min(). The file names Min.sm and min.sm cannot co-exist in the same directory.

In order to resolve these cases in a transparent manner, we need to have some convention on how to handle that. The rule must be simple and strict in order to enable automatic identification of the handbook page by function name.

The following options crossed my mind.
- subdirectory in the function index directory for names with uppercase letters. All function names with uppercase first character map to that directory. That would require to move existing pages, thereby breaking the existing links. As long as there is no GUI support for link editing, this is not feasible.
- Special markup of capital first characters, perhaps using a leading underscore, e.g. Min() -> _min.sm. This might be feasible, if we agree on not having function names starting with underscore.

For now, I shall use the underscore just in those cases, where conflicts arise. Smart linking from capitalized function names might first search for a underscore file name and if that is not found, then refer to the lowercase variant.

May be there are better ideas in the community.

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

Wrote

Another "bad" idea could be to double the letter for capital ones ? For example: mmin() for Min()

Yes, that might be feasible. I just feel a little more comfortable with forbidding function names starting with underscore than function names starting with double character.

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

Wrote

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

I like this. Perhaps one could just split the function index directory into subfolders built-in plus the plugins and store the descriptions there. Most important is that there is still a neat way for SMath to guess, where the description can be found. And the plugins must have official names that are internally known to SMath and visible to handbook writers. Possibly, installing a plugin could create such a subdirectory for documentation as well.

I guess that is how it is going to go. Still there is a rule for function names: built-in functions or functions inside a given plugin must have names that differ by more than character case.