Fix forward SyncTex accuracy in internal browser by providing a range location indication alternative

[pyk1998]

This proposed solution for issue #4168 involves implementing a range indicator in the PDF viewer based on the line position in the editor. The solution includes several major modifications:

• Adding a configuration option to choose the indicator type between indicating a single location or a range.
• Ignoring the column parameter when invoking the SyncTex binary when indicating a range.
• Parsing all the SyncTex binary records and extracting the box (rectangle) coordinates.
• Handling the list of records in the viewer, calculating the rectangular coordinates, and displaying them.
• Adding CSS animation to show the corresponding area in the PDF.

To use this solution, follow these steps:

• Uncheck the configuration option latex-workshop.synctex.synctexjs.enabled.
• Choose the Range option in the latex-workshop.synctex.indicator.type configuration.

By implementing these changes, the PDF viewer will display a range rectangular indicator that corresponds to the selected line in the editor.

[James-Yu]

Thanks for the contribution. Before looking into the implementation (which is good, just a few function merges to comply with the practice), may I know if this feature is portable to synctex.js?

@jlelong It looks like the binary is still providing a bit more info about the location over synctex.js, making #4186 valid. What do you think of adopting a priority of execution (binary > javascript) to balance utility (binary) and availability (js as fallback)?

[pyk1998]

@James-Yu Thank you for the review. If there's any modification needed, please let me know. I'm very happy to have a chance learning from the community.

I've checked the related code, it looks also possible to apply the same logic to synctex.js.

By default, the forward search in synctex.js also returns a single location:

LaTeX-Workshop/src/locate/synctex/worker.ts

Lines 75 to 90 in 2128e1e

	for (const b of blocks as Block[]) {
	// Skip a block if they have boxes inside, or their type is kern or rule.
	// See also https://github.com/jlaurens/synctex/blob/2017/synctex_parser.c#L4655 for types.
	if (b.elements !== undefined || b.type === 'k' || b.type === 'r') {
	continue
	}
	cBottom = Math.max(b.bottom, cBottom)
	const top = b.bottom - b.height
	cTop = Math.min(top, cTop)
	cLeft = Math.min(b.left, cLeft)
	if (b.width !== undefined) {
	const right = b.left + b.width
	cRight = Math.max(right, cRight)
	}
	}
	return new Rectangle({ top: cTop, bottom: cBottom, left: cLeft, right: cRight })

However, it constains a lot of low-level code handling blocks in synctex file:

LaTeX-Workshop/src/locate/synctex/worker.ts

Lines 156 to 176 in 2128e1e

	const linePageBlocks = pdfSyncObject.blockNumberLine[inputFilePath]
	const lineNums = Object.keys(linePageBlocks).map(x => Number(x)).sort( (a, b) => { return (a - b) } )
	const i = lineNums.findIndex( x => x >= line )
	if (i === 0 || lineNums[i] === line) {
	const l = lineNums[i]
	const blocks = getBlocks(linePageBlocks, l)
	const c = toRect(blocks)
	return { page: blocks[0].page, x: c.left + pdfSyncObject.offset.x, y: c.bottom + pdfSyncObject.offset.y, indicator: true }
	}
	const line0 = lineNums[i - 1]
	const blocks0 = getBlocks(linePageBlocks, line0)
	const c0 = toRect(blocks0)
	const line1 = lineNums[i]
	const blocks1 = getBlocks(linePageBlocks, line1)
	const c1 = toRect(blocks1)
	let bottom: number
	if (c0.bottom < c1.bottom) {
	bottom = c0.bottom * (line1 - line) / (line1 - line0) + c1.bottom * (line - line0) / (line1 - line0)
	} else {
	bottom = c1.bottom
	}

To me, it is not as intuitive to modify them as simply invoking the binary. I will try to analyze them.

[pyk1998]

Having tried to modifed synctex.js with no luck.
Maybe the low-level synctex block handling code seems to be incomplete?

According to the comment, the synctex.js seems not handling all the blocks:

LaTeX-Workshop/src/locate/synctex/worker.ts

Lines 75 to 77 in 2128e1e

	for (const b of blocks as Block[]) {
	// Skip a block if they have boxes inside, or their type is kern or rule.
	// See also https://github.com/jlaurens/synctex/blob/2017/synctex_parser.c#L4655 for types.

A similar but more complete parser is the one used in SumatraPDF:
https://github.com/sumatrapdfreader/sumatrapdf/blob/85a0fa0f09d729e06c7f6e14bf55445723fe0304/ext/synctex/synctex_parser.c#L3310-L3429

(Note that the latest parser used in https://github.com/jlaurens/synctex/blob/main/synctex_parser.c have changed from these two greatly.)

This caused the record returned from the synctex.js is not enough for viewer showing the range of the forward syntex location.
From my simple opinon, using the binary directly is more convenient and easy to maintenance.

[jlelong]

@jlelong It looks like the binary is still providing a bit more info about the location over synctex.js, making #4186 valid. What do you think of adopting a priority of execution (binary > javascript) to balance utility (binary) and availability (js as fallback)?

I agree that we can change the order and put the binary first and only keep the js implementation as a fallback.

[James-Yu]

Thank you very much for this contribution. Please consider the general requests on code structure.

[pyk1998]

@James-Yu Thank you so much for the detailed and kind advice. I have tried my best to merge the functions and types. However, I found that the forwardSynctex seems a lot different from forwardSynctexRange from both parameters and internal logic. I think we can jut let them separate?

[pyk1998]

@James-Yu I have also tried to merge forwardSynctexRange with forwardSynctex in viewer in the latest commit. Please kindly review all the refactors.

[James-Yu]

Thanks for the changes. Will review soon (but not too soon).

[pyk1998]

@James-Yu I think I have changed the code according to the comments. Any further updates?

[James-Yu]

Not having time to touch this. There are indeed a few issues with code style, yet I will directly commit to the PR shortly.

[pyk1998]

@James-Yu Thank you so much for the abundant and kind work on the code style. I've really got so many lessons to learn from the followed up commits. Thank you again for the maintanence of such great extension, and I am so happy having a chance to participate. Wish you all the best.