search

usfm-bible / tcdocs

Technical Committee Documents
Other
9 stars 9 forks source link

User extensions #58

Open jonathanrobie opened 5 months ago

jonathanrobie commented 5 months ago

https://docs.usfm.bible/usfm-usx-docs/latest/extensions.html

Any 'private-use' marker/style extensions should begin with z. Example: \zMyPara or . Markers/styles in the z namespace are not considered part of the USFM/USX standard. An application or processor may provided support for z extensions, but are not expected to handle the markup or its associated text in any particular way, and are also free to ignore this markup when it is encountered in a text.

This does not tell me how to define a new extension. I can't find the place in the specification that tells me that.

In particular, is there a way to define a new element and say where it can be used?

jwickberg commented 5 months ago

Maybe related to this is that we currently have properties of different markers included in the documents, but the current grammar doesn't include anything for those.

Maybe we need a modified version of the usfm_sb.sty file - probably with a different name since it will have a different purpose - that would only include the properties of markers. A version of this file could be specified as a way to create custom markers. We have said we could just \def to define custom markers for the parser, but I think we would still need a way to specify more marker properties.

jonathanrobie commented 5 months ago

What needs to be defined for custom markers? I could imagine:

  1. Where it can occur.
  2. What attributes it requires / permits

I would like to keep formatting out of this.

mhosken commented 5 months ago
  1. structure. Is it a milestone or a note or a char style that must be closed, or a paragraph style.
  2. Subcategories for other Processing: Section head versus verse text. This is not styling. For example we need to know if a paragraph is a section head to associate it forwards or backwards for referencing. Likewise whether a paragraph contains verse text or not.

I also do not want to see visual styling as part of this spec.

On Mon, 12 Feb 2024, 19:38 Jonathan Robie, @.***> wrote:

What needs to be defined for custom markers? I could imagine:

  1. Where it can occur.
  2. What attributes it requires / permits

I would like to keep formatting out of this.

— Reply to this email directly, view it on GitHub https://github.com/usfm-bible/tcdocs/issues/58#issuecomment-1939421174, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABLMO3OM4AHISWUG4GS423DYTJVTDAVCNFSM6AAAAABDFHICZWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMZZGQZDCMJXGQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>

jwickberg commented 5 months ago

We are all agreed that formatting should not be included - I was just referencing the existing file as a starting point. \Marker w \Endmarker w* \Name w...w* - Peripheral Ref - Wordlist Entry \Description A wordlist text item \TextType VerseText \TextProperties publishable vernacular \StyleType Character \Attributes ?lemma ?strong ?srcloc Maybe these are the properties we would want. EndMarker is standard, so could be left off. Name and Description are useful for applications displaying the styles as choices.

jonathanrobie commented 5 months ago

We are all agreed that formatting should not be included - I was just referencing the existing file as a starting point.

Is there solid documentation for that format? If not, could you please write a description of this format so I'm sure I am seeing what is there?

klassenjm commented 5 months ago

This is the best I can point to for docs on the PT stylesheet (.sty) and the properties used in it.

https://github.com/ubsicap/usfm/tree/master/sty

klassenjm commented 5 months ago

Ignoring formatting properties in that list, things like \TextType, \TextProperties, \StyleType (marker), \Name, \Description could be things we would want to try to capture within a \def statement -- perhaps? The \OccursUnder and \Rank are things captured now in the grammar (I believe).

KentSpiel commented 5 months ago

Defining extensions is important, however I am wondering how to include these specification in a USFM document. Right now they are defined in a style sheet which is not part of the specification. Style sheets are a Paratext specific feature, and apply to all the documents in a project. I do not think we should make Paratext style sheets a formal part of the specification. It seems to me the best solution is to add an extension header to any USFM documents that use extended markup. The Paratext style sheet, either custom.sty or a bespoke variation of usfm.sty, would then need to access/mirror the header structural information and add formatting information for display. Questions:

mhosken commented 3 months ago

markers.ext has been specified and we generate a file usfm.ext which has the structure for all the USFM markers in the grammar directory. This needs to be documented in docs.usfm.bible @klassenjm

klassenjm commented 1 month ago

See update: https://docs.usfm.bible/usfm-usx-docs/latest/extensions.html

@mhosken

  1. The docs currently indicate that for makers with more than one attribute, an \attribute field should be provided for each. Is that correct? Or, do we want to specify one \attributes field instead, with a list.

  2. How do we plan to specify a default attribute, or a required attribute. The following syntax could be used to indicate that x-myattr1 is default.

    \attributes *x-myattr1

    The following syntax could be used to indicate that x-myattr2 is optional.

    \attributes *x-myattr1 ?x-myattr2