Re: Using dynamic text in manuals: yes or no?
Le 18/09/2023 à 22:13, Dan a écrit : Attached to this e-mail is a showcase file (chapter 2 of Tutorial, current version in master branch), so that everyone can have a look and tinker with it. This example already displays some of the benefits I pointed out previously, namely automatic update of strings in UI (see Text Properties in attached file). This is nice indeed. Some limits should be placed to the usage of info insets, though, as the example makes clear. *Localized GUI strings*, is the exact string in souce code, metacharacters included (&, |, [[context]]); plus, the string may not be unique either. So this should be used with caution + DOs: for unique and seldom used/changed strings such as names of manuals, template or example files. + DONTs: I would never use this, say, for environment names or button names (find & replace, for instance). If there was a way to browse all strings in the info inset dialog, with a search fields, it might be easier. Some things to note: - When using info insets, spaces between words are normal, instead of non-breaking, which is the usual in the docs for menu names and the like. Isn't it the opposite? It is the reason IMO why info insets are not used more in documentation, they do not break on screen and this does not look good. Having insets that can break on screen has been on some TODO list forever (so called three-parts-insets, or something like that). I think that I know how to do it, by using a mechanism similar to addToMathRow() for math insets with allows to linearize macros in equations. But I have no idea about when this could be implemented. And of course this creates practical issues about how to do it right (in terms of display mainly). - Not all references to menus are paired with a function in LyX, for instance File > Export. We could add an info type "submenu", this wold not be difficult (but it is a format change, of course) - The actual language the info insets are displayed in is the UI's, not the document's. This is definitely a drawback for languages with limited translation support. But these languages will have the same issue in the real UI, right? So it is faithful to what the user gets. - If a localized GUI string is not found or is not yet translated, it is displayed in English; therefore there is no danger of leaving blank text in place of info insets. Right. Thanks for investigating that. JMarc -- lyx-docs mailing list lyx-docs@lists.lyx.org http://lists.lyx.org/mailman/listinfo/lyx-docs
Re: Using dynamic text in manuals: yes or no?
> On 9/16/23 15:35, Dan wrote: > >> Hello, >> >> I am currently finishing the translation of the Tutorial manual, and I am >> realizing there are quite a few bits that could benefit from using dynamic >> text fields (so-called infoInsets: Insert > Field), thus preventing minor >> changes in the source code or UI strings to affect the coherence of the >> Docs; just as we already do with keyboard shortcuts or function icons. >> >> I am thinking of: >> - Names of example or template files, which are seldom used and, if so, >> just in a particular manual. For example "Example (raw)" in Tutorial. >> - Names of the manuals of the documentation (are translatable to show them >> in Help menu). >> - Location of specific features or functions in the menus: File > New, >> Document > View, Edit > Undo and the like. >> > > That sounds like a very good idea to me. The manuals also double as examples: > You can see from them how to do certain things in LyX. Info insets aren't as > useful to most users, but they might be, so using them shows the user that > this option exists. > > Riki > Attached to this e-mail is a showcase file (chapter 2 of Tutorial, current version in master branch), so that everyone can have a look and tinker with it. This example already displays some of the benefits I pointed out previously, namely automatic update of strings in UI (see Text Properties in attached file). Some limits should be placed to the usage of info insets, though, as the example makes clear. *Localized GUI strings*, is the exact string in souce code, metacharacters included (&, |, [[context]]); plus, the string may not be unique either. So this should be used with caution + DOs: for unique and seldom used/changed strings such as names of manuals, template or example files. + DONTs: I would never use this, say, for environment names or button names (find & replace, for instance). Some things to note: - When using info insets, spaces between words are normal, instead of non-breaking, which is the usual in the docs for menu names and the like. - Not all references to menus are paired with a function in LyX, for instance File > Export. - The actual language the info insets are displayed in is the UI's, not the document's. This is definitely a drawback for languages with limited translation support. - If a localized GUI string is not found or is not yet translated, it is displayed in English; therefore there is no danger of leaving blank text in place of info insets. Daniel. -- Enviat amb Tutanota. Tutorial-with-dynamic-text.lyx Description: application/lyx -- lyx-docs mailing list lyx-docs@lists.lyx.org http://lists.lyx.org/mailman/listinfo/lyx-docs
Re: Using dynamic text in manuals: yes or no?
On 9/16/23 15:35, Dan wrote: Hello, I am currently finishing the translation of the Tutorial manual, and I am realizing there are quite a few bits that could benefit from using dynamic text fields (so-called infoInsets: Insert > Field), thus preventing minor changes in the source code or UI strings to affect the coherence of the Docs; just as we already do with keyboard shortcuts or function icons. I am thinking of: - Names of example or template files, which are seldom used and, if so, just in a particular manual. For example "Example (raw)" in Tutorial. - Names of the manuals of the documentation (are translatable to show them in Help menu). - Location of specific features or functions in the menus: File > New, Document > View, Edit > Undo and the like. What do you think of this? As I am updating the translation of the UI as well, I find myself searching the manuals with ongoing translation for very small bits of information that have changed, such as the ones listed above. That sounds like a very good idea to me. The manuals also double as examples: You can see from them how to do certain things in LyX. Info insets aren't as useful to most users, but they might be, so using them shows the user that this option exists. Riki -- lyx-docs mailing list lyx-docs@lists.lyx.org http://lists.lyx.org/mailman/listinfo/lyx-docs
