 |
The 07-31 manual now has all of the information on handling Context Help so am closing this BT. In addition, I was able to update code to reference the manual as outlined here by adding a Context Help reference in exportedl.C. |
|
|
@Andrea Thank you for the .txt file. I have proofread it and did some latex formatting. But I eliminated the alternative descriptions in the text for different parameters as I thought it would just lead to problems for us and prevent context help from working correctly. This has been checked into GIT. @sge We have reviewed all of the information presented in this BT to put sections in the Manual and I believe we have it all compacted there where needed (with the exception of the alternative parameters in the translate_manual script). So at the end of the month when the software and manual are updated online, I plan to close this BT unless there are objections. And again, THANKS SO MUCH, it is just wonderful! |
 |
@PhyllisSmith @sge I am attaching a text file as an example. Please review it to correct errors and introduce improvements.
context_help.txt (6,416 bytes) |
|
|
@Andrea_Paz @sge Andrea, if you can work on your documentation idea as much as possible per Georgy's suggestion, I would really appreciate it and would proofread it based on information in this BT. It would be really helpful to have it nicely documented because it is a little hard to read all of this to get the pertinent information. |
 |
@Andrea_Paz First of all, translating CGG manual to HTML requires full-featured latex2html installed. Latex2html itself has many requirements: a working TeX distribution (texlive), Netpbm, GhostScript, dvips, etc. If some of its requirements are not fulfilled, not only CGG manual cannot be translated, any other latex document will be untranslatable also. If one relies on the latex2html as part of its Linux distribution, the guys making distribution are responsible to ensure latex2html functionality. If one has to install latex2html by himself, there are some instructions inside the latex2html source archive how to install and configure it. They are general instructions and apply equally to translation of any document, including CGG manual. Translating CGG manual does not impose any special requirements to latex2html except that it must be at least version 2021.2. Therefore we do not need to document in the CGG manual how to install latex2html, it is either installed out of box, or the installation described elsewhere. We can document the following steps concerning CGG manual. 1) How to checkout the manual. 2) How to produce PDF document from latex source (including invoking makeindex for the Index and Glossary). 3) To produce HTML output, one has to copy (rename) latex2html-init to .latex2html-init (starting with dot). 4) Then invoke translate_manual script. 5) Where to put the HTML output so that CGG context help can find it. 6) May be, some optional adjustment to the latex2html command line. Some variants are given in the comments inside translate_manual script, some are listed here in the Note 0004744. If it is meant to document the conventions how to develop new CGG dialogs with embedded context help and how to document them in the manner compatible with context help, then it is completely different problem, I think, not for the CGG user's manual, but for some future CGG developer's manual, should it arise. |
|
|
@sge Hi, I would like to add the steps to compile the manual in chapter 1 (Installation). It could be useful to those who compile Cinelerra-GG to always have the program (and the manual) as updated as possible. There's already a note in Chapter 1 on how to import the already compiled folder, and then there are your in-depth explanations in Chapter 18. Now that Latex2html is complete, could you give a description of what is needed and how to go about getting the context help? Do you think this is useless information for the manual? |
|
|
Latex2html version 2021.2 released: https://github.com/latex2html/latex2html/releases/tag/v2021.2 It finally contains all the recent modifications necessary to translate CGG manual with glossary, namerefs etc. features. |
|
|
@sge Thanks for the update. I would still like to avoid duplicates so will be checking for numerical digits. |
|
|
@PhyllisSmith Dan Gildea added 'clobbertitles' patch to latex2html. Now, when downloaded from git master, no patching of latex2html is necessary. Now there will be no filename collisions, a sequential digit will be added to such a filename when necessary. If still interested in avoiding section naming duplications, the appearance of <any digit>.html pattern in a filename will indicate such duplication candidate. |
|
|
@sge Oh, that is good to prevent me from making the same mistakes. And I really like the patch name of "clobber". |
|
|
@PhyllisSmith Thank you Phyllis! Here is attached one more patch -- for latex2html. The patched version of latex2html will not generate duplicated HTML filenames under -long_titles any more, even when some sections will have completely identical names. I have already sent this patch to the maintainers of latex2html. latex2html-20210225.clobbertitles.diff.gz (1,330 bytes) |
|
|
@sge 1) News was updated and includes a link to Troubleshoot_Help.html which shows the Context Help section. 2) Also, from the email: "Some phrase about Context Help facility might be added to the list of documentation sources on the web page https://www.cinelerra-gg.org/downloads/#documentation" This was also done and the link is to the left of the HMTL User Manual note in the documentation section. 3) The manual GIT was updated in Installation.tex to inform self-builders of the need to include: https://cinelerra-gg.org/download/images/HTML_Manual-20210531.tgz (substituting correct date) and unpacking to their Cinelerra/bin/doc directory to be included in their built system. This will be in How_build_CINELERRRA_GG_from.html and Notable_Options_Caveats.html initially. I believe that this is complete but I would like to leave this open a little longer as there is so much good information included here. |
|
|
@sge Thanks for the reminder about removing the CinelerraGG_Manual directory before the finel latex2html run. I was not clear, even though in my script I commented out the "rm" commands, I echo the "rm" lines just to remind me to run them manually -- because as you said I did see cache mess things up and not get changed. |
|
|
@PhyllisSmith In my opinion, you should always explicitly remove (or at least rename) the CinelerraGG_Manual directory before the final latex2html run. Latex2html caches its auto-generated images and, if the latex source gets changed in such a way that the number of the generated images, or the images themselves, changes, the old images remaining from the preceding runs can pollute the directory, induce strange error messages and lead to not fully consistent result. Although there are some options foreseen to make latex2html not to use its cache, I would prefer to remove the old directory, to be absolutely sure it won't hurt. |
|
|
@Andrea_Paz Configuration.tex seems OK to me now but I will wait to check it in. It would be beneficial to always have Context Help provide relevant information rather than showing the Contents. So if anyone finds an item that probably should be documented and is not currently, please let us know. If Andrea has time, could you add a quick note on "Export EDL -- this is under the File pulldown and I think it is no longer relevant but I noticed it is in Shortcuts. If I remember correctly, Andrew knows something about it BUT for now, maybe just add to the Loadand save.tex file, something about how it is currently not been kept up to date. It must have been useful at some time. |
|
|
@sge Thank you for all of the explanations provided in answer to MatN. For me, there was no confusion about location of mouse and what Help page came up so I think many users will quickly understand to be sure about where they click the mouse. It is still amazing to me how astute the program is in getting good Context Help. I checked into GIT the modified translate_manual file you provided as I had not removed -show_section_numbers -- always need at least one other person to check work that gets checked in -- otherwise MatN would not have been tripped up by my error. @MatN About "Phyllis makes HTML manual not with this script, but somehow by hand" -- well, I always just log in as root so I made a local copy of translate_manual and modified it to just echo the rm commands, always use a logfile, removed the pdflatex commands, and print out statements to remind me. But I checked into GIT the script that most people will want to use so that it does not get lost. About: "does Latex2html absolutely require that a PDF manual is produced first?" I removed the pdflatex commands from my version of the translate_manual script because I have a separate script to create the pdf manual first. I almost always run pdflatex multiple times while I change some wording and there is no reason to keep creating the HTML version until happy with pdf results. P.S. because it is so true, I got a good laugh out Georgy's line: "(I would even say, it is not obvious for users, in contrast to programmers, what a widget is)." |
|
|
@sge I had it wrong "\index{entry} SMP cpus" ==> "\index{SMP cpus}". Under HW device I had not put index; now I have. Does it seem ok now? Configuration-2.tex (55,605 bytes) |
|
|
@MatN @PhyllisSmith As developers try to translate CGG manual with the translate_manual script, I'd suggest to make it a really working script. The modified script is here in attachment. Most changes are in some comments only. One additional change is to copy latex2html-init to .latex2html-init automatically if .latex2html-init does not yet exist. Dan Gildea has my 'longtitles' patch checked in latex2html git. If you reinstall latex2html from git now (no patching necessary), then you will be able to use arbitrary entitling option (for example, -t 'Cinelerra GG Infinity') while using -long_titles in the same tile. @Andrea_Paz There seems to be some strange \index argument near 'HW device' in the attached Configuration.tex from your note, could you verify it?
translate_manual (1,933 bytes) |
|
|
I realized that in Preferences --> Performance the description of "Cache Transition" and "Use HW device" is missing. Thanks for pointing that out! I tried inserting them, can this be okay? |
|
|
@MatN @PhyllisSmith To the discussion about context help on Performance settings. I was deciding which chapter/section of CGG manual should context help refer to: the Configuration/Performance section, or the Performance/Hardware section. I realized that the Hardware section seems to be unnecessarily complicated for something like 'help' and contains much more information than could be implied under the 'hw device' input field. There is, namely, some information on installation and debugging hardware acceleration libs, etc. Nevertheless, we can very easily rename the help keyword of the 'hw device' widget to refer to the subsection 'Hardware video acceleration' or, alternatively, 'GPU hardware decoding' (or encoding?). Or, a short description of this item can be added to the Configuration chapter of the manual, with a reference to the much more detailed Performance chapter. What would be better, to your mind? On latex2html quirks. I have attached here the patch to latex2html (against latex2html git master branch) which corrects the recently detected bug where -long_titles and -t with the value different from the .tex file name were used. If you reinstall latex2html with this patch applied, then it will be possible to translate CinelerraGG_Manual.tex not with -t 'CinelerraGG_Manual' but, for example, with -t 'Cinelerra GG Infinity' (even with blanks inside), or anything you wish, this will work together with -long_titles now. I have already sent the patch to latex2html maintainers and hope, in will be checked into their git soon. @MatN Yes, latex2html requires to produce a self-consistent PDF output first. It will work also without it, but as latex2html uses the information from various .aux files to produce Contents, various lists (of figures, tables, etc.), bookmarks, crossrefs, etc., its result without the preceding pdflatex runs will be incomplete. Moreover, latex2html itself runs pdflatex on selected excerpts of the document to create images for complicated latex constructs which cannot be converted to plain HTML directly. Such excerpts may require some info from .aux files by themselves, and then their implicit translation will fail. Moreover, latex2html collects info for the Index and Glossary. To ensure their completeness, makeindex has to be run at least once for each of these appendices. latex2html-longtitles.diff.gz (498 bytes) |
 |
@sge, Thank you for your very clear explanation, this makes it very clear how it works. Building it with: latex2html -html_version 4.0,math -use_pdftex -use_dvipng -long_titles 5 -image_type png -nofootnode -split +3 -link 3 -bottom_navigation -local_icons -t 'CinelerraGG_Manual' CinelerraGG_Manual.tex produces the "About" page and all seems to work fine. I think some changes to the manual are needed now that it is used for context-sensitive help, I have only tested very few help pages. For instance, the Performance page , if you put the cursor in the upper part, you indeed get the Performance chapter of the manual, but that lacks the "hw device" explanation. This device is for decoding only. It is described extensively in chapter 19.1 , but I think it should be mentioned here too. A side question: does Latex2html absolutely require that a PDF manual is produced first? It uses the .aux files generated for that, can it not do that itself? There could be more, but the manual seems to work fine. |
|
|
@MatN Open Settings->Preferences->Performance Point with the mouse on the caption 'Background Rendering', press Alt/h. You should get help on background rendering. Point with the mouse on the caption 'Render Farm', press Alt/h. Now you should get help on render farm. Point with the mouse on the small caption 'Cache size', press Alt/h. Now you should get help about the Performance section where this item is actually documented. Point with the mouse on the red caption 'Video:' (with a wrench), press Alt/h. Now you should get help on file formats. This was the intended Context Help behavior in the Preferences dialog. |
|
|
@MatN Now on the unexpected help pages shown after pressing Alt/h in different Preferences tabs. The kernel idea in Context Help is declaration of the proper keyword inside the GUI widget's private data structure. So the widget itself knows his intended help page. The program does not need steadily to calculate where is currently the mouse, the X11 system itself triggers the event in the proper (sub)window owner. Due to this approach filling the whole Context Help environment with the information and maintaining it is now so straightforward. But there is consequence: whose help page will be shown, depends on the positioning of the mouse EXACTLY over the particular widget of interest. And unfortunately, it is not always obvious for the user, where which widget is (I would even say, it is not obvious for users, in contrast to programmers, what a widget is). The Preferences dialog is a very complicated one. Look for example on the Appearance tab: there is a lot of toggles for very different properties: time, colorspace, problems with rendering, indices, presentation of assets in tracks and in Resources window, etc. How should the user figure out, to 'always show next frame' or only sometimes (and when) to show next frame, for example? And in the neighboring 'Clears before toggle': what to clear before what to toggle? Both controls are close to each other in the same window but actually belong to very different (and complicated) topics. This is the uniqueness of the Preferences dialog: almost each widget has assigned its own intended help page. But you may think about one thing while having mouse actually over some other thing, then you can get improper help page on such a request. Settings->Preferences->About Here your problem source is different: the 'About' page is not found on the 1st pass because of extraneous section numbers in Contents. On the 2nd pass (inexact, case insensitive) it could be found, but another section with the word 'about' inside was found earlier. Translate your manual without the -show_section_numbers option to latex2html, and this problem should disappear. Settings->Preferences->Interface If you press Alt/h with the mouse somewhere over an empty space inside the window itself, you get manual page 'Interface'. But if your mouse will be over the tab button entitled 'Interface' - the bar with tabs itself is the property of the enclosing window. The program expects: you wish to get help on the main window with all the tabs itself - and you get help page 'Configuration, Settings and Preferences'. Settings->Preferences->Performance If you press Alt/h with the mouse somewhere over an empty space inside the window itself, you get manual page 'Performance'. But if, while pressing Alt/h, your mouse was accidentally not over an empty space, but over the textual caption 'Background Rendering' (which itself is a distinct GUI widget and has its own context help keyword defined), the system expects: you are interested not simply in the purpose of the Performance tab, but in the particularities of background rendering (otherwise how should you set its preferences if you do not yet know what background rendering is). And you get that help page. May be, one needs firstly to get some experience to learn, how Context Help can be used really efficiently... Otherwise, it is rather straightforward to edit help keywords in Cinelerra code. But it has to be EXACTLY specified, where the mouse cursor was (over which drawing inside a window) while Alt/h was pressed, resulting in an improper help page. |
|
|
@MatN @PhyllisSmith I have reproduced the quirk with 'Link "CinelerraGG_Manual.html" to "index.html" failed: No such file or directory'. Some time ago, when adopting CGG latex manual to latex2html, I included in translate_manual two additional commented out latex2html calls with different sets of options. That time they were not meant as actually working alternatives. Rather they should provide some kind of a memo for developers to consider different possible options yielding slightly differently looking HTML output. So, looking on these comments, after consulting latex2html manpage and some trials, the developer could choose the command giving best looking result. Anything like 'Context Help' was not taken into account that time, it simply did not yet exist at all. But now, although any translation variant should be able to give somehow looking HTML manual, not all variants can yield result which is compatible with the current implementation of Context Help. Now on the topic. -html_version 4.0,math 4.0 is perhaps mandatory. To my feeling, HTML5 is not (yet) implemented in the latex2html translator as complete as HTML4 is. If you remove 'math', then HTML math extension will not be used, and much more small images will have to be generated by the translator for various subscripts, superscripts, simple arithmetics etc. The things should still work but the document will contain many unnecessary images when translated without 'math'. -use_pdftex is a must. However, as this option actually is the default, you can just safely remove it, nothing will change. -use_dvipng / -nouse_dvipng These are equivalent alternatives. The output will look only slightly differently, you can choose best looking one, both will work. -use_dvipng is the default. But for debugging (if generation of images while translation goes wrong for unknown reason), -nouse_dvipng can give more diagnostics. -image_type (gif/png/svg) You can try any option, all should work. But different browsers may support these image formats differently. For example, some do not understand svg, some could have troubles with transparency in PNG, etc. -long_titles 5 With this option, HTML file names will consist of words taken from section names. Without it, all HTML files fill be named 'node<ddd>.html' where <ddd> are sequential numbers. Both will work, but in ContextManual.pl you will have to actualize the filenames which contain the actual Contents and Index. -split +3 -link 3 These control segmenting of the whole HTML hierarchy and the depth of generated links to subsections. You can try different, but here, the depth 3 seems optimal. >3 will fractionize the document on too small pieces, <3 on too large ones, so the manual will be inconvenient to read. -split 0 will not segment the document at all and produce one huge HTML file. -nofootnode With this options, footnotes are placed at the bottom of that HTML page in which they appear. Without it, one special HTML file fill be created and all the footnotes collected in this extra file. For CGG manual this would be definitely undesired result. -numbered_footnotes Footnotes can be displayed either with a superscripted number, or as a general link icon without number. The second may be desired in the cases where different HTML pages are intended to be used independently, so that the footnote numbers become out of order. The default depends on the documentclass (for the used in CGG class memoir: numbered). Both should work in Context help equally well. -show_section_numbers The section numbers (same as in PDF) will be prepended to the section names, figure captions, etc. The look of the result will be different, Your preferences may vary. This format of section names will also appear in Contents.html, and for Context Help it was not foreseen. Although Context Help may still work with this form of manual, it can be not as efficient and reliable as without numbers. If we decide later to use the numbers, perhaps ContextManual.pl will have to be adjusted to this format. -bottom_navigation is just a styling for the created HTML pages, to place the Next/Up/Previous links not only on top, but additionally at the bottom of HTML pages. For Context Help it does not matter. -local_icons The icons for the Next/Up/Previous, and some additional links will be copied into the document hierarchy. For a standalone document (as used for Context Help) this is a requirement. For a document on a webserver such icons might be taken from some central place on the server. -t 'CinelerraGG_Manual' This is set into the <TITLE> HTML tag, but additionally, if -long_titles is used, seems to become the name of the HTML file containing the titlepage - that file which is then linked to index.html. If the value of this option differs from the name of the master .tex file, and -long_titles is used, then you get that error message "Link failed..." you report. This is a latex2html bug. Don't bother, set -t to the master .tex file name for now. This bug in latex2htrml will be fixed later, but it will take some time. |
|
|
@MatN The About page should get you to: About.html (I tried again in different spots and except for the buttons on the bottom, it always did). BUT why do you have "numbers" on your html files? as in "1_3_4"? I had removed the numbers from section names when I build the manual file:///tmp/.mount_cin-e0MHc1wo/usr/bin/doc/CinelerraGG_Manual/1_3_4_Notes_about_Buil I think the numbers are messing things up. Check the latex2html line in my previous note and see what is different (hopefully, you will avoid the mistakes I made already today). |
|
|
I think I got building the AppImage inclusive alt-h help mostly right. I've attached my current bld_appimage.sh . The remaining build problem is I still get the: Error (Link): Link "CinelerraGG_Manual.html" to "index.html" failed: No such file or directory even though both Index.html and index.html are present. Regarding the about page, if I go to Settings->Preferences->About, alt-h will get me to: file:///tmp/.mount_cin-e0MHc1wo/usr/bin/doc/CinelerraGG_Manual/1_3_4_Notes_about_Building_.html Not sure that is right, but there might no be a better one. Phyllis? Also I noticed on the Settings->Preferences->Interface, alt-h gets me to the general Settings page, not that section for the Interface. Something similar for the Performance tab, it gives me a background rendering help page, but there is more on that tab. These could be limitations on how the manual is currently structured. In any case, it is much better that no alt-h ! bld_appimage-2.sh (2,380 bytes) |
|
|
@sge Of course, you are right and the -nofootnode is actually on the line I quoted to MatN -- not sure why I did not see it so now I know nothing has to be changed after all. |
|
|
@MatN As I introduced context help keywords in Cinelerra (there was a lot) sometimes I was in doubt which HTML page seems most relevant. Moreover, I could make mistakes. If some context help page looks like a mistake, please report: 1. Which GUI object triggers the wrong help page? How to reproduce? Please identify it as exactly as possible, and how to come to this window, if not obvious. 2. Which HTML page is actually shown on context help (copy-paste the URL)? 3. Which other HTML page (exact filename please), to your mind, should be shown instead? @PhyllisSmith -nofootnode must remain in command line. Otherwise latex2html will collect all the footnotes of all HTML pages together in one united page with footnotes only. This behavior can be desirable in some sutiations but in our case it is definitely not what we want. If -numbered_footnotes disappears, then footnotes will be marked not by the corresponding digits but by small diamond-shaped icons. Such footnotes can be desired, for example, if HTML pages of a multipage document are intended to be used independently from each others, where footnote numbers become out of order. |
|
|
@MatN About: "but the help page I get at the "about" page looks strange." For me, the About help page is correct. ----------------------------------------------------------- FYI: Below is the actual line I use to create the manual used online because I always want to see the "logfile": latex2html -html_version 4.0,math -use_pdftex -nouse_dvipng -long_titles 5 -image_type gif -nofootnode -numbered_footnotes -split +3 -link 3 -bottom_navigation -local_icons -t 'CinelerraGG_Manual' CinelerraGG_Manual.tex |& tee logfile |
|
|
I am using .latex2html-init and the ext4 filesystem. Index.html only appears when a) using long titles, and b) the latex2html -t option is set to "'Cinelerra-GG Manual" . I rebuilt with the latest git updated for CinGG and manual, and get an AppImage which includes the help. Of course it is then bigger, 135 MByte instead of 78M, and therefore CinGG loads slower, but it really works nice. I think i is a big improvement. I have not done much help testing, but the help page I get at the "about" page looks strange. |
|
|
There is now the HTML version of the manual as a tgz, approximately how it looked on 20210331, at https://cinelerra-gg.org/download/images/HTML_Manual-20210331.tgz If someone has a better name suggestion or where to put it, let me know. Also, checked into the code source GIT, a couple of minor changes. |
|
|
@MatN Your latex2html and perl are perhaps OK. Absence of .latex2html-init could result in failed translation of some HTML pages, most likely of the titlepage, CinelerraGG_Manual.html. This might be the reason that it could not be linked to index.html in your case. When using -long_titles, two 'index' files are created, but they are two different files. Index.html (capitalized 'I') is the "Index" section of the manual. index.html (small 'i') is a copy (or link) of CinelerraGG_Manual.html (the titlepage). When translating manual with -long_titles in some Windows'ish filesystem (NTFS, FAT32, etc.) with case insensitive filenames, one of these 'index' files will unavoidably overwrite the other. The other warnings from latex2html you report are OK, the translator simply lists LaTeX packages and commands which it does not know. Unknown commands will be either ignored, or included as a generated image, it is OK as long as the result is acceptable. |
|
|
1. I used the latest latex2html from github, unmodified. The make, make test, make check and make install all seemed to work fine, and it worked after the install when called from any directory, so I did not add the link you specified in the "additional information" of BT538. 2. I forgot about renaming latex2html-init, that affects all .html files, makes them look a little bit worse. 3. My Perl version is 5.26.1, system is Mint XFCE 19.3. 4. With "-long_titles 5" there is Contents.html, index.html, and Glossary.html. Without "long titles" only index.html appears. 5. I get some warnings at the end of the latex2html build, see below. Two jump out for me: - ? brace missing for \ - Link "CinelerraGG_Manual.html" to "index.html" failed: No such file or directory at /usr/local/bin/latex2html This last one only appears if building with "-long_titles" , and the index file does exist and works. === latex2html build warnings at end === No implementation found for style `cmap' No implementation found for style `substitutefont' No implementation found for style `mathdesign' No implementation found for style `mathtools' No implementation found for style `mathtext' No implementation found for style `caption' No implementation found for style `hhline' No implementation found for style `pdflscape' No implementation found for style `calc' No implementation found for style `bigstrut' No implementation found for style `indentfirst' No implementation found for style `gensymb' No implementation found for style `tikz' No implementation found for style `geometry' No implementation found for style `enumitem' No implementation found for style `scrextend' No implementation found for style `eso-pic' redefining command \hyperref redefining command \nomname redefining command \arraystretch *** wrap_cmd_hyperref not defined, cannot wrap \hyperref No number for "Themousecursor,abovethegreencolored“playforward”transportbutton,isonthetimebar.Furthertotherightweseethered;SPMquot;indicatorline;SPMquot;." No number for "Infowindowswiththe“Detail”box" No number for "Highlight,thenclick“NewMediaorClips”.“Modifyfolder”canbeusedtochangethenameofafolder.“Deletefolder”inthepopupcanbeusedtodeleteafolder." No number for "The“master”Mediafolder" Unknown math command: \underscorezero , image needed. Unknown math command: \underscoreequations , image needed. Unknown math command: \implies , image needed. Unknown math command: \degree , image needed. ? brace missing for \ Error (Link): Link "CinelerraGG_Manual.html" to "index.html" failed: No such file or directory at /usr/local/bin/latex2html line 878. Unknown commands: HUGE IeC addappheadtotoc bottomrule chapternumberline hypersetup midrule printchaptername printpartname printtoctitle righthyphenmin setparaheadstyle setsecheadstyle setsubparaheadstyle setsubsecheadstyle setsubsubsecheadstyle subitem thinmuskip tmspace toprule usetikzlibrary Done. ============ |
|
|
@MatN As recommended by SGE, I will be generating a tgz file containing the html manual that coordinates with the latest release at the time so people who do their own builds can download that and include it easily. But I have not gotten it done yet. Andrea has incorporated most of Georgy's documentation into the manual and I am adding the rest. Sorry for the delay. |
|
|
@MatN The tricks with translation of manual are dealt with in BT538: https://www.cinelerra-gg.org/bugtracker/view.php?id=538 In short: 1. You absolutely need latex2html installed and working. Moreover, neither latex2html from your Linux distribution, nor some release of latex2html. Currently, the development (master) branch of latex2html has to be fetched from github, as the last release does not yet contain all the modifications necessary for the complete translation of Cinelerra manual. 2. When you fetch manual sources from git, there is file 'latex2html-init'. It must be manually renamed into '.latex2html-init', starting with dot. 3. The translate_manual script is only an example. As far as I know, Phyllis makes HTML manual not with this script, but somehow by hands. Adjusting such a script can be considered, so that .latex2html-init be created automatically, and the set of options to latex2html be matching the actual needs, but this is not yet done in completeness. 4. After translation, one should at least take a look in the resulting CinelerraGG_Manual directory, if the expected contents appears, just like after compiling a program one checks if any executable file has been created. 5. You are allowed to adjust latex2html options according to your needs. For example, you can remove '-long_titles 5', then you will have something like 'node6.html' instead of 'Contents.html', and, let's say, 'node253.html' instead 'Index.html'. But after you figure out, how the actual Contents and Index are called, you can modify the corresponding definitions in the perl script ContextManual.pl, and the context help system should work with such filenames equally good. |
|
|
Ah, maybe I found it. Because I wanted to use PNG images, I used the second latex2html line in the translate_manual script. I see now there is a difference apart from the images: "-long_titles 5 " is missing. Has that influence on whether Content is generated or not? Because the content is present in the PDF. Iĺl try later today. |
|
|
@sge, No, I should have said. The file doesn't exist. I presume it should be generated via the translate_manual script, and it is not. That is why I though there might be something missing from the git. Is the git of the manual up to date for this html directory generation? And many thanks for the work you do on this, it is a major advance IMHO. |
|
|
@MatN Is there actually the Contents.html file under the spefied path? If that file really does not exist, then Alt/h cannot work without it. If it does exist, then strange... |
|
|
I have tested a complete AppImage build from git of both manual and CinGG. The AppImage works, but as soon as I try alt-h, I get an error msg (AppImage started from terminal) that a file is missing: Cannot open <snip> /CinelerraGG_Manual/Contents.html: No such file or directory at /tmp/.mount_cin-b13mOL8V/usr/bin/doc/ContextManual.pl line 132. Is there something missing from the git? I used a modified bld_appimage.sh (attached), but that should not affect this. bld_appimage.sh (2,164 bytes) |
|
|
@sge I understand your last note. Before I checked in your code to GIT, I did scroll through the 6000+ diff file to get a feel for implementation details (plus read your detailed initial description here). It is necessary to at least have one other person review what can be understood anything that gets checked in just to try to make sure no obvious errors are present. I am still just so impressed how well you added the Context Help to make it easy to maintain this code as future changes arise. And was amazed when you fixed the extraneous comma in gwindowgui.C "Hard Edges" ! Andrea has incorporated your suggested Documentation notes into sections of the manual and so we are in the process of reviewing them. He also moved cdripper to the right place and I would like to figure out (without any help) how to/if fix Context_Help.pl to accommodate that so I better understand for the future. Also, possibly over time fix the other issues with names as described in Context_Help.pl. It will take me some time. Still more later. |
|
|
@PhyllisSmith It is not uncommon in Linux distributions to prepare a binary package from more than a single source branch. I mean, we can continue having separate git trees for the CinelerraGG source and for the Latex Manual source, but additionally provide via the website translated HTML manual packages (in .tgz form) somehow synchronized with the corresponding AppImage or source packages of CGG itself (for example, having similar date coded in the .tgz archive name). Then software packagers, or peoples who like to compile software by themselves can fetch CGG, compile it from source, then fetch HTML manual archive of the actual date, unpack it and move to the proper place. Or even fetch Latex manual and translate it too, when they like to do so. This will work just as easy as you put HTML manual into AppImage, no problem. It is absolutely unnecessary to check in the whole HTML manual into CGG git tree. What is necessary now: when editing manual only, still keep in mind what should and what should not be callable from CGG via Alt/h, and under which GUI element's context. And after possible changes in sectioning, test, if the desired sections are actually callable or not. So, the manual and CGG itself belong now to each other more tightly than before the first appearance of Alt/h. |
|
|
@sge Checked into GIT all of the files exactly as you provided -- wanted to make sure they were in a safe place. (I was very careful, but I still need to verify that I did not make any mistakes). I did not check into the doc directory, the actual HTML manual (yet) so anyone who creates their own build will have to (still) copy the html manual their manually because I am still digesting the information you provided on this. You are right that it is not an issue for AppImage as it is so easy for me just to include it when creating the AppImage, but I am concerned about the known and unknown builders out there. Currently it looks like it will have to be checked in, but it is just so big. More later !! |
|
|
@fary54 I tried Firefox, Seamonkey, Konqueror, Google Chrome but did not find any command line option to open the given URL in the same window/tab. There are only options to explicitly open in a new window, but not the reverse. So please configure your browser beforehand for the needed behavior. |
 |
@ PhyllisSmith Ok it's perfect, we will see when using the software and according to the feedback of all users. Thank you for your quick response. |
|
|
@fary54 Andrea or I will include this in the Manual as you suggest. I agree with sge that it is helpful to have multiple tabs available -- especially for newer users who have to refer to different sections at the same time. I think that you are only noticing the abundance of multiple tabs is because, like me, you are "testing" and just keep trying out a lot of variations. |
|
|
@sge First of all a big thank you for your quick and really complete answer. I am not a programmer and it's a pity because I can only bring up the practical side of the user to help you. I understand your opinion about the opening of several tabs and I did not know the possibility of configuring the browser. If the possibility to open the help only in one tab is not possible from Cinelerra, it might be interesting to insert your solution in the Cinelerra help guide. What do you think about it? |
|
|
@fary54 I, personally, would prefer opening Alt/h links in new tabs and manually close them when not needed. It is quite often handy to be able to switch between several tabs with different manual pages inside. Likewise there are ways to get links opened in same tab, as you prefer. 1) Use another browser which has such a mode configurable (example for Seamonkey): export CIN_BROWSER=seamonkey cin In seamonkey browser go to Edit -> Preferences... -> Browser -> Link Behavior -> Links from other applications Set the option "Open links passed from other applications in:" to the value "The current tab/window" And you get it! 2) Hack a default browser if you know how to hack it (example for Firefox): Start Firefox and open the pseudo-URL: about:config There comes a warning like "I'll be careful, I promise!", acknowledge it. Then comes a very long list with lots of undecipherable variable names. Scroll it down and find variable with the name "browser.link.open_newwindow.override.external". By default it has value: -1, which means: use value of the more general variable "browser.link.open_newwindow". Place mouse cursor over "browser.link.open_newwindow.override.external", press right button and select from the popup menu "Modify". The value becomes editable. Set it to 1, and you get new links from external apps opened in same tab. If you set the variable "browser.link.open_newwindow" instead, you get this behavior not only for external, but also for all links which otherwise would be opened in new tabs or new windows. The possible values of both variables are: 1: open in the current window and tab 2: open in the new window 3 (default): open in the new tab, current window May be other browsers (Google Chrome? Konqueror?) also can be configured or hacked, don't ask me - I do not know how to hack them. |
|
|
Incredible It's very simple but when you try it you realize that it's indispensable. Congratulations for the idea and the work done. PS: Personally, the only small reproach I can make is that each time you press the "ALT+h" key, it opens a new tab in the browser. Quickly, we find ourselves with several dozen tabs open. Is it possible to remedy this by replacing only the content of the active tab ? and it would be perfect. |
 |
@PhyllisSmith You are great. Thank you so much for the AppImage! On UbuntuStudio 16.04 LTS it works very fine. @sge You did an amazing work! I need to take a few of time to read carefully what you wrote in the "Additional information" section. |
|
|
@IgorBeg There is an AppImage for users to test for older distros now. It is at: https://cinelerra-gg.org/download/images/cin_for_older_distros.AppImage It works on older and will also work on newer distros, if you have multiple computers/partitions at different levels. |
 |
That's some great news. :-) "For now, Cinelerra context help is not localized at all. We have no Cinelerra manual in any language except English anyway. But even should we get the manual translated to other languages, I think, the context help keywords must remain unlocalized literal string constants. Firstly, because the set of languages known to Cinelerra itself is not the same as the set of languages the manual will be translated to. If some "translated keyword" is fed to the help system, while the manual in this language does not exist, keyword matching cannot succeed. Secondly, such a help localization with the translation of all keywords can be done and then maintained much easier and much more reliably inside the ContextManual.pl script rather than in the Cinelerra binary, IMHO." I have a subscription to Deepl.com. Deepl.com has its own API. So we would have the possibility to translate the manual automatically into other languages. I am not a programmer, so unfortunately I can't write code to do this, so help from a programmer would be needed. |
|
|
@sge OK, still having way too much fun testing here and did not get the older distros' appimage ready yet. I want to get comfortable enough to check it into GIT as soon as possible. P.S. also have to finish reading above. |
|
|
There is an AppImage for users to test for newer distros (I will create one for older distros tomorrow after I fix my mistake first). It is at: https://cinelerra-gg.org/download/images/cin_for_newer_distros.AppImage It is great to test !! Please report any problems. |
|
|
@sge This was so exciting that I just had to try it before I even read all of the related information -- as soon as I got to "this is sufficient" I was done compiling !! and now I am having a lot of fun testing. Surprised about having to use "alt-h" instead of "h" since we have been saving that character just for this purpose, but it is just wonderful. More updates as I gain some more testing and finish reading this BT. |
|
|
cin-help.diff.gz (35,798 bytes) |
- Anonymous
