diff options
author | Jérôme Laurens <jerome.laurens@u-bourgogne.fr> | 2009-07-08 11:35:32 +0000 |
---|---|---|
committer | Jérôme Laurens <jerome.laurens@u-bourgogne.fr> | 2009-07-08 11:35:32 +0000 |
commit | c22898f94bcbefb6ac42d8d109cdc298fc646007 (patch) | |
tree | 9ec375267ec93c2c47f5b7619440687f44d8287d /Build/source/texk/web2c/synctexdir/synctex_parser.h | |
parent | d68114f5117e9ca6c33a676b9b239a5617196baa (diff) |
First synctex update, it might need some fine tuning in order to work on all platforms.\nSee the file synctex_parser_history.txt for more details.
git-svn-id: svn://tug.org/texlive/trunk@14186 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/synctexdir/synctex_parser.h')
-rw-r--r-- | Build/source/texk/web2c/synctexdir/synctex_parser.h | 335 |
1 files changed, 191 insertions, 144 deletions
diff --git a/Build/source/texk/web2c/synctexdir/synctex_parser.h b/Build/source/texk/web2c/synctexdir/synctex_parser.h index f698ffb5a7e..6f549a489bc 100644 --- a/Build/source/texk/web2c/synctexdir/synctex_parser.h +++ b/Build/source/texk/web2c/synctexdir/synctex_parser.h @@ -1,8 +1,13 @@ /* -Copyright (c) 2008 jerome DOT laurens AT u-bourgogne DOT fr +Copyright (c) 2008, 2009 jerome DOT laurens AT u-bourgogne DOT fr This file is part of the SyncTeX package. +Latest Revision: Wed Jul 1 11:16:51 UTC 2009 + +Version: 1.6 +See synctex_parser_readme.txt for more details + License: -------- Permission is hereby granted, free of charge, to any person @@ -49,46 +54,124 @@ Thu Jun 19 09:39:21 UTC 2008 #ifndef __SYNCTEX_PARSER__ # define __SYNCTEX_PARSER__ -/* synctex_node_t is the type for all synctex nodes. - * The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */ -typedef struct _synctex_node * synctex_node_t; - -/* The main synctex object is a scanner - * Its implementation is considered private. - * The basic workflow is - * - create a scanner with a file - * - perform actions on that scanner - * - free the scanner - */ -typedef struct __synctex_scanner_t _synctex_scanner_t; -typedef _synctex_scanner_t * synctex_scanner_t; - #ifdef __cplusplus extern "C" { #endif -/* This is the designated method to create a new synctex scanner object. - * output is the pdf/dvi/xdv file associated to the synctex file. - * If relevant, it can be the tex file that originated the synctex file - * but it might cause problems if the \jobname has a custom value. - * The last file extension is removed and replaced by the proper extension. - * Then the private method synctex_scanner_new_with_contents_of_file is called. - * NULL is returned in case of an error or non existent file. +/* synctex_node_t is the type for all synctex nodes. + * The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */ +typedef struct _synctex_node * synctex_node_t; + +/* The main synctex object is a scanner + * Its implementation is considered private. + * The basic workflow is + * - create a "synctex scanner" with the contents of a file + * - perform actions on that scanner like display or edit queries + * - free the scanner when the work is done + */ +typedef struct __synctex_scanner_t _synctex_scanner_t; +typedef _synctex_scanner_t * synctex_scanner_t; + +/* This is the designated method to create a new synctex scanner object. + * output is the pdf/dvi/xdv file associated to the synctex file. + * If necessary, it can be the tex file that originated the synctex file + * but this might cause problems if the \jobname has a custom value. + * Despite this method can accept a relative path in practice, + * you should only pass a full path name. + * The path should be encoded by the underlying file system, + * assuming that it is based on 8 bits characters, including UTF8, + * not 16 bits nor 32 bits. + * The last file extension is removed and replaced by the proper extension. + * Then the private method _synctex_scanner_new_with_contents_of_file is called. + * NULL is returned in case of an error or non existent file. + * Once you have a scanner, use the synctex_display_query and synctex_edit_query below. + * The new "build_directory" argument is available since version 1.5. + * It is the directory where all the auxiliary stuff is created. + * Sometimes, the synctex output file and the pdf, dvi or xdv files are not created in the same directory. + * This is the case in MikTeX (I will include this into TeX Live). + * This directory path can be nil, it will be ignored. + * It can be either absolute or relative to the directory of the output pdf (dvi or xdv) file. + * If no synctex file is found in the same directory as the output file, then we try to find one in the build directory. + * Please note that this new "build_directory" is provided as a convenient argument but should not be used. + * In fact, this is implempented as a work around of a bug in MikTeX where the synctex file does not follow the pdf file. + * The new "parse" argument is available since version 1.5. In general, use 1. + * Use 0 only if you do not want to parse the content but just check the existence. */ -synctex_scanner_t synctex_scanner_new_with_output_file(const char * output); +synctex_scanner_t synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse); -/* This is the designated method to delete a synctex scanner object. - * Frees all the memory. +/* This is the designated method to delete a synctex scanner object. + * Frees all the memory, you must call it when you are finished with the scanner. */ void synctex_scanner_free(synctex_scanner_t scanner); -/* Display all the information contained in the scanner object. - * If the records are too numerous, only the first ones are displayed. - * This is mainly for informatinal purpose to help developers. +/* Send this message to force the scanner to parse the contents of the synctex output file. + * Nothing is performed if the file was already parsed. + * In each query below, this message is sent, but if you need to access information more directly, + * you must be sure that the parsing did occur. + * Usage: + * if((my_scanner = synctex_scanner_parse(my_scanner))) { + * continue with my_scanner... + * } else { + * there was a problem + * } + */ +synctex_scanner_t synctex_scanner_parse(synctex_scanner_t scanner); + +/* The main entry points. + * Given the file name, a line and a column number, synctex_display_query returns the number of nodes + * satisfying the contrain. Use code like + * + * if(synctex_display_query(scanner,name,line,column)>0) { + * synctex_node_t node; + * while((node = synctex_next_result(scanner))) { + * // do something with node + * ... + * } + * } + * + * For example, one can + * - highlight each resulting node in the output, using synctex_node_h and synctex_node_v + * - highlight all the rectangles enclosing those nodes, using synctex_box_... functions + * - highlight just the character using that information + * + * Given the page and the position in the page, synctex_edit_query returns the number of nodes + * satisfying the contrain. Use code like + * + * if(synctex_edit_query(scanner,page,h,v)>0) { + * synctex_node_t node; + * while(node = synctex_next_result(scanner)) { + * // do something with node + * ... + * } + * } + * + * For example, one can + * - highlight each resulting line in the input, + * - highlight just the character using that information + * + * page is 1 based + * h and v are coordinates in 72 dpi unit, relative to the top left corner of the page. + * If you make a new query, the result of the previous one is discarded. + * If one of this function returns a non positive integer, + * it means that an error occurred. + * + * Both methods are conservative, in the sense that matching is weak. + * If the exact column number is not found, there will be an answer with the whole line. + * + * Sumatra-PDF, Skim, iTeXMac2 and Texworks are examples of open source software that use this library. + * You can browse their code for a concrete implementation. + */ +int synctex_display_query(synctex_scanner_t scanner,const char * name,int line,int column); +int synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v); +synctex_node_t synctex_next_result(synctex_scanner_t scanner); + +/* Display all the information contained in the scanner object. + * If the records are too numerous, only the first ones are displayed. + * This is mainly for informatinal purpose to help developers. */ void synctex_scanner_display(synctex_scanner_t scanner); -/* The x and y offset of the origin in TeX coordinates. The magnification +/* The x and y offset of the origin in TeX coordinates. The magnification These are used by pdf viewers that want to display the real box size. For example, getting the horizontal coordinates of a node would require synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner) @@ -100,14 +183,14 @@ int synctex_scanner_x_offset(synctex_scanner_t scanner); int synctex_scanner_y_offset(synctex_scanner_t scanner); float synctex_scanner_magnification(synctex_scanner_t scanner); -/* Managing the input file names. - * Given a tag, synctex_scanner_get_name will return the corresponding file name. - * Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag. - * The file name must be the very same as understood by TeX. - * For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex. - * No automatic path expansion is performed. - * Finally, synctex_scanner_input is the first input node of the scanner. - * To browse all the input node, use a loop like +/* Managing the input file names. + * Given a tag, synctex_scanner_get_name will return the corresponding file name. + * Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag. + * The file name must be the very same as understood by TeX. + * For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex. + * No automatic path expansion is performed. + * Finally, synctex_scanner_input is the first input node of the scanner. + * To browse all the input node, use a loop like * * if((input_node = synctex_scanner_input(scanner))){ * do { @@ -115,9 +198,9 @@ float synctex_scanner_magnification(synctex_scanner_t scanner); * } while((input_node=synctex_node_sibling(input_node))); * } * - * The output is the name that was used to create the scanner. - * The synctex is the real name of the synctex file, - * it was obtained from output by setting the proper file extension. + * The output is the name that was used to create the scanner. + * The synctex is the real name of the synctex file, + * it was obtained from output by setting the proper file extension. */ const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag); int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name); @@ -125,27 +208,27 @@ synctex_node_t synctex_scanner_input(synctex_scanner_t scanner); const char * synctex_scanner_get_output(synctex_scanner_t scanner); const char * synctex_scanner_get_synctex(synctex_scanner_t scanner); -/* Browsing the nodes - * parent, child and sibling are standard names for tree nodes. - * The parent is one level higher, the child is one level deeper, - * and the sibling is at the same level. - * The sheet of a node is the first ancestor, it is of type sheet. - * A node and its sibling have the same parent. - * A node is the parent of its child. - * A node is either the child of its parent, - * or belongs to the sibling chain of its parent's child. - * The next node is either the child, the sibling or the parent's sibling, - * unless the parent is a sheet. - * This allows to navigate through all the nodes of a given sheet node: +/* Browsing the nodes + * parent, child and sibling are standard names for tree nodes. + * The parent is one level higher, the child is one level deeper, + * and the sibling is at the same level. + * The sheet of a node is the first ancestor, it is of type sheet. + * A node and its sibling have the same parent. + * A node is the parent of its child. + * A node is either the child of its parent, + * or belongs to the sibling chain of its parent's child. + * The next node is either the child, the sibling or the parent's sibling, + * unless the parent is a sheet. + * This allows to navigate through all the nodes of a given sheet node: * * synctex_node_t node = sheet; * while((node = synctex_node_next(node))) { * // do something with node * } * - * With synctex_sheet_content, you can retrieve the sheet node given the page. - * The page is 1 based, according to TeX standards. - * Conversely synctex_node_sheet allows to retrieve the sheet containing a given node. + * With synctex_sheet_content, you can retrieve the sheet node given the page. + * The page is 1 based, according to TeX standards. + * Conversely synctex_node_sheet allows to retrieve the sheet containing a given node. */ synctex_node_t synctex_node_parent(synctex_node_t node); synctex_node_t synctex_node_sheet(synctex_node_t node); @@ -154,77 +237,77 @@ synctex_node_t synctex_node_sibling(synctex_node_t node); synctex_node_t synctex_node_next(synctex_node_t node); synctex_node_t synctex_sheet_content(synctex_scanner_t scanner,int page); -/* These are the types of the synctex nodes */ +/* These are the types of the synctex nodes */ typedef enum { synctex_node_type_error = 0, + synctex_node_type_input, synctex_node_type_sheet, synctex_node_type_vbox, synctex_node_type_void_vbox, synctex_node_type_hbox, synctex_node_type_void_hbox, - synctex_node_type_hbox_non_void, synctex_node_type_kern, synctex_node_type_glue, synctex_node_type_math, - synctex_node_type_input, + synctex_node_type_boundary, synctex_node_number_of_types } synctex_node_type_t; -/* synctex_node_type gives the type of a given node, - * synctex_node_isa gives the same information as a human readable text. */ +/* synctex_node_type gives the type of a given node, + * synctex_node_isa gives the same information as a human readable text. */ synctex_node_type_t synctex_node_type(synctex_node_t node); const char * synctex_node_isa(synctex_node_t node); -/* This is primarily used for debugging purpose. - * The second one logs information for the node and recursively displays information for its next node */ +/* This is primarily used for debugging purpose. + * The second one logs information for the node and recursively displays information for its next node */ void synctex_node_log(synctex_node_t node); void synctex_node_display(synctex_node_t node); -/* Given a node, access to its tag, line and column. - * The line and column numbers are 1 based. - * The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line. - * When the tag is known, the scanner of the node will give the corresponding file name. - * When the tag is known, the scanner of the node will give the name. +/* Given a node, access to its tag, line and column. + * The line and column numbers are 1 based. + * The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line. + * When the tag is known, the scanner of the node will give the corresponding file name. + * When the tag is known, the scanner of the node will give the name. */ int synctex_node_tag(synctex_node_t node); int synctex_node_line(synctex_node_t node); int synctex_node_column(synctex_node_t node); -/* This is the page where the node appears. - * This is a 1 based index as given by TeX. +/* This is the page where the node appears. + * This is a 1 based index as given by TeX. */ int synctex_node_page(synctex_node_t node); -/* For quite all nodes, horizontal, vertical coordinates, and width. - * These are expressed in page coordinates, with origin at the top left corner. +/* For quite all nodes, horizontal, vertical coordinates, and width. + * These are expressed in TeX small points coordinates, with origin at the top left corner. */ -float synctex_node_h(synctex_node_t node); -float synctex_node_v(synctex_node_t node); -float synctex_node_width(synctex_node_t node); +int synctex_node_h(synctex_node_t node); +int synctex_node_v(synctex_node_t node); +int synctex_node_width(synctex_node_t node); -/* For all nodes, dimensions of the enclosing box. - * These are expressed in page coordinates, with origin at the top left corner. - * A box is enclosing itself. +/* For all nodes, dimensions of the enclosing box. + * These are expressed in TeX small points coordinates, with origin at the top left corner. + * A box is enclosing itself. */ -float synctex_node_box_h(synctex_node_t node); -float synctex_node_box_v(synctex_node_t node); -float synctex_node_box_width(synctex_node_t node); -float synctex_node_box_height(synctex_node_t node); -float synctex_node_box_depth(synctex_node_t node); - -/* For quite all nodes, horizontal, vertical coordinates, and width. - * The visible dimensions are bigger than real ones to compensate 0 width boxes - * that do contain nodes. - * These are expressed in page coordinates, with origin at the top left corner. - * A box is enclosing itself. +int synctex_node_box_h(synctex_node_t node); +int synctex_node_box_v(synctex_node_t node); +int synctex_node_box_width(synctex_node_t node); +int synctex_node_box_height(synctex_node_t node); +int synctex_node_box_depth(synctex_node_t node); + +/* For quite all nodes, horizontal, vertical coordinates, and width. + * The visible dimensions are bigger than real ones to compensate 0 width boxes + * that do contain nodes. + * These are expressed in page coordinates, with origin at the top left corner. + * A box is enclosing itself. */ float synctex_node_visible_h(synctex_node_t node); float synctex_node_visible_v(synctex_node_t node); float synctex_node_visible_width(synctex_node_t node); -/* For all nodes, visible dimensions of the enclosing box. - * A box is enclosing itself. - * The visible dimensions are bigger than real ones to compensate 0 width boxes - * that do contain nodes. +/* For all nodes, visible dimensions of the enclosing box. + * A box is enclosing itself. + * The visible dimensions are bigger than real ones to compensate 0 width boxes + * that do contain nodes. */ float synctex_node_box_visible_h(synctex_node_t node); float synctex_node_box_visible_v(synctex_node_t node); @@ -232,67 +315,31 @@ float synctex_node_box_visible_width(synctex_node_t node); float synctex_node_box_visible_height(synctex_node_t node); float synctex_node_box_visible_depth(synctex_node_t node); -/* The main entry points. - * Given the file name, a line and a column number, synctex_display_query returns the number of nodes - * satisfying the contrain. Use code like - * - * if(synctex_display_query(scanner,name,line,column)>0) { - * synctex_node_t node; - * while((node = synctex_next_result(scanner))) { - * // do something with node - * ... - * } - * } - * - * Given the page and the position in the page, synctex_edit_query returns the number of nodes - * satisfying the contrain. Use code like - * - * if(synctex_edit_query(scanner,page,h,v)>0) { - * synctex_node_t node; - * while(node = synctex_next_result(scanner)) { - * // do something with node - * ... - * } - * } - * - * page is 1 based - * h and v are coordinates relative to the top left corner of the page. - * If you make a new query, the result of the previous one is discarded. - * If one of this function returns a non positive integer, - * it means that an error occurred. - * - * Both methods are conservative, in the sense that matching is weak. - * If the exact column number is not found, there will be an answer with the whole line. - */ -int synctex_display_query(synctex_scanner_t scanner,const char * name,int line,int column); -int synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v); -synctex_node_t synctex_next_result(synctex_scanner_t scanner); - -/* The main synctex updater object. - * This object is used to append information to the synctex file. - * Its implementation is considered private. - * It is used by the synctex command line tool to take into account modifications - * that could occur while postprocessing files by dvipdf like filters. +/* The main synctex updater object. + * This object is used to append information to the synctex file. + * Its implementation is considered private. + * It is used by the synctex command line tool to take into account modifications + * that could occur while postprocessing files by dvipdf like filters. */ typedef struct __synctex_updater_t _synctex_updater_t; typedef _synctex_updater_t * synctex_updater_t; -/* Designated initializer. - * Once you are done with your whole job, - * free the updater */ -synctex_updater_t synctex_updater_new_with_output_file(const char * output); +/* Designated initializer. + * Once you are done with your whole job, + * free the updater */ +synctex_updater_t synctex_updater_new_with_output_file(const char * output, const char * directory); -/* Use the next functions to append records to the synctex file, - * no consistency tests made on the arguments */ -void synctex_updater_append_magnification(synctex_updater_t updater, char * magnification); -void synctex_updater_append_x_offset(synctex_updater_t updater, char * x_offset); -void synctex_updater_append_y_offset(synctex_updater_t updater, char * y_offset); +/* Use the next functions to append records to the synctex file, + * no consistency tests made on the arguments */ +void synctex_updater_append_magnification(synctex_updater_t updater, char * magnification); +void synctex_updater_append_x_offset(synctex_updater_t updater, char * x_offset); +void synctex_updater_append_y_offset(synctex_updater_t updater, char * y_offset); -/* You MUST free the updater, once everything is properly appended */ +/* You MUST free the updater, once everything is properly appended */ void synctex_updater_free(synctex_updater_t updater); #ifdef __cplusplus -}; +} #endif #endif |