Re: @menu puts too many restrictions to produce the .info file
Good evening Gavin. I have actually. My original plan was to have multiple menus for different types of users, so they may traverse it according to the job they want to do. Many, including myself end up having to go though a lot of menu paths to get what I need. So it is customary for me to simply take the texi files and traverse using some scripts rather than using info. I used to use Next/Prev/Up, although a bit tedious to specify three things for each node. Much rather have a switch that lets me set any menu the way I want without starting whining at me. Not everybody requires the same level of detail and for some users, many nodes would be irrelevant for them. As a workaround I been making nodes with a sort of "menu" but really using @ref for the links. Does my wrangling make sense, or do you see problems in using info in the said way? Info works well, until you start focusing on abbreviated ways of doing a job and you got to use the manual. There are some packages with just an info manual which I find difficult to use. I prefer html entirely on one page for rapidity. - Christopher Dimech General Administrator - Naiad Informatics - GNU Project (Geocomputation) - Geophysical Simulation - Geological Subsurface Mapping - Disaster Preparedness and Mitigation - Natural Resource Exploration and Production - Free Software Advocacy > Sent: Saturday, October 31, 2020 at 10:04 PM > From: "Gavin Smith" > To: "Patrice Dumas" , "Christopher Dimech" > , "help-texinfo gnu" > Subject: Re: @menu puts too many restrictions to produce the .info file > > On Tue, Oct 20, 2020 at 05:59:56PM +0100, Gavin Smith wrote: > > On Tue, Oct 20, 2020 at 04:53:11PM +0100, Gavin Smith wrote: > > > If an author wants to have irregular menu or node structures for some > > > reason (I haven't made sense exactly of what Christopher is doing > > > with his documents) then they could use explicit node pointers, > > > specifying Next/Prev/Up for each node. > > > > Another idea is to make it so that if a node has explicit node > > pointers, then its menu would not be used to determine structural > > relations between nodes. The menu, along with the node pointers, would > > be trusted to be correct, and intended by the author, but not used > > for anything else. > > Did you think about whether this would be a good idea? I explained > this in more detail in another message. >
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 05:59:56PM +0100, Gavin Smith wrote: > On Tue, Oct 20, 2020 at 04:53:11PM +0100, Gavin Smith wrote: > > If an author wants to have irregular menu or node structures for some > > reason (I haven't made sense exactly of what Christopher is doing > > with his documents) then they could use explicit node pointers, > > specifying Next/Prev/Up for each node. > > Another idea is to make it so that if a node has explicit node > pointers, then its menu would not be used to determine structural > relations between nodes. The menu, along with the node pointers, would > be trusted to be correct, and intended by the author, but not used > for anything else. Did you think about whether this would be a good idea? I explained this in more detail in another message.
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 05:30:15PM +0200, Christopher Dimech wrote: > Understood. Had thought it exists but not documented, but reading your > comment again, you are correct. Would one be able to call it inside the > source code? Currently customization variables can only be set on the command line and in customization perl code, not in Texinfo. I am not sure that this should change. -- Pat
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 05:59:56PM +0100, Gavin Smith wrote: > On Tue, Oct 20, 2020 at 04:53:11PM +0100, Gavin Smith wrote: > > If an author wants to have irregular menu or node structures for some > > reason (I haven't made sense exactly of what Christopher is doing > > with his documents) then they could use explicit node pointers, > > specifying Next/Prev/Up for each node. > > Another idea is to make it so that if a node has explicit node > pointers, then its menu would not be used to determine structural > relations between nodes. The menu, along with the node pointers, would > be trusted to be correct, and intended by the author, but not used > for anything else. I was certain that it was already the case... > We'd need specifics of possible irregular document structures to know > how well this idea would work. As I said in another mail, to me the only constraint should be that any node is reachable from any point in the document through nodes or menus. Other than that, I do not think that we need to put constraints, although we could want to have warning messages for unusual structures. -- Pat
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 04:53:11PM +0100, Gavin Smith wrote: > > Possibly, @novalidate was supposed to do this, as well as checking > cross-references: > > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Pointer-Validation.html > > > Instead, makeinfo checks that the tree constructed from the > > document’s menus matches the tree constructed from the sectioning > > commands. For example, if a chapter-level menu mentions nodes n1 and > > n2, in that order, nodes n1 and n2 must be associated with @section > > commands in the chapter. > > However, it doesn't appear to work fully. All the warnings/errors > are still present with @novalidate or --no-validate. @novalidate > may also do something slightly different with texinfo.tex (stops > auxiliary files from being opened). It might be worth checking what > @novalidate did with older versions of makeinfo to see if there > is a regression. I do not think that we should do that. I think implementing what is in the documentation is more important than being in line with what was before. And even more important is to specify correctly in the documentation what it should do. > @novalidate seems to have been intended as an ad hoc, temporary > insertion in a file while it was being worked on, rather than to > be a permanent part of the file. I am not so sure about that. If it is so, it should be documented. > I don't like the idea of requiring variables to be set for a file to be > processed correctly. It would be better if there was something in the > file itself to indicate how menus/sectioning should be interpreted. > Due to the effect on texinfo.tex, @novalidate can't have this role, > though. I do not think that the issue here is the processing, only the messages. > The menu/sectioning code is already quite complicated, so adding > another customization variable affecting this would be a bad idea. > > The warnings and errors go away if you specify node pointers explicitly. > > For example, instead of > > @node Intactv-Function > > have > > @node Intactv-Function,,, > > After all, since you have not said what the Next/Prev node should be > in the first case, makeinfo has to determine it somehow, and it is a > problem if the menus and apparent section structure contradict each other. That is a good point. However, it is not clear to me that it is a problem if the Next/Prev and the menus are different, which means that it could be acceptable for the tree structure and the menu structure to be different even if the Next/Prev node are determined by the section tree structure. To state it differently, maybe it should be possible to select menu or sections to be the source of the Next/Prev, and have the Next/Prev structure not consistent with the one that is not used to setup the Next/Prev. I'll have to look at the code to remember how things are done. > If an author wants to have irregular menu or node structures for some > reason (I haven't made sense exactly of what Christopher is doing > with his documents) then they could use explicit node pointers, > specifying Next/Prev/Up for each node. I think that the menu structure could be somehow disconnected from the node structure. It seems to me that as long as a node is reachable, it is ok, even if the node Next/Prev/Up structure is not consistent with the menu structure. -- Pat
Re: @menu puts too many restrictions to produce the .info file
I attach a file to see how I used floats to display images where indenting makes sense as in standard languages. Things are fine with sectioning, title, ... and can use whole line. But I see many instances when users want to include many @if* statements, including within other constructs. I see that conditional expressions can become very important for large works. > Sent: Tuesday, October 20, 2020 at 5:59 PM > From: "Gavin Smith" > To: "Christopher Dimech" > Cc: "Patrice Dumas" , "help-texinfo gnu" > > Subject: Re: @menu puts too many restrictions to produce the .info file > > On Tue, Oct 20, 2020 at 05:30:15PM +0200, Christopher Dimech wrote: > > I also mention that Makeinfo states that @ifset and @ifclear > > should only appear at a line beginning. I suggest that it be made > > as other region commands that are allowed indentation. > > This is not necessarily easy to implement and it would be very easy > for you to move the commands to the beginnings of their lines. It's > never been encouraged to indent whole-line commands in Texinfo. > Ch03b--Chmed--Igm.texi Description: TeXInfo document
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 04:53:11PM +0100, Gavin Smith wrote: > If an author wants to have irregular menu or node structures for some > reason (I haven't made sense exactly of what Christopher is doing > with his documents) then they could use explicit node pointers, > specifying Next/Prev/Up for each node. Another idea is to make it so that if a node has explicit node pointers, then its menu would not be used to determine structural relations between nodes. The menu, along with the node pointers, would be trusted to be correct, and intended by the author, but not used for anything else. We'd need specifics of possible irregular document structures to know how well this idea would work.
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 05:30:15PM +0200, Christopher Dimech wrote: > I also mention that Makeinfo states that @ifset and @ifclear > should only appear at a line beginning. I suggest that it be made > as other region commands that are allowed indentation. This is not necessarily easy to implement and it would be very easy for you to move the commands to the beginnings of their lines. It's never been encouraged to indent whole-line commands in Texinfo.
Re: @menu puts too many restrictions to produce the .info file
The simplest solution for Christopher's document is to delete the menu altogether: delete the four lines @menu * Intactv-Function:: Interactive Functions. * Tpsw-Cmd:: The Tpsw Interactive Command with Numeric Arguments. @end menu and the errors all go away. On Tue, Oct 20, 2020 at 03:43:23PM +0200, Patrice Dumas wrote: > On Tue, Oct 20, 2020 at 03:31:10PM +0200, Christopher Dimech wrote: > > It should not be assumed that the author made mistakes. At least > > not problems with how one structures the document. Because when > > using texi2pdf all of that is acceptable. > > On the one hand I agree that it may be annoying for a user to have > warnings for intentionnal and valid code, on the other hand, most of the > users are happy with the tree structure and it is indeed a mistake when > the menu structure does not follow the tree structure. So I think that > using a customization variable is ok to begin with, and it could even be > decided later that it is on in the default case. But let's see if Gavin > says something on that. Possibly, @novalidate was supposed to do this, as well as checking cross-references: https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Pointer-Validation.html > Instead, makeinfo checks that the tree constructed from the > document’s menus matches the tree constructed from the sectioning > commands. For example, if a chapter-level menu mentions nodes n1 and > n2, in that order, nodes n1 and n2 must be associated with @section > commands in the chapter. However, it doesn't appear to work fully. All the warnings/errors are still present with @novalidate or --no-validate. @novalidate may also do something slightly different with texinfo.tex (stops auxiliary files from being opened). It might be worth checking what @novalidate did with older versions of makeinfo to see if there is a regression. @novalidate seems to have been intended as an ad hoc, temporary insertion in a file while it was being worked on, rather than to be a permanent part of the file. I don't like the idea of requiring variables to be set for a file to be processed correctly. It would be better if there was something in the file itself to indicate how menus/sectioning should be interpreted. Due to the effect on texinfo.tex, @novalidate can't have this role, though. The menu/sectioning code is already quite complicated, so adding another customization variable affecting this would be a bad idea. I tried @detailmenu to try and get a menu that wouldn't be validated, but this is not enough: although the contents of a @detailmenu block are not subject to validation themselves, @detailmenu has to be nested within a @menu block, and if that @menu block is there, validation happens. The warnings and errors go away if you specify node pointers explicitly. For example, instead of @node Intactv-Function have @node Intactv-Function,,, After all, since you have not said what the Next/Prev node should be in the first case, makeinfo has to determine it somehow, and it is a problem if the menus and apparent section structure contradict each other. If an author wants to have irregular menu or node structures for some reason (I haven't made sense exactly of what Christopher is doing with his documents) then they could use explicit node pointers, specifying Next/Prev/Up for each node.
Re: @menu puts too many restrictions to produce the .info file
Understood. Had thought it exists but not documented, but reading your comment again, you are correct. Would one be able to call it inside the source code? Finding a variable like that becomes vital for those which plan deviates from the popular way. I also mention that Makeinfo states that @ifset and @ifclear should only appear at a line beginning. I suggest that it be made as other region commands that are allowed indentation. Regards Christopher - Christopher Dimech Chief Administrator - Naiad Informatics - GNU Project (Geocomputation) - Geophysical Simulation - Geological Subsurface Mapping - Disaster Preparedness and Mitigation - Natural Resource Exploration and Production - Free Software Advocacy > Sent: Tuesday, October 20, 2020 at 4:45 PM > From: "Patrice Dumas" > To: "Christopher Dimech" > Cc: "help-texinfo gnu" > Subject: Re: @menu puts too many restrictions to produce the .info file > > On Tue, Oct 20, 2020 at 04:33:53PM +0200, Christopher Dimech wrote: > > Sure, but ALLOW_NON_TREE_NODE_STRUCTURE is not there. > > Of course, this is something to be added that I proposed in the mail > following your report. It is not implemented already! I would prefer > to have Gavin look at the proposal before implmenting that (and not > before the week end if I do it). > > > > > > > > > > Sent: Tuesday, October 20, 2020 at 4:15 PM > > > From: "Patrice Dumas" > > > To: "Christopher Dimech" > > > Cc: "help-texinfo gnu" > > > Subject: Re: @menu puts too many restrictions to produce the .info file > > > > > > On Tue, Oct 20, 2020 at 04:10:41PM +0200, Christopher Dimech wrote: > > > > Where are the customization variables documented? > > > > > > In the node 'Customization Variables' of the texinfo manual > > > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Customization-Variables.html > > > > > > -- > > > Pat > > > >
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 04:33:53PM +0200, Christopher Dimech wrote: > Sure, but ALLOW_NON_TREE_NODE_STRUCTURE is not there. Of course, this is something to be added that I proposed in the mail following your report. It is not implemented already! I would prefer to have Gavin look at the proposal before implmenting that (and not before the week end if I do it). > > > > > Sent: Tuesday, October 20, 2020 at 4:15 PM > > From: "Patrice Dumas" > > To: "Christopher Dimech" > > Cc: "help-texinfo gnu" > > Subject: Re: @menu puts too many restrictions to produce the .info file > > > > On Tue, Oct 20, 2020 at 04:10:41PM +0200, Christopher Dimech wrote: > > > Where are the customization variables documented? > > > > In the node 'Customization Variables' of the texinfo manual > > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Customization-Variables.html > > > > -- > > Pat > >
Re: @menu puts too many restrictions to produce the .info file
Sure, but ALLOW_NON_TREE_NODE_STRUCTURE is not there. > Sent: Tuesday, October 20, 2020 at 4:15 PM > From: "Patrice Dumas" > To: "Christopher Dimech" > Cc: "help-texinfo gnu" > Subject: Re: @menu puts too many restrictions to produce the .info file > > On Tue, Oct 20, 2020 at 04:10:41PM +0200, Christopher Dimech wrote: > > Where are the customization variables documented? > > In the node 'Customization Variables' of the texinfo manual > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Customization-Variables.html > > -- > Pat >
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 04:10:41PM +0200, Christopher Dimech wrote: > Where are the customization variables documented? In the node 'Customization Variables' of the texinfo manual https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Customization-Variables.html -- Pat
Re: @menu puts too many restrictions to produce the .info file
On Tue, Oct 20, 2020 at 03:31:10PM +0200, Christopher Dimech wrote: > It should not be assumed that the author made mistakes. At least > not problems with how one structures the document. Because when > using texi2pdf all of that is acceptable. On the one hand I agree that it may be annoying for a user to have warnings for intentionnal and valid code, on the other hand, most of the users are happy with the tree structure and it is indeed a mistake when the menu structure does not follow the tree structure. So I think that using a customization variable is ok to begin with, and it could even be decided later that it is on in the default case. But let's see if Gavin says something on that. > Let's start with a useful case. Let's forget about subsections for now. > > > Test 1: > > Suppose I change the last @node to @anchor. Makeinfo will complain that > menu and sections are not in order. > > If you try to mouse click on the menu at the location of the @anchor, > the Anchor Reference will not work. I agree that it is a relevant case. I'll try to have a look at that in the week end if nobody else do it before. -- Pat
Re: @menu puts too many restrictions to produce the .info file
It should not be assumed that the author made mistakes. At least not problems with how one structures the document. Because when using texi2pdf all of that is acceptable. Message is intended to start a discussion on improving some aspects for those intending to do non-trivial work in texinfo. And start tackling some of them. Let's start with a useful case. Let's forget about subsections for now. Test 1: Suppose I change the last @node to @anchor. Makeinfo will complain that menu and sections are not in order. If you try to mouse click on the menu at the location of the @anchor, the Anchor Reference will not work. - Christopher Dimech Chief Administrator - Naiad Informatics - GNU Project (Geocomputation) - Geophysical Simulation - Geological Subsurface Mapping - Disaster Preparedness and Mitigation - Natural Resource Exploration and Production - Free Software Advocacy > Sent: Tuesday, October 20, 2020 at 3:03 PM > From: "Patrice Dumas" > To: "Christopher Dimech" > Cc: "help-texinfo gnu" > Subject: Re: @menu puts too many restrictions to produce the .info file > > On Tue, Oct 20, 2020 at 02:49:28PM +0200, Christopher Dimech wrote: > > I wish to point out that @menu puts a lot of restrictions on running > > makeinfo. > > > > > > Do you have a use case in which this would not be an error: > > 1. Having an unreferenced node > > 2. lacking some item in the Menu > > 3. Not having same order in menu as in Sectioning > > This one seems to me to be ok, @node and @anchor should be unique, it is > an intended feature: > > 4. Menu complains about @anchor > > 5. Menu complains of @sebsectioning > > > > I do get use cases where the menu is there to help the user > > towards a particular direction. However when I produce > > documentation in Pdf I want it too look are an ordered manual. > > > > There are many reasons why a person would want a menu that differs > > from the sectioning. > > I agree with you on 2, 3, and 5. In general those warnings are ok, as > these are likely to be mistakes, but I agree that the user may want > menus structures to be different from the tree structure and suppress > the corresponding warnings somewhat selectively. @novalidate > and --no-validate could be of use in that case, but it may also be too > broad. > > One possibility could be to add a customization variable, like > ALLOW_NON_TREE_NODE_STRUCTURE > > -- > Pat >
