Hi, Sorry if this is very clear from the manual, maybe I just didn't read the part where it is explained (or I read it but was too stupid/tired to notice), but I don't understand the meaning of the return value of some callbacks. The first example (by order of apparition in the manual) is pre_linebreak_filter, whose calling convention is: function(<node> head, <string> groupcode) return true | false | <node> newhead end I think it's clear what returning a newhead node does, but I don't understand what returning true or false means for this callback. Other similar callbacks include post_linebreak_filter, (h|v)pack_filter, pre_output_filter, etc. The underlying problem is, I was trying to enhance the user documentation of luatexbase-mcb (which allows to register many functions in a single callback, based on some ConTeXt code I believe) but I can't make sense of the calling conventions in the current code (the functions are expected to return a node *and* true, in whatever order), so that I can't check it is correct, and even less document why it works that way. I guess understanding the calling convention for the callbacks themselves would be a good starting point. Thanks, Manuel.
On Fri, Nov 05, 2010 at 01:59:54PM +0100, Manuel Pégourié-Gonnard wrote:
Hi,
Sorry if this is very clear from the manual, maybe I just didn't read the part where it is explained (or I read it but was too stupid/tired to notice), but I don't understand the meaning of the return value of some callbacks.
The first example (by order of apparition in the manual) is pre_linebreak_filter, whose calling convention is:
function(<node> head, <string> groupcode) return true | false | <node> newhead end
I think it's clear what returning a newhead node does, but I don't understand what returning true or false means for this callback. Other similar callbacks include post_linebreak_filter, (h|v)pack_filter, pre_output_filter, etc.
I think it is explained in section 4.1: For some minor speed gain, you can assign the boolean false to the non-file related callbacks, doing so will prevent LuaTeX from executing whatever it would execute by default (when no callback function is registered at all). Be warned: this may cause all sorts of grief unless you know exactly what you are doing! This functionality is present since version 0.38. Not sure about "true" though. Regards, Khaled -- Khaled Hosny Arabic localiser and member of Arabeyes.org team Free font developer
On 11/05/2010 02:22 PM, Khaled Hosny wrote:
I think it is explained in section 4.1:
For some minor speed gain, you can assign the boolean false to the non-file related callbacks, doing so will prevent LuaTeX from executing whatever it would execute by default (when no callback function is registered at all).
No, this is different, this documents the case of callback.register('pre_linebreak_filter', false)
On Fri, Nov 05, 2010 at 02:24:25PM +0100, Taco Hoekwater wrote:
On 11/05/2010 02:22 PM, Khaled Hosny wrote:
I think it is explained in section 4.1:
For some minor speed gain, you can assign the boolean false to the non-file related callbacks, doing so will prevent LuaTeX from executing whatever it would execute by default (when no callback function is registered at all).
No, this is different, this documents the case of
callback.register('pre_linebreak_filter', false)
Which I just realised :) -- Khaled Hosny Arabic localiser and member of Arabeyes.org team Free font developer
On Fri, Nov 05, 2010 at 03:22:06PM +0200, Khaled Hosny wrote:
On Fri, Nov 05, 2010 at 01:59:54PM +0100, Manuel Pégourié-Gonnard wrote:
Hi,
Sorry if this is very clear from the manual, maybe I just didn't read the part where it is explained (or I read it but was too stupid/tired to notice), but I don't understand the meaning of the return value of some callbacks.
The first example (by order of apparition in the manual) is pre_linebreak_filter, whose calling convention is:
function(<node> head, <string> groupcode) return true | false | <node> newhead end
I think it's clear what returning a newhead node does, but I don't understand what returning true or false means for this callback. Other similar callbacks include post_linebreak_filter, (h|v)pack_filter, pre_output_filter, etc.
I think it is explained in section 4.1:
For some minor speed gain, you can assign the boolean false to the non-file related callbacks, doing so will prevent LuaTeX from executing whatever it would execute by default (when no callback function is registered at all). Be warned: this may cause all sorts of grief unless you know exactly what you are doing! This functionality is present since version 0.38.
Not sure about "true" though.
Please ignore this, I just confused things up. Regards, Khaled -- Khaled Hosny Arabic localiser and member of Arabeyes.org team Free font developer
On 11/05/2010 01:59 PM, Manuel Pégourié-Gonnard wrote:
Hi,
Sorry if this is very clear from the manual, maybe I just didn't read the part where it is explained (or I read it but was too stupid/tired to notice), but I don't understand the meaning of the return value of some callbacks.
The first example (by order of apparition in the manual) is pre_linebreak_filter, whose calling convention is:
function(<node> head,<string> groupcode) return true | false |<node> newhead end
I think it's clear what returning a newhead node does, but I don't understand what returning true or false means for this callback. Other similar callbacks include post_linebreak_filter, (h|v)pack_filter, pre_output_filter, etc.
In all these cases the result of returning a boolean is the same: false == callback has failed true == callback has run ok, but nothing has been changed the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Hi, [btw: I meant to write to the users list, sorry] Le 05/11/2010 14:22, Taco Hoekwater a écrit :
In all these cases the result of returning a boolean is the same:
false == callback has failed true == callback has run ok, but nothing has been changed
the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Ok, thanks for the clarification. Just to be sure: in case the function returns false, and error will be issued, right? Thanks, Manuel.
On 11/05/2010 02:46 PM, Manuel Pégourié-Gonnard wrote:
Hi,
[btw: I meant to write to the users list, sorry]
Le 05/11/2010 14:22, Taco Hoekwater a écrit :
In all these cases the result of returning a boolean is the same:
false == callback has failed true == callback has run ok, but nothing has been changed
the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Ok, thanks for the clarification. Just to be sure: in case the function returns false, and error will be issued, right?
Eh ... no. You have to raise an error yourself, if you want that.
Le 05/11/2010 14:52, Taco Hoekwater a écrit :
On 11/05/2010 02:46 PM, Manuel Pégourié-Gonnard wrote:
Le 05/11/2010 14:22, Taco Hoekwater a écrit :
In all these cases the result of returning a boolean is the same:
false == callback has failed true == callback has run ok, but nothing has been changed
the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Ok, thanks for the clarification. Just to be sure: in case the function returns false, and error will be issued, right?
Eh ... no. You have to raise an error yourself, if you want that.
Hum, so what is the purpose of returning false rather than true, if no action is taken based on this value?
On 11/05/2010 02:56 PM, Manuel Pégourié-Gonnard wrote:
Le 05/11/2010 14:52, Taco Hoekwater a écrit :
On 11/05/2010 02:46 PM, Manuel Pégourié-Gonnard wrote:
Le 05/11/2010 14:22, Taco Hoekwater a écrit :
In all these cases the result of returning a boolean is the same:
false == callback has failed true == callback has run ok, but nothing has been changed
the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Ok, thanks for the clarification. Just to be sure: in case the function returns false, and error will be issued, right?
Eh ... no. You have to raise an error yourself, if you want that.
Hum, so what is the purpose of returning false rather than true, if no action is taken based on this value?
Oh, now I see this was not clear. Action actually is taken: the whole node list starting at head is thrown away.
Le 05/11/2010 14:57, Taco Hoekwater a écrit :
On 11/05/2010 02:56 PM, Manuel Pégourié-Gonnard wrote:
Le 05/11/2010 14:52, Taco Hoekwater a écrit :
On 11/05/2010 02:46 PM, Manuel Pégourié-Gonnard wrote:
Le 05/11/2010 14:22, Taco Hoekwater a écrit :
In all these cases the result of returning a boolean is the same:
false == callback has failed true == callback has run ok, but nothing has been changed
the latter case (true) is interesting because it allows a speed optimization that can be considerable. I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Ok, thanks for the clarification. Just to be sure: in case the function returns false, and error will be issued, right?
Eh ... no. You have to raise an error yourself, if you want that.
Hum, so what is the purpose of returning false rather than true, if no action is taken based on this value?
Oh, now I see this was not clear. Action actually is taken: the whole node list starting at head is thrown away.
Ok, now it's perfectly clear. Thanks again, Manuel.
Le 05/11/2010 14:22, Taco Hoekwater a écrit :
I could have sworn this was mentioned in the manual, but I cannot find it myself either.
Got it! It was in the manual under buildpage_filter for luatex 0.25:
As for all the callbacks that deal with nodes, the return value can be one of three things: · boolean true signals succesful processing · node signals that the `head' node should be replaced by this node · boolean false signals that the `head' node list should be ignored and flushed from memory
Then, the calling convention for this callback was changed, and the text likely disappeared at this point. Manuel.
participants (3)
-
Khaled Hosny -
Manuel Pégourié-Gonnard -
Taco Hoekwater