diff options
author | Jonathan Kew <jfkthame@googlemail.com> | 2008-06-21 00:42:36 +0000 |
---|---|---|
committer | Jonathan Kew <jfkthame@googlemail.com> | 2008-06-21 00:42:36 +0000 |
commit | a833f19836b8e188ce94d82473439714b50f6853 (patch) | |
tree | 7c93c7dfa09f14c61cf13933ac80164198fd0241 /Build/source/texk/web2c/synctexdir/synctex_parser.h | |
parent | c6e0b21f3b6f248c5d57cb61fb0fa545ec329189 (diff) |
synctex update (parser, comments)
git-svn-id: svn://tug.org/texlive/trunk@8892 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 | 93 |
1 files changed, 69 insertions, 24 deletions
diff --git a/Build/source/texk/web2c/synctexdir/synctex_parser.h b/Build/source/texk/web2c/synctexdir/synctex_parser.h index 18a3c8a01a1..f698ffb5a7e 100644 --- a/Build/source/texk/web2c/synctexdir/synctex_parser.h +++ b/Build/source/texk/web2c/synctexdir/synctex_parser.h @@ -31,16 +31,34 @@ shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the copyright holder. +Acknowledgments: +---------------- +The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh, +and significant help from XeTeX developer Jonathan Kew + +Nota Bene: +---------- +If you include or use a significant part of the synctex package into a software, +I would appreciate to be listed as contributor and see "SyncTeX" highlighted. + +Version 1 +Thu Jun 19 09:39:21 UTC 2008 + */ #ifndef __SYNCTEX_PARSER__ # define __SYNCTEX_PARSER__ -/* synctex_node_t is the type for all synctex nodes */ +/* 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 + * 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; @@ -50,28 +68,33 @@ extern "C" { #endif /* This is the designated method to create a new synctex scanner object. - * name can be the tex file that originated the synctex file. - * The ".tex" file extension is removed and replaced by the proper extension. + * 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_scanner_t synctex_scanner_new_with_output_file(const char * output); /* This is the designated method to delete a synctex scanner object. + * Frees all the memory. */ void synctex_scanner_free(synctex_scanner_t scanner); -/* Display all the information contains in the scanner object. - * If the records are too numerous, they are not displayed. +/* 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. 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 coordinate of a node would require + 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) - Getting its width would simply require + Getting its TeX width would simply require synctex_node_box_width(node)*synctex_scanner_magnification(scanner) + but direct methods are available for that below. */ int synctex_scanner_x_offset(synctex_scanner_t scanner); int synctex_scanner_y_offset(synctex_scanner_t scanner); @@ -80,14 +103,21 @@ 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 * - * if(input_node = synctex_scanner_input(scanner)){ + * if((input_node = synctex_scanner_input(scanner))){ * do { * blah - * } while(input_node=synctex_node_sibling(input_node)); + * } 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. */ const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag); int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name); @@ -99,7 +129,7 @@ const char * synctex_scanner_get_synctex(synctex_scanner_t scanner); * 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 pf type sheet. + * 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, @@ -109,12 +139,13 @@ const char * synctex_scanner_get_synctex(synctex_scanner_t scanner); * This allows to navigate through all the nodes of a given sheet node: * * synctex_node_t node = sheet; - * while(node = synctex_node_next(node)) { + * while((node = synctex_node_next(node))) { * // do something with node * } * - * With synctex_sheet_content, you can retrieve the sheet node at index page. - * whereas 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); @@ -144,13 +175,15 @@ typedef enum { 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 */ +/* 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. + * 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); @@ -163,13 +196,16 @@ int synctex_node_column(synctex_node_t node); 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. */ float synctex_node_h(synctex_node_t node); float synctex_node_v(synctex_node_t node); float synctex_node_width(synctex_node_t node); /* For all nodes, dimensions of the enclosing box. - * A box is enclosing itself.*/ + * These are expressed in page 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); @@ -177,7 +213,9 @@ 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. + * 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); @@ -185,7 +223,8 @@ 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. + * 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); @@ -199,16 +238,16 @@ float synctex_node_box_visible_depth(synctex_node_t node); * * if(synctex_display_query(scanner,name,line,column)>0) { * synctex_node_t node; - * while(node = synctex_next_result(scanner)) { + * while((node = synctex_next_result(scanner))) { * // do something with node * ... * } * } * - * Given the page and the position, synctex_edit_query returns the number of nodes + * 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_display_query(scanner,page,h,v)>0) { + * if(synctex_edit_query(scanner,page,h,v)>0) { * synctex_node_t node; * while(node = synctex_next_result(scanner)) { * // do something with node @@ -217,9 +256,13 @@ float synctex_node_box_visible_depth(synctex_node_t node); * } * * page is 1 based - * h and v are counted relative to the top left corner of the page. + * 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); @@ -228,6 +271,8 @@ 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. */ typedef struct __synctex_updater_t _synctex_updater_t; typedef _synctex_updater_t * synctex_updater_t; |