HRGT moustache profile (documentatie)

[RieksJ]

Het is de bedoeling dat voor TEv2 tools die teksten converteren, zoals de TRRT en HRGT, een 'moustache profile' is gedefinieerd, d.w.z. een verzameling van moustache-variabelen die door de interpreter van waardes worden voorzien. Voor de TRRT bevat het profiel de variabelen {{showtext}}, {{termType}}, {{term}}, {{trait}}, {{scopetag}}, {{vsntag}}.

Door dit te documenteren kunnen gebruikers hun eigen interpreters maken die aansluiten op bestaande converters.

De documentatie van dit profiel voor de HRGT ontbreekt op dit moment. Ik zie verschillende mogelijkheden:

1. {{scopetag}}, {{vsntag}}, {{paramlist}}
2. {{scopetag}}, {{vsntag}}, {{converter}}, {{sort}}

@Ca5e : heb jij nog andere ideeen? Zo ja, wat zijn die? Welke van jouw/mijn ideeen zijn geimplementeerd c.q. zouden moeten zijn geimplementeerd?

[Ca5e]

De waarden voor de TRRT komen overeen met hetgeen dat ooit is bedacht voor de regex, met daarbij type toegevoegd. Dit zijn de zes: [showtext](type:id#trait@scopetag:vsntag]. termType en term, zoals die hierboven zijn genoemd, zijn natuurlijk wel beschikbaar in de converters als eigenschappen van een MRG entry. Het lijkt me niet helemaal correct om de eigenschappen van een term direct te schrijven als moustache variabele (dus omringd door de dubbele accolades), gezien dit alleen als notatie in de converter van toepassing is en nog niet in de interpreter.

Voor de HRGT, en dus de beschikbare eigenschappen van een MRGRef, heb ik op dit moment gekozen voor hrg, converter, sorter, scopetag en vsntag. Hierbij wordt als named capturing group eerst de waarde voor hrg opgeslagen en wordt deze later gesplitst om ook tot scopetag en vsntag te komen. Iets als paramlist zal nieuwe mogelijkheden kunnen bieden als het gaat om het toevoegen van eigenschappen aan een MRGRef die niet beschreven staan, maar daarna wel gebruikt kunnen worden in een converter. Het nadeel is hierbij dat er wel een specifieke notering vastgelegd moet worden waarin we duidelijk maken hoe de paramlist dan weer geinterpreteerd wordt.

Door het bovenstaande verhaal zie ik wel de kracht in functionaliteit om alle named capturing groups uit een interpreter, die niet per se gedocumenteerd hoeven te zijn, ook toe te voegen als eigenschap van een term of MRGRef. Wat er op z'n plaats weer voor zorgt dat deze eigenschappen gebruikt kunnen worden in een zelfgeschreven converter. Iets als paramlist wordt volgens mij dan onnodig.

[RieksJ]

Waar dit op neer komt is een verduidelijking van het generieke conversieproces. Op dit moment is (min of meer) beschreven dat een importer een textje vindt (een termref of mrgref), daar (moustache) variabelen uit haalt, en dat de converter op basis daarvan (en andere spullen) een replacement-tekst, en dat het gevonden tekstje dan met de replacement-tekst wordt vervangen.

Het lijkt erop dat we dit moeten verduidelijken tot iets als:

• de importer vindt een tekstje, en haalt daar waardes uit voor een aantal capturing-groups (het 'import profiel' is de verzameling van deze capturing groups).
• er vindt een verwerking plaats, waarbij een 'converter profiel' wordt geconstrueerd, d.w.z. een verzameling moustache variabelen waarvan de waardes voor converters beschikbaar komen.
• de converter construeert een replacement tekst op basis van het converter profiel.

Elke tool die dit idee gebruikt (HRGT, TRRT) moet dan specificeren:

• wat het import profiel is (de capturing groups);
• wat het converter profiel is (d.w.z. de velden van de gevonden MRG entry, en voor de HRGT ook de variabelen {{mrg.terminology.xxxx}} )
• hoe de waardes van variabelen uit het converter profiel hun waardes krijgen obv het import profiel. Daaronder hoort onder meer het opzoeken van MRG entries, en het geven van default waardes aan moustache variabelen als dat nodig zou zijn.

Mee eens?

[Ca5e]

Het volgende zou ik als een correcte beschrijving zien.

• De interpreter wordt gebruikt om teksten te doorzoeken, stukken die overeenkomen met de regexes worden door de interpreter verwerkt aan de hand van named capturing groups. De named capturing groups die geïnterpreteerd worden door de tool, zouden we als het interpreter profiel kunnen beschouwen. De interpreter levert een object met eigenschappen van de geïnterpreteerde named capturing groups, mogelijk zouden we dit resulterende object juist als interpreter profiel kunnen zien.
• Verdere verwerking levert een converter profiel op, die ook het resultaat van de interpreter bevat. Dit profiel wordt doorgegeven aan de converter, waarbij de moustache expressies kunnen verwijzen naar eigenschappen van het doorgegeven profiel. Het zijn dus niet de moustache expressies die beschikbaar zijn, maar de eigenschappen van het profiel object.
• De converter levert na compileren een tekst die weggeschreven kan worden als vervanging van de oorspronkelijke tekst.

Er zou dan per tool beschreven kunnen worden wat de profielen bevatten en watvoor mogelijke verwerking er gedaan wordt (zoals showtext naar id omzetten en defaulttype instellen).

Door het bovenstaande verhaal zie ik wel de kracht in functionaliteit om alle named capturing groups uit een interpreter, die niet per se gedocumenteerd hoeven te zijn, ook toe te voegen als eigenschap van een term of MRGRef. Wat er op z'n plaats weer voor zorgt dat deze eigenschappen gebruikt kunnen worden in een zelfgeschreven converter. Iets als paramlist wordt volgens mij dan onnodig.

Wat vind je verder van het bovenstaande @RieksJ? Dit zou er dus voor zorgen dat de output van de interpreter naast de standaard showtext, id, type, trait, scopetag en vsntag, in het geval van de TRRT, simpelweg alle named capturing groups beschikbaar maakt.

[RieksJ]

Dat klinkt goed. We zouden dan kunnen zeggen dat:

• elke interpreter een regex is, waarmee een tekst-patroon gezocht kan worden en een zekere vz. named capturing populeert.

• elke tool

  • een interpreter-profiel heeft, i.e., de vz. van named capturing groups die interpreters geacht worden te populeren). De specs documenteren dit profiel.
  • een converter-profiel heeft, i.e., de vz van moustache-variabelen op basis waarvan converters teksten construeren en daarmee het door een interpreter aangewezen tekst-patroon vervangen. Deze variabelen komen niet alleen uit de (bewerkte - bijv. door lege waardes te vervange door defaults, of combinaties van groepen te maken) named capturing groups, maar ook uit andere bronnen, zoals een MRG-entry of de 'terminology'-sectie van de MRG. De specs documenteren ook dit profiel. Merk op dat niet alle named capturing groups een moustache variabele hoeven te hebben met dezelfde naam.

• elke converter op basis van een converter-profiel een tekst construeert, die de tool (waarin de converter wordt gebruikt) gebruikt om een gevonden tekst-patroon mee te vervangen.

[RieksJ]

@Ca5e Zou je de generieke documentatie hierover, en ook de specifieke documentatie van de HRGT en de TRRT willen nalopen en zien of die specificaties met de implementatie overeenkomen (d.w.z. de specs zijn compleet, consistent en zo, en de implementatie heeft geen 'extraatjes' die niet zijn gespecificeerd)?

[Ca5e]

The documentation of the TRRT, HRGT, and converter profile have just been adjusted slightly. The update is failing within the deploy workflow because the bot that commits updated MRG's doesn't have a verified signature, which now seems to be required within the repo (repository rule violations). I believe there are solutions, but this should be part of another issue. I'll close this for now as the converter profile documentation now seems adequate.