 |
Refer to complete implementation of 0000568. Thank you very much ! |
 |
@PhyllisSmith Now you can close this issue in favor of the much more complete context help implementation, see BT568 |
|
|
@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. |
|
|
@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... |
 |
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. |
|
|
@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). |
|
|
@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. |
|
|
@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. |
|
|
@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. |
|
|
@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. |
|
|
@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. |
|
|
@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. |
|
|
@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. |
|
|
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. |
|
|
@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. |
|
|
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. |
|
|
@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. |
|
|
cin_5.1-help.diff.gz (2,141 bytes) |
- Anonymous
