RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
Just to clarify that I was suggesting three completely different things: One first thing was better support of internationalization for *Manuals*, in that context I was speaking about node name translation for presentation to user (there should remain a node true name that should remain the same whatever the translation. Ok, sorry if I misunderstood the rationale for the menu entries. One second thing was internationalisation for *DocStrings*, in that context I was suggesting that docstring could contain some link to some manual variable or function description, so switching the Help language based on configured locale would just mean switching to the correct manual translation. BTW, replacing docstring by jump to manual is basically what calc already does, with its h f and h k commands. However it does it in a language dependent way because it does not use the position within the node (call it PWTN) in the command/variable index --- maybe the reason for such an implementation is that when this feature was made available in calc,, info was not supporting so well PWTN --- but instead uses only the node pointer, and then seaches some string in the node to find the position. One third thing is that even plain docstring format itself is language dependant. Only for that third item I was suggesting that a better format for docstrings would be some sort of texinfo-light (I think that texinfmt.el already support some lighter texinfo and could be some starting point for adding such a feature). So in a nutshell the evolved docstring would contain some header indicating - is that legacy format - is that texinfo-light format - do we have a pointer to some manual to be used instead when available and sought for at the configured locale location --- note that the pointer needs only to indentify the manual itself, the variable or function name is already known what you do C-h f or C-h k. Vincent. Date: Mon, 1 Sep 2014 21:53:55 + From: k...@freefriends.org To: vincent@hotmail.fr; 18...@debbugs.gnu.org; bug-texinfo@gnu.org Subject: RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation' use exactly the same node names whatever the language, so that the same link can be used, and when the manual is compiled to multifile HTML, you have the same file tree whatever the language. Seems Currently the usual practice is that a translated document is just another document with some -xx ending in the base name (where xx refers to the language, e.g. fr for French). True. In my opinion an alternative method would be that translated document should rather bare exactly the same name but just be in a language specific directory named xx, with some fall backs to another language No question that that is a well-known alternative approach. * Translated node name: true node name. Some description @node true node name and the viewer is supposed to show only Translated node name. As Gavin says, that is not correct. Both parts of the node name are intended to be shown. The existing use of this feature is to make short menu item abbreviations, e.g., for the sake of completion or just ease of reading. For example, in the Texinfo manual, the HTML Cross References section has a @menu like this: @menu * Link Basics: HTML Xref Link Basics. * Node Expansion: HTML Xref Node Name Expansion. .. Whatever such a hypothetical texinfo-light needs to do, fine. We should think about that separately. It need not affect what Texinfo does. Seems like two very different cases to me. Let's not try to shoehorn existing Texinfo features into things that are far outside their intent and practice. A discussion of such a texinfo-light (not a name I would advocate, either) should presumably take place on emacs-devel, not in a debian bug for Texinfo. k
RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
Answers inserted below... Date: Sun, 31 Aug 2014 23:37:06 +0100 Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation' From: gavinsmith0...@gmail.com To: vincent@hotmail.fr CC: 18...@debbugs.gnu.org; bug-texinfo@gnu.org (adding bug-texinfo) On Fri, Aug 22, 2014 at 11:04 PM, Vincent Belaïche vincent@hotmail.fr wrote: Finally, as an EMACS user, it would be more important to me * if docstring could be written in a sort of texinfo-light format (when you create a package or anything you first do docstring, and then you port this to a manual (so having some texinfo-light format from the beginning would reduce the effort) It might be worth asking on emacs-devel about this to see if anyone wants to implement it or has ideas about how it could work. Concerning the info format, what sort of problem I also see --- still in relation to i18n --- is that one should be able to use exactly the same node names whatever the language, so that the same link can be used, and when the manual is compiled to multifile HTML, you have the same file tree whatever the language. Seems like a good idea to me. Would help for links between manuals and for finding pages in other languages. Are there any guidelines about how to translate Texinfo documents? Currently the usual practice is that a translated document is just another document with some -xx ending in the base name (where xx refers to the language, e.g. fr for French). In my opinion an alternative method would be that translated document should rather bare exactly the same name but just be in a language specific directory named xx, with some fall backs to another language (meaning ../oo, where oo refers to the other language) when manual does not exists. I think that the alternative method is closer to what people usually do for Web sites, in which each language is its own tree replica (file/directory names are same, but only file contents differ). What I am meaning is that using the same node names should not imply that when the final user is reading a manual written in non-English he/she has to see the real node names unless he/she copy to clipboard the node address, one should be able to specify along with the node name a node local name to be presented by the viewer Having translated node names isn't as important because there would be translated headers in the contents of files/nodes saying what section we're in. The main use would be the status bar in a browser giving the current node, and pointers or references to other nodes. I understand it is not ideal to read a cross-reference in another language. Maybe anchors with translated node names could be used instead? That would work for everything (cross-references, pointers) apart from the node name that is displayed in a status bar. Maybe makeinfo would have to be modified to recognize that a menu in a node using anchor names is referring to the child nodes properly. Menus are precisely the only place where you don't need any change in Texinfo, as you can do: * Translated node name: true node name. Some description @node true node name and the viewer is supposed to show only Translated node name. What I was meaning is that the viewer should be configurable to show either the node path with translated names or true names. In the case of nodes that are not referred by any menu, like the top node, or node accessed only by cross reference, there aren't currently any provision in Texinfo to povide a node name translation. That could be some command @localenodename to give that translation inside the node. Vincent.
Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
On Mon, Sep 1, 2014 at 8:40 PM, Vincent Belaïche vincent@hotmail.fr wrote: Having translated node names isn't as important because there would be translated headers in the contents of files/nodes saying what section we're in. The main use would be the status bar in a browser giving the current node, and pointers or references to other nodes. I understand it is not ideal to read a cross-reference in another language. Maybe anchors with translated node names could be used instead? That would work for everything (cross-references, pointers) apart from the node name that is displayed in a status bar. Maybe makeinfo would have to be modified to recognize that a menu in a node using anchor names is referring to the child nodes properly. Menus are precisely the only place where you don't need any change in Texinfo, as you can do: * Translated node name: true node name. Some description @node true node name and the viewer is supposed to show only Translated node name. I can imagine cases where a menu label is something other than the node name, for example if the document author wants to give a more extended description of what the node is about. Anyway, names of targets are not usually hidden (in the standalone Info browser, at least). What I was meaning is that the viewer should be configurable to show either the node path with translated names or true names. In the case of nodes that are not referred by any menu, like the top node, or node accessed only by cross reference, there aren't currently any provision in Texinfo to povide a node name translation. That could be some command @localenodename to give that translation inside the node. Something like this could be done by treating an anchor as a synonym for a node if it refers to byte 0 of the node. If someone selected or followed a reference to such an anchor, its name could be displayed instead of the node. There would still be the problem of how makeinfo would do implicit pointer creation with the right node names.
RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
use exactly the same node names whatever the language, so that the same link can be used, and when the manual is compiled to multifile HTML, you have the same file tree whatever the language. Seems Currently the usual practice is that a translated document is just another document with some -xx ending in the base name (where xx refers to the language, e.g. fr for French). True. In my opinion an alternative method would be that translated document should rather bare exactly the same name but just be in a language specific directory named xx, with some fall backs to another language No question that that is a well-known alternative approach. * Translated node name: true node name. Some description @node true node name and the viewer is supposed to show only Translated node name. As Gavin says, that is not correct. Both parts of the node name are intended to be shown. The existing use of this feature is to make short menu item abbreviations, e.g., for the sake of completion or just ease of reading. For example, in the Texinfo manual, the HTML Cross References section has a @menu like this: @menu * Link Basics: HTML Xref Link Basics. * Node Expansion:HTML Xref Node Name Expansion. .. Whatever such a hypothetical texinfo-light needs to do, fine. We should think about that separately. It need not affect what Texinfo does. Seems like two very different cases to me. Let's not try to shoehorn existing Texinfo features into things that are far outside their intent and practice. A discussion of such a texinfo-light (not a name I would advocate, either) should presumably take place on emacs-devel, not in a debian bug for Texinfo. k
Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
(adding bug-texinfo) On Fri, Aug 22, 2014 at 11:04 PM, Vincent Belaïche vincent@hotmail.fr wrote: Finally, as an EMACS user, it would be more important to me * if docstring could be written in a sort of texinfo-light format (when you create a package or anything you first do docstring, and then you port this to a manual (so having some texinfo-light format from the beginning would reduce the effort) It might be worth asking on emacs-devel about this to see if anyone wants to implement it or has ideas about how it could work. Concerning the info format, what sort of problem I also see --- still in relation to i18n --- is that one should be able to use exactly the same node names whatever the language, so that the same link can be used, and when the manual is compiled to multifile HTML, you have the same file tree whatever the language. Seems like a good idea to me. Would help for links between manuals and for finding pages in other languages. Are there any guidelines about how to translate Texinfo documents? What I am meaning is that using the same node names should not imply that when the final user is reading a manual written in non-English he/she has to see the real node names unless he/she copy to clipboard the node address, one should be able to specify along with the node name a node local name to be presented by the viewer Having translated node names isn't as important because there would be translated headers in the contents of files/nodes saying what section we're in. The main use would be the status bar in a browser giving the current node, and pointers or references to other nodes. I understand it is not ideal to read a cross-reference in another language. Maybe anchors with translated node names could be used instead? That would work for everything (cross-references, pointers) apart from the node name that is displayed in a status bar. Maybe makeinfo would have to be modified to recognize that a menu in a node using anchor names is referring to the child nodes properly.
Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
From: Vincent Belaïche vincent@hotmail.fr Cc: 18...@debbugs.gnu.org, Texinfo bug-texinfo@gnu.org Date: Fri, 22 Aug 2014 15:01:43 +0200 - texi2any must collapse multiple blanks in node names *everywhere*, but it is still allowed to break and indent a node name containing a blank accross a line in the case of a note. - info viewer must handle node name split accross lines, but it does not need to make multiblank reduction in other-cases Now, if the above is agreable, then in the case of our problem this would imply that when texi2any meets that kind of menu entry * NODENAME:: SOME TITLE It must convert it to within the info file: * NODENAME: NODE NAME. SOME TITLE Or it should remove the extra blanks, i.e. produce this: * NODE NAME:: SOME TITLE Or it could emit a warning, or even error out. IOW, I see no reason to silently tolerate such cases. They are surely unintended. Eli: 1) do you agree on my re-caping and suggestion ? Almost, see above. 2) do you think that all the same, robustifying the info viewer in the case of menu entry has some benefit --- after all this allows: 2.1) to cope with job done by earlier versions of makeinfo in this corner case 2.2) to have very slightly smaller info file still in this corner case I'm on the fence about this.
RE: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation'
Hello Eli, Gavin, Patice, Karl. Looping also through Patrice Dumas and Karl Berry and texinfo-bug list. Useful links: http://savannah.gnu.org/bugs/?43045 http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18308 Answers comments below: Date: Fri, 22 Aug 2014 09:36:14 +0300 From: e...@gnu.org Subject: Re: bug#18308: 24.4.50; Info viewer cannot follow menu entry for '(texinfo) @- @hyphenation' To: vincent@hotmail.fr CC: gavinsmith0...@gmail.com; 18...@debbugs.gnu.org [...] I a nutshell, there are cases of node references where the info viewer is not bothered by internal multiple spaces (this cross reference inside bash manual), and other cases where the info viewer cannot handle it (the case of node (texinfo) @- @hyphenation pointer in menu entry of upper node). Emacs already does all that, of course. Just not in the case of the menu entries, where the node names are not expected to span more than one line. I have checked that in the case of the node line: File: texinfo.info Node:node name ... the texi2any compiler does correctly the multiblank collapsing. Basically, trying to recap, if I get it, the work split that you (Eli) are suggesting between info viewer and texi2any compiler is as follows: - texi2any must collapse multiple blanks in node names *everywhere*, but it is still allowed to break and indent a node name containing a blank accross a line in the case of a note. - info viewer must handle node name split accross lines, but it does not need to make multiblank reduction in other-cases Now, if the above is agreable, then in the case of our problem this would imply that when texi2any meets that kind of menu entry * NODENAME:: SOME TITLE It must convert it to within the info file: * NODENAME: NODE NAME. SOME TITLE Eli: 1) do you agree on my re-caping and suggestion ? 2) do you think that all the same, robustifying the info viewer in the case of menu entry has some benefit --- after all this allows: 2.1) to cope with job done by earlier versions of makeinfo in this corner case 2.2) to have very slightly smaller info file still in this corner case Gavin Patrice, do you agree on my suggestion how to evolve texi2any and stand-alone info viewer ? So, on second thoughts, I am thinking in the end that for consistency, the info viewer not only should, but also _must_ be corrected. As I said, maybe. But the fact is that the _Texinfo_source_ of the Texinfo manual uses different amounts of blanks in this node's name. So line breaking and filling in the Info file is not the issue here. I am even speculating that in the case of the manual menu entry, probably it was intentional to put more spaces for the entry to read better (as @- and @hyphenation are two different commands, isn't it a good idea to put a little more space between them). The problem is _inconsistency_, not extra blanks. The number of blanks should have been consistent in all the uses of this node name. I think that the root of that _inconsistency_ problem is that when you write the following: * NODENAME:: SOME TITLE NODENAME has two meanings: 1) it is the menu label, ie what the user will see, so you are not allowed to collapse blanks, because this would change what the author want to be diplayed to the user 2) it is also the node pointer, so in this case you have to collapse blanks. Karl: don't you think that *ALSO* the manuel should be changed to be written as * NODENAME: NODE NAME. SOME TITLE In the case of info node `(texinfo) @- @hyphenation'. Maybe it is not such a good practice to write it the other way round, because if the author has some intention to display things in some specific way, then for maintainability that should be explicit in the way as it is written in the texinfo code. Vincent.
