summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/synctexdir/synctex_parser.h
diff options
context:
space:
mode:
authorJonathan Kew <jfkthame@googlemail.com>2008-06-21 00:42:36 +0000
committerJonathan Kew <jfkthame@googlemail.com>2008-06-21 00:42:36 +0000
commita833f19836b8e188ce94d82473439714b50f6853 (patch)
tree7c93c7dfa09f14c61cf13933ac80164198fd0241 /Build/source/texk/web2c/synctexdir/synctex_parser.h
parentc6e0b21f3b6f248c5d57cb61fb0fa545ec329189 (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.h93
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;