userulehook
userulehook
Function prototype:
hook (windowuseruleiduseparamoidvaluestatedocid)
Synopsis
Use with:
add_hook(hookname, func[, prepend])
remove_hook(hookname, func)
where hookname is userulehook.
The userule hook allows the user to customize processing of FOSI usetexts that have non-zero userule values. It can be used either to customize Arbortext Editor's built-in userule processing (indexing and userule exporting), or to perform entirely different custom processing. The userule hook can be used for any of the following purposes:
• To alter the preliminary index document and then invoke index processing
• To change an ACL variable or set option that affects index processing or export handling
• To alter the contents of a usetext before it is inserted as generated text
• To conditionally decide whether a usetext should be inserted as generated text
• To replicate built-in processing for exporting and indexing
The hook is called:
• when generated text is updated
• before formatting for published output
• after a formatting pass if either of these happens:
◦ page number references within the usetext were changed by the formatting pass
◦ previous calls to the hook returned -1 (see the explanation of the state argument)
Arguments
• window is the integer id of the window in which index processing occurs. The hook is not expected to use this value except as a “handle” to pass to the indexproc and fosivar_value ACL functions.
• useruleid is the integer userule id (sequence number). This is also a “handle” to be passed to the indexproc ACL function.
• useparam is the string value for the useparam.
• oid is the oid of the element being processed in the user's document instance whose element-in-context (e-i-c) contains the usetext with the non-zero userule.
• value is the integer userule value.
• state is the integer indicating userule state. If the state is 1, this is the first time that the userulehook is being called for this oid and this specific usetext (since it is possible for an oid to have more than one usetext). The contents of the document referenced by docid are from the first pass of formatting. If the state is 2, the userulehook is being called again for this oid and this specific usetext and the content of the document referenced by docid is different from the previous call. Usually this is because some page numbers have changed. If you are trying to save the contents to a file or drive some external system, you may want to reprocess because of the changes. If the state is 3, the userulehook is being called again for this oid and this specific usetext and the content of the document referenced by docid has not changed. If you are trying to save the contents to a file or drive some external system, you do not have to reprocess as the contents have not changed.
The hook will only be called for state 3 if the hook returns -1 when called for state 1 and 2. This mechanism is useful when exporting files as it will cause the file only to be written when page numbers have stopped changing.
• docid is the integer id of the document containing the preliminary content that can be modified.
The hook function must return 1 or -1. -1 means do not insert the usetext contents into the output stream; 1 means to insert.
If the preliminary document is modified, and it is desired to then insert the preliminary document into the published output stream, the function must return 1. If nothing is to be inserted in the published output stream, the function must return -1. (This can be useful if the preliminary userule is written to a file, which is referenced elsewhere in the document or is otherwise processed.)
When using the name of an index coding pseudo-element (perhaps when searching for tag occurrence in the document), you must append an asterisk to the pseudo-element name, (for example, ixpt*).
|
|
If the userulehook causes a cross reference to be inserted into the document, the hook must include the following line of ACL for the cross reference to be properly resolved:
main::RESOLVE_XREFS_AFTER_USERULES=1
|
Examples
The following example shows how to alter the preliminary index document and then invoke index processing using the indexproc built in function. This sample code returns the result of indexproc.
# example userulehook: change index to uppercase
function simpleuserulefunc(view_id, userule_id, \
userule_param, userule_oid, userule_value, userule_state, \
userule_doc_id)
{
local otop, obot
local savedoc = current_doc(userule_doc_id)
# translate the prelim doc to upper case
otop = oid_first(userule_doc_id)
obot = oid_last(userule_doc_id)
goto_oid(otop)
mark begin
goto_oid(obot)
mark end
translate uc
# convert the prelim index doc into the final index doc
indexproc(view_id, userule_id, userule_param)
current_doc(savedoc)
return 1
}
This example shows how to replicate built-in processing for exporting and indexing, and how to add custom processing for userule value 3:
function process_userule3(predoc_postdoc)
{
...
}
function ur(view_id, userule_id, userule_param, \
userule_oid, userule_value, userule_state, \
userule_doc_id)
{
local otop, obot
local savedoc = current_doc(userule_doc_id)
if (userule_value == 1 && userule_state < 3)
{
Local filename
filename = "index1.sgml"
write -ok -sgml -nopi -noheader $filename
current_doc(savedoc)
return -1
}
else if (userule_value == 2)
{
indexproc(view_id, userule_id, userule_param)
current_doc(savedoc)
return 1;
}
else if (userule_value == 3)
{
process_userule3(userule_doc_id)
current_doc(savedoc)
return 1
}
return -1;
}
