View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0000540||Cinelerra-GG||[All Projects] Feature||public||2020-11-24 16:18||2021-01-03 14:33|
|Target Version||Fixed in Version|
|Summary||0000540: Context help via HTML manual|
|Description||The small patch attached demonstrates how the HTML form of Cinelerra manual (see BT538) can be used to provide context help with minimal efforts.|
|Additional Information||Prerequisite: HTML manual (see BT538) deployed in the subdirectory doc of the Cinelerra installation directory, so that if the cin binary is|
then the title page of the manual must be in
If you do not wish to build HTML manual just now by yourself, you can download it from my webserver as
and unpack under cinelerra-5.1/bin/doc.
Now apply the tiny patch cin_5.1-help.diff.gz (in attachment to this BT) in the topdir of Cinelerra sources and rebuild Cinelerra. The only .C file changed is cinelerra/pluginpopup.C (changed minimally), and the corresponding pluginpopup.h, of course. There is one new file, doc/ContextManual.pl (it is a perl script and must have execute permissions), and one added line to doc/Makefile which assures installation of ContextManual.pl into bin/doc.
Now we can test the stuff.
Check that ContextManual.pl is placed in bin/doc and is executable. Check that CinelerraGG_Manual is also placed in bin/doc.
Run cin, make some video and audio tracks, drop several audio and/or video effects on the tracks. Now, if you press right mouse button over some plugin bar, there will be at the bottom of the plugin popup menu an additional command 'Context help'. Executing the 'Context help' command should bring a new browser window (or browser tab) with that section of the manual which documents the plugin on which you have executed the context help command. Try to invoke such manual pages for several different plugins to look how it works.
Such a context help engine is very simple. The plugin popup menu command executes the perl script ContextManual.pl with the current plugin title as a single argument. ContextManual.pl does the following.
1. Open that HTML file of the manual which contains 'Contents'. The actual Contents file name is defined at the start of ContextManual.pl.
2. Scan the Contents file (via perl regexp) to search the contents line for the argument as the exact text string, between <A> and </A> HTML tags. If found, extract the HREF file name and transfer it to the browser.
3. If exact match not found, scan Contents for an incomplete case insensitive match in the similar manner.
4. If still not found, grep the whole manual for exact match and show in browser the first file where a match was found.
5. If not found, repeat (4) case insensitive.
6. Show manual section on FFMpeg plugins if the argument starts with 'F_', or on Ladspa if it starts with 'L_'.
7. If still nothing found, show Contents itself.
Several plugins are documented with section titles containing some special symbols inappropriate for regexps, for example, '/' or '&', or have slightly different title. For such plugins rewritten regexps are defined at the beginning of ContextManual.pl.
When executed without any argument (such a call may be added to 'shell cmds') ContextManual.pl shows Contents.
When showing manual sections, ContextManual.pl executes browser in background to prevent the calling Cinelerra thread from blocking.
Of course, this all is not a completed solution. It is nothing else than a prototype, an example that with our HTML manual we can, after editing only one single .C file, get context help for all the Cinelerra plugins, including even that plugins which do not exist yet, but will be created (and documented) in future.
It is possible to make some GUI controls which will call help in every other program or dialog window. Such a command has to do nothing more than execute ContextManual.pl with some appropriately defined keyword capable of identifying the right chapter/section/subsection of the manual. The decision, where and in which form could such GUI controls appear, should be best addressed to another person - who knows Cinelerra widget set much better than me.
As ContextManual.pl is a perl script, it can be easily extended when needed. It is also very easy to debug topic searches because this script can be executed from command line.
|Tags||No tags attached.|
Please read the last note by me on BT538: Glossary, and the cross references having only caption name or caption number alone, work now - implemented in the new patch to the latex2html translator. The necessary patches to latex2html and CinelerraGG_Manual are uploaded there, in BT538.
Index entries in PDF should be clickable hypertext references. Install qpdfview and forget other PDF viewers like okular or whatever. Qpdfview allows loading references in additional tabs, leaving the text just viewed in the current tab.
On figure references. In the PDF text, having just 'figure 2.13' looks definitely better. But in HTML, may be, better would be figure name instead of the figure number as the reference text: easier to click on it than targeting a short number, and one can immediately read what for a figure it is, whether there is reason to click on it at all. I am unsure what would look better in the HTML version. If I find how to change figure references, perhaps I'll try to test this...
I think the glossary is useless in the HTML version, as is the index in the PDF version. We could eliminate them if it's not a problem.
If footnotes are problematic we can delete them and replace them with a line in the main text.
|Thanks for the effort. It was just an idea to make finding content via search engines better, if it is technically feasible. You will be able to decide which variant is most feasible, as I haven't found the time to test it yet.|
Update: the latex2html is working very well and I now have the procedure to create the HTML version after I create the PDF version and will upload the latest to the website to keep in synch.
As suggested by sge, I tested latex2html with '-long_titles 5' which names the single HTML pages more search engine friendly using the section/subsection titles. It does look better, but unfortunately it created 2 problems that ruin the results. 1) all of the footnote credits come out with 2 numerical values one of which is totally bad. And 2) There are 3 fewer files when using long_titles and I think this can happen when 2 different sections use the same title so it writes over the first one when encountering the second one. This could probably be fixed but then future additions might mess it up and it would be hard to catch the error.
- Andrea has added index entries and they show and are usable in both the PDF and HTML versions and there can be more added/changed as needed.
- The Glossary is not working correctly in HTML and I have hit a brick wall trying to fix it. It was already difficult to do in the PDF version but Andrey got that going for us. The Glossary gets stuck on the end of the last section "Workflow with multi-cam and audio".
- The other thing I could not fix that I do not like is each reference to a figure (as well as any referenced section) includes not only the number of that figure but also the caption that is under that figure. For example in the "Camera and Projector" section instead of just seeing (figure 2.13) it shows up as (figure 2.13Color3way on Temporary).
Latex2html can use longer HTML file names. If the manual were segmented to Chapter level, it were looking definitely nicer. But I expect, if we segment this document to Chapter or Section level, some sections will be huge and inconvenient for browsing. When we create several hundreds HTML files with long names, perhaps they still will not reflect relevant subsection names very well, and it will be complicated to sort them.
Sam, can you translate the manual with latex2html by yourself? Wenn not, I can make an experimental translation with longer names for your evaluation.
Yes, HTML can be much faster to navigate than PDF: it is segmented on many smaller files rather than one huge document. But there is one more advantage: in HTML one can open links in new tabs/windows while almost all PDF readers can navigate in a single window only. I know no multitab PDF viewer for Windows and only one for Linux. That one for Linux is qpdfview (https://github.com/bendikro/qpdfview), and I expect, very few users know this one. Desktop default viewers (KDE, GNOME, Acroread) cannot display PDF multitab.
I followed the appearance of Index and Glossary in the manual. Latex2html does support Index, but I expect, it does not support Glossary yet. Perhaps I'll make it to understand Glossary later, when the preceding changes to latex2html will be integrated, and Index in the manual also populated more. A representative Index makes a big manual really more informative.
@Andrea_Paz Thanks for testing!
You will have to reapply that patch and again copy over the html manual files to the doc subdirectory as this was not checked into GIT. It is not feasible to include the manual with the CinelerraGG code. Refer to note 4379 by sge.
Everything is OK for me (Arch + KDE + Firefox).
In the terminal I have the following messages repeated several times but, I repeat, that everything works fine:
(/usr/lib/firefox/firefox:162379): GLib-GObject-WARNING **: 13:14:13.608: invalid (NULL) pointer instance
(/usr/lib/firefox/firefox:162379): GLib-GObject-CRITICAL **: 13:14:13.608: g_signal_connect_data: assertion 'G_TYPE_CHECK_INSTANCE (instance)' failed
Note: The context help from the plugin bar was lost though.
Thanks for embedding on the server Phyllis. Is there a possibility to name the single HTML pages more search engine friendly? Currently it writes node21.html as an example. The page are just numbered consecutively. It would be better to name the page after the chapter names, if it would be technically feasible.
Some progress here -- more to do.
1) The HTML manual is now on the website (currently using the one provided until I try to do the update as in BT 0000538). There is a link on the main page under Documentation - underneath the PDF User Manual version for now.
2) GIT checkin of preferences.C to add Shell Button. As already stated it will only show if you use a new bcast5 BUT you can just edit $HOME/.bcast5/Cinelerra_rc and add it via the following:
- first increase SHBTNS_TOTAL by 1; if using the default this would now be: SHBTNS_TOTAL 5
- then add after the current last SHBTNSxxx the following lines:
SHBTN4_NAME HTML Current Manual
SHBTN4_COMMANDS $CIN_BROWSER https://cinelerra-gg.org/download/CinelerraGG_Manual
If Andrea has time could you verify that this works for you too because I use Firefox on Fedora?
BTW: the HTML version is really nice and seems a lot faster to use.
On getting HTML manual index via shell cmds: look in cinelerra/preferences.C near line 430. There are the following lines of code:
shbtn_prefs.append(new ShBtnPref(_("Current Manual"), "$CIN_BROWSER https://cinelerra-gg.org/download/CinelerraGG_Manual.pdf"));
shbtn_prefs.append(new ShBtnPref(_("Setting Shell Commands"), "$CIN_BROWSER file://$CIN_DAT/doc/ShellCmds.html"));
shbtn_prefs.append(new ShBtnPref(_("Shortcuts"), "$CIN_BROWSER file://$CIN_DAT/doc/shortcuts.html"));
shbtn_prefs.append(new ShBtnPref(_("RenderMux"), "$CIN_DAT/doc/RenderMux.sh"));
Inserting one more line should do that, showing HTML manual index via browser:
shbtn_prefs.append(new ShBtnPref(_("HTML manual"), "$CIN_DAT/doc/ContextManual.pl"));
To actualize it in user's ~/.bcast5/Cinelerra_rc, of course, removing old Cinelerra_rc will be necessary.
Thank you for testing my prototype.
On HTML manual: although it is possible to check it into GIT, it is not absolutely necessary. HTML manual can be treated exactly in the same way as CinelerraGG_Manual.pdf with the only difference: it is not a single file but a directory with a set of files in it. HTML manual can be generated at once with CinelerraGG_Manual.pdf, I even provided a shell script (translate_manual, in BT538) which builds both manual forms. So, I think, maintaining in GIT the Latex manual is sufficient.
On using the 'h' keystroke for help: I would support the same approach, some key, 'h', or Alt/h, or F1, or whatever. I did know some widget sets, like Motif widgets, but I have (yet) no knowledge on the Cinelerra's own native widget set. Perhaps I can try to figure out where (and whether) one can hook on keystrokes to call for help. I need a month or so, I think it is not extremely urgent.
Finally I have successfully tested following the exact steps you outlined at the beginning of this BT. Good proof of concept as it worked well.
Unfortunately in preliminary discussions all we had conceptualized here was using the "h" key to get help and somehow connecting wherever the cursor was to refer to that section. In other words we had no idea how to get this implemented. I am going to see if using the "shell cmds" button in the upper right hand corner of the main program window can at least bring up an index to the html manual which would be stored on the CinGG website.
There is currently in the GIT "Project" the source code under Cinelerra-GG, the latex manual under "Latex Manual" and the old irrelevant libreoffice .odt under "Manual".
1) If possible I think we should put your html manual in place of the "Manual" and keep it updated there. (Of course, I don't really know how to do that but eventually I can figure it out).
2) Then in the same way that the Latex Manual is updated and saved/used at https://cinelerra-gg.org/download/CinelerraGG_Manual.pdf, the HTML Manual would be put in the same directory under a subdirectory and saved/used from there. And the index would be used to get around.
I do not think it is going to be possible to actually hook up the "h" key to get what the users expect to see as in other programs. More later.
Searching Index instead of Contents (or in addition to) would be good. But we do not (yet) have Index in Cinelerra manual. It should be not too difficult to construct it, but I never tried to make Index in LaTeX documents and have no experience.
Perhaps when our HTML-capable manual will be adapted and implemented in git, then I can look how to produce Index in HTML form and write some script to search for keywords in it.
Great, everything works fine! (Sorry for making you repeat the explanations twice)
Good thing would be to put a "Help" button next to the menus in the Program window, which opens the manual index with the web browser. This page could have a "search" function for names and topics. Inside the "i" button would remain the link to the manual in pdf. I don't know if this is possible.
Thank you very much.
The procedure to checkout, patch and translate CGG manual
These commands can be executed from any directory with user's write permissions. Let's expect that the patch CinelerraGG_Manual.diff.gz is in user's home directory. rename-pngs is to be executed only once. Patched latex2html must be installed beforehand.
git clone "git://git.cinelerra-gg.org/goodguy/cin-manual-latex.git" master
zcat ~/CinelerraGG_Manual.diff.gz | patch -p1
chmod +x rename-pngs translate_manual
If everything successful, the directory CinelerraGG_Manual will be created with html manual inside. This directory has to be transferred completely into bin/doc.
Checking out Cinelerra itself from git is described on https://www.cinelerra-gg.org/downloads/ (and somewhere in the manual). It is also possible to download a source package from https://cinelerra-gg.org/download/pkgs/src/. Then to patch it (assuming the patch being in home directory):
cd cinelerra-5.1 (or how cinelerra's topdir is called by you)
zcat ~/cin_5.1-help.diff.gz | patch -p1
chmod +x doc/ContextManual.pl
Then build CGG as usual (autogen.sh, configure, make, make install, etc.)
If successful, after `make install' there should appear ContextManual.pl in bin/doc, and the whole CinelerraGG_Manual directory with html and png files in it must have been copied into bin/doc. And you can begin testing.
I would like to do a test (and also of BT538), but I do not understand how to do it.
I build from git, but not because I know how it works, I just copy and paste the commands. So I don't know how to apply a patch (sorry!). Can you explain me how to do it?
Another question: before recompiling, you don't have to put the html manual in
/path/doc instead of /path/bin/doc ?
There are several concerns.
As soon as one wants to use such kind of context help, he has to place the whole html manual hierarchy into doc. But this html stuff is:
a) relatively big in size
b) manual is maintained as a distinct git project, so a combination of two projects in one binary package may result
c) if we combine both the program and the manual in a single source distribution, then the full successful build of such a distribution will require a number of additional tools specific for the manual part (texlive, latex2html, netpbm, etc.)
Implementing context help via html manual has several advantages. A special dedicated help browser not needed, modern web browsers support navigation over html pages much better. And there is no need to maintain simultaneously the manual and the help pages: we generate everything from the single master document.
What about GUI, ideally, the help controls should be intuitive to find and easy to reach with mouse and/or keyboard commands. Perhaps, they should have a consistent look over many different parts of Cinelerra interface. Perhaps some kind of a Help button in menus - in that windows where some kind of menu exists, or a Help button in dialogs could be OK. But Cinelerra GUI is reach. How could look a Help button, for example, inside the patchbay, to call help page for patchbay... I have no idea.
I am unsure if my placement of the Hep command at the bottom of plugin popup menu is appropriate. I took the first place which could easily find, to quickly test the concept, and if successful, demonstrate something to discuss. May be, plugins help also should look somehow differently. Sorry, GUI design is not my strong point.
I will test this soon. My biggest concern is putting all of this in the Cinelerra doc directory because the png files are still changing quite a bit.
cin_5.1-help.diff.gz (2,141 bytes)
|2020-11-24 16:18||sge||New Issue|
|2020-11-24 16:18||sge||File Added: cin_5.1-help.diff.gz|
|2020-11-27 02:41||PhyllisSmith||Assigned To||=> PhyllisSmith|
|2020-11-27 02:41||PhyllisSmith||Status||new => acknowledged|
|2020-11-27 02:41||PhyllisSmith||Note Added: 0004374|
|2020-11-28 05:31||sge||Note Added: 0004379|
|2020-11-28 10:18||Andrea_Paz||Note Added: 0004383|
|2020-11-28 13:11||sge||Note Added: 0004387|
|2020-11-28 22:45||Andrea_Paz||Note Added: 0004389|
|2020-11-29 16:58||sge||Note Added: 0004390|
|2020-12-06 04:56||PhyllisSmith||Note Added: 0004412|
|2020-12-06 15:32||sge||Note Added: 0004413|
|2020-12-06 15:40||sge||Note Added: 0004414|
|2020-12-13 21:57||PhyllisSmith||Note Added: 0004419|
|2020-12-14 00:19||Sam||Note Added: 0004420|
|2020-12-14 13:56||Andrea_Paz||Note Added: 0004421|
|2020-12-14 15:30||PhyllisSmith||Note Added: 0004422|
|2020-12-14 17:29||sge||Note Added: 0004423|
|2020-12-23 20:42||PhyllisSmith||Note Added: 0004432|
|2020-12-23 22:47||Sam||Note Added: 0004433|
|2020-12-24 09:22||Andrea_Paz||Note Added: 0004435|
|2020-12-24 17:03||sge||Note Added: 0004437|
|2021-01-03 14:33||sge||Note Added: 0004448|