View Issue Details

IDProjectCategoryView StatusLast Update
0000540Cinelerra-GG[All Projects] Featurepublic2021-01-03 14:33
Reportersge Assigned ToPhyllisSmith  
PrioritynoneSeverityfeatureReproducibilityN/A
Status acknowledgedResolutionopen 
Product Version 
Target VersionFixed in Version 
Summary0000540: Context help via HTML manual
DescriptionThe small patch attached demonstrates how the HTML form of Cinelerra manual (see BT538) can be used to provide context help with minimal efforts.
Additional InformationPrerequisite: HTML manual (see BT538) deployed in the subdirectory doc of the Cinelerra installation directory, so that if the cin binary is

cinelerra-5.1/bin/cin

then the title page of the manual must be in

cinelerra-5.1/bin/doc/CinelerraGG_Manual/CinelerraGG_Manual.html

If you do not wish to build HTML manual just now by yourself, you can download it from my webserver as

http://nmr.nioch.nsc.ru/CinelerraGG_Manual/CinelerraGG_Manual.tar.gz

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.
TagsNo tags attached.

Activities

sge

sge

2021-01-03 14:33

reporter   ~0004448

@PhyllisSmith
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.
sge

sge

2020-12-24 17:03

reporter   ~0004437

@Andrea_Paz
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.
@PhyllisSmith
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...
Andrea_Paz

Andrea_Paz

2020-12-24 09:22

manager   ~0004435

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

Sam

2020-12-23 22:47

administrator   ~0004433

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

PhyllisSmith

2020-12-23 20:42

manager   ~0004432

@sge
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.

@Sam:
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.

ALL:
- 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).
sge

sge

2020-12-14 17:29

reporter   ~0004423

@Sam
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.
@PhyllisSmith
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.
PhyllisSmith

PhyllisSmith

2020-12-14 15:30

manager   ~0004422

@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.
Andrea_Paz

Andrea_Paz

2020-12-14 13:56

manager   ~0004421

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

Sam

2020-12-14 00:19

administrator   ~0004420

@sge @PhyllisSmith
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.
PhyllisSmith

PhyllisSmith

2020-12-13 21:57

manager   ~0004419

@sge
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
SHBTN4_WARN 0
SHBTN4_RUN_SCRIPT 0

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

sge

2020-12-06 15:40

reporter   ~0004414

@PhyllisSmith
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.
sge

sge

2020-12-06 15:32

reporter   ~0004413

@PhyllisSmith
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.
PhyllisSmith

PhyllisSmith

2020-12-06 04:56

manager   ~0004412

@sge
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.
sge

sge

2020-11-29 16:58

reporter   ~0004390

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

Andrea_Paz

2020-11-28 22:45

manager   ~0004389

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

sge

2020-11-28 13:11

reporter   ~0004387

@Andrea_Paz:
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
cd master
zcat ~/CinelerraGG_Manual.diff.gz | patch -p1
chmod +x rename-pngs translate_manual
./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.
Andrea_Paz

Andrea_Paz

2020-11-28 10:18

manager   ~0004383

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 ?
sge

sge

2020-11-28 05:31

reporter   ~0004379

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

PhyllisSmith

2020-11-27 02:41

manager   ~0004374

@sge
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.
sge

sge

2020-11-24 16:18

reporter  

cin_5.1-help.diff.gz (2,141 bytes)

Issue History

Date Modified Username Field Change
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