New `start` attribute for `marker-reference` and deprecate `start-offset`

[bertfrees]

The specification of start-offset is quite complex IMO, but yet it does not provide the ultimate generic solution for any marker search.

The start-offset attribute offsets the start of the search by the specified number of pages. This applies irrespectively of the scope of the search.

By default, the search begins on the page where the marker-reference element is placed. The search, once combined with a non-zero start-offset, could start on a non-existing page. If the search direction is the same as the offset direction, the search would never hit an existing page and the empty string is returned. However, if the search direction is opposite to the offset direction, the search could eventually hit an existing page. Depending on the scope, the following applies in this particular situation:

page-content

return the empty string

page

return the empty string

spread

if the current page belongs to the same spread as the page with the specified offset (had it existed), start the search on the first existing page in the search direction, otherwise return the empty string

sheet

if the current page belongs to the same sheet as the page with the specified offset (had it existed), start the search on the first existing page in the search direction, otherwise return the empty string

sequence

start the search on the first existing page in the search direction

volume

start the search on the first existing page in the search direction

document

start the search on the first existing page in the search direction

The specific use case I have in mind, that is not supported, is to do a marker search within the current volume, going forward from the first page of the volume, or going backward from the last page of the volume.

From the specification it seems (I haven't actually tested it) that for scopes sequence, volume and document, starting on a page that is not within the scope does not automatically result in an empty result, so you could use a very high (negative resp. positive) offset, so that you can be sure that you start on a page that is in one of the previous resp. next volumes, or does not exist, and so that you eventually hit the first resp. last page of the current volume.

However, "using a very high number" feels like a bit of a hack.

Another issue with the specification is that it is not clear where the search starts for the various scopes (unless I didn't read properly, please correct me if I missed something).

I think things could be improved / made more explicit by replacing the attribute with a more general start, that takes either a keyword, or an integer number like start-offset, to maintain backward compatibility. We would deprecate start-offset.

Valid keywords would be:

• begin-of-scope (default for forward)
• begin-of-page
• end-of-page (default for backward)
• end-of-scope

Instead of:

<marker-reference marker="foo" scope="volume" start-offset="10000" direction="backward"/>

I could then use:

<marker-reference marker="foo" scope="volume" start="end-of-scope" direction="backward"/>

[PaulRambags]

Hoi Bert, Jij schrijft hieronder: * that takes either a keyword, or an integer number like start-offset, Bedoel je wellicht: * that takes either a keyword like start-offset, or an integer number, Ik heb al langere tijd niets van me laten horen... mijn excuses daarvoor. Ik was bezig met een project "Zwartdruk bij braille" om een PDF te genereren bij een braille en Dedicon heeft besloten dat dit project naar volgend jaar wordt doorgeschoven (dat andere zaken belangrijker zijn nu). Maar ik voel me toch een beetje schuldig t.o.v. jou, want er zijn momenten dat ik wél aan de Pipeline mag werken en dan heb ik jou vaak nodig. En nu dus een tijdje niet. Zo ben jij overgeleverd aan de grillen van Dedicon. Ik had jou daar beter van op de hoogte kunnen stellen. Sorry. Groetjes, Paul From: Bert Frees ***@***.***> Sent: Friday, November 29, 2024 3:08 PM To: mtmse/obfl ***@***.***> Cc: Subscribed ***@***.***> Subject: [mtmse/obfl] New `start` attribute for `marker-reference` and deprecate `start-offset` (Issue #37) The specification of start-offset<https://mtmse.github.io/obfl/obfl-specification.html#L1333> is quite complex IMO, but yet it does not provide the ultimate generic solution for any marker search. The start-offset attribute offsets the start of the search by the specified number of pages. This applies irrespectively of the scope of the search. By default, the search begins on the page where the marker-reference element is placed. The search, once combined with a non-zero start-offset, could start on a non-existing page. If the search direction is the same as the offset direction, the search would never hit an existing page and the empty string is returned. However, if the search direction is opposite to the offset direction, the search could eventually hit an existing page. Depending on the scope, the following applies in this particular situation: page-content return the empty string page return the empty string spread if the current page belongs to the same spread as the page with the specified offset (had it existed), start the search on the first existing page in the search direction, otherwise return the empty string sheet if the current page belongs to the same sheet as the page with the specified offset (had it existed), start the search on the first existing page in the search direction, otherwise return the empty string sequence start the search on the first existing page in the search direction volume start the search on the first existing page in the search direction document start the search on the first existing page in the search direction The specific use case I have in mind, that is not supported, is to do a marker search within the current volume, going forward from the first page of the volume, or going backward from the last page of the volume. From the specification it seems (I haven't actually tested it) that for scopes sequence, volume and document, starting on a page that is not within the scope does not automatically result in an empty result, so you could use a very high (negative resp. positive) offset, so that you can be sure that you start on a page that is in one of the previous resp. next volumes, or does not exist, and so that you eventually hit the first resp. last page of the current volume. However, "using a very high number" feels like a bit of a hack. Another issue with the specification is that it is not clear where the search starts for the various scopes (unless I didn't read properly, please correct me if I missed something). I think things could be improved / made more explicit by replacing the attribute with a more general start, that takes either a keyword, or an integer number like start-offset, to maintain backward compatibility. We would deprecate start-offset. Valid keywords would be: * begin-of-scope (default for forward) * begin-of-page * end-of-page (default for backward) * end-of-scope Instead of: <marker-reference marker="foo" scope="volume" start-offset="10000" direction="backward"/> I could then use: <marker-reference marker="foo" scope="volume" start="end-of-scope" direction="backward"/> - Reply to this email directly, view it on GitHub<#37>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AHDZKI6VHVTLKBPY3YKETYL2DBYLZAVCNFSM6AAAAABSXGBND2VHI2DSMVQWIX3LMV43ASLTON2WKOZSG4YDKMRSGY2TSMQ>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.******@***.***>> DISCLAIMER: De informatie verzonden met dit e-mail bericht is uitsluitend bestemd voor de geadresseerde. Indien u niet de beoogde geadresseerde bent, verzoeken wij u vriendelijk dit aan de afzender te melden (of via: ***@***.******@***.***>) en het origineel en eventuele kopieën te verwijderen. The information sent in this e-mail is solely intended for the individual or company to whom it is addressed. If you received this message in error, please notify the sender immediately (or mail to ***@***.******@***.***>) and delete the original message and possible copies.