Šķîþ ţö ḿàîñ çöñţéñţ

É-02: Ţĥé ƒöŕḿàţ šýšţéḿ

Šüḿḿàŕý​

Ƒöŕḿàţš àŕé þļüĝĝàƃļé ŕéàđéŕš àñđ ŵŕîţéŕš ţĥàţ çöñṽéŕţ ƃéţŵééñ öñ-đîšķ ŕéþŕéšéñţàţîöñš àñđ ţĥé Þàŕţ šţŕéàḿ. Ţĥé ƒŕàḿéŵöŕķ šĥîþš à ƃŕöàđ šéţ öƒ ƃüîļţ-îñ ƒöŕḿàţš üñđéŕ core/formats/, éàçĥ îḿþļéḿéñţîñĝ DataFormatReader àñđ DataFormatWriter öñ ţöþ öƒ šĥàŕéđ BaseFormatReader / BaseFormatWriter éḿƃéđš. À šîñĝļé FormatRegistry éẋþöšéš à ƒàçţöŕý-ƃàšéđ ļööķüþ ţĥàţ šéŕṽéš ƃüîļţ-îñ àñđ þļüĝîñ ƒöŕḿàţš üñîƒöŕḿļý. Đéţéçţîöñ çàšçàđéš ţĥŕöüĝĥ éẋţéñšîöñ, þŕîöŕîţý, àñđ çöñţéñţ šñîñĝ. Ƃýţé-éẋàçţ ŵŕîţé-ƃàçķ ŕîđéš öñé šķéļéţöñ šţöŕé ţĥàţ éṽéŕý ŕéàđéŕ àñđ ŵŕîţéŕ þàîŕ ŵîŕéš ţĥé šàḿé ŵàý, àñđ à ŕéàđéŕ çļàššîƒîéš îţš îñþüţ ţĥŕéé ŵàýš: ţŕàñšļàţàƃļé çöñţéñţ, þüŕé šţŕüçţüŕé, àñđ ñöñ-ţŕàñšļàţàƃļé-ƃüţ-ḿéàñîñĝƒüļ çöñţéẋţ ţĥàţ ţĥé ŕéàđéŕ šüŕƒàçéš ţö ţööļš.

Çöñţéẋţ​

Ţĥé ƒŕàḿéŵöŕķ ḿüšţ ŕéàđ à ļàŕĝé ṽàŕîéţý öƒ ƒîļé ƒöŕḿàţš àñđ ŵŕîţé ţĥéḿ ƃàçķ ŵîţĥ ƃýţé-éẋàçţ ƒîđéļîţý: éṽéŕý ñéŵļîñé, éṽéŕý éñţîţý ŕéƒéŕéñçé, éṽéŕý àţţŕîƃüţé ǫüöţé šţýļé. Ƒöŕḿàţš ṽàŕý ŵîđéļý îñ šţŕüçţüŕé: ļîñéàŕ ţéẋţ (þļàîñ ţéẋţ, Ḿàŕķđöŵñ), ţŕéé-šţŕüçţüŕéđ ḿàŕķüþ (ĤŢḾĻ, ẊḾĻ, ÖþéñẊḾĻ), ļîñé-öŕîéñţéđ ķéý-ṽàļüé (Ĵàṽà þŕöþéŕţîéš, Àþþļé šţŕîñĝš), ĝŕîđ-ƃàšéđ (ÇŠṼ, šþŕéàđšĥééţš), àñđ éẋçĥàñĝé-šþéçîƒîç (ẊĻÎƑƑ, ŢḾẊ, Ĝéţţéẋţ).

Ƒöŕḿàţš àļšö ƒŕéǫüéñţļý çöñţàîñ éḿƃéđđéđ çöñţéñţ îñ àñöţĥéŕ ƒöŕḿàţ (ĤŢḾĻ îñšîđé ĴŠÖÑ, Ḿàŕķđöŵñ îñšîđé ÇŠṼ), àñđ ţĥé ŕéàđéŕ/ŵŕîţéŕ çöñţŕàçţ ḿüšţ àççöḿḿöđàţé ţĥàţ ŕéçüŕšîöñ ŵîţĥöüţ šþéçîàļ çàšéš.

À šéçöñđ çöñšüḿéŕ çöḿþļîçàţéš ţĥé þîçţüŕé. Ţĥé ţŕàñšļàţîöñ þàţĥ ŵàñţš öñļý ţĥé þŕöšé à ĥüḿàñ ŵöüļđ ţŕàñšļàţé; ḿöđéļ îñĝéšţîöñ ŵàñţš àļļ ţéẋţüàļ çöñţéẋţ: çöđé ļîšţîñĝš, çàþţîöñš, àļţ-ţéẋţ, ƒöŕḿüļàš, đö-ñöţ-ţŕàñšļàţé šţŕîñĝš, çöñƒîĝ-éẋçļüđéđ ṽàļüéš, àñđ çöḿḿéñţš. À ţŵö-ŵàý çļàššîƒîçàţîöñ, ŵĥéŕé à ƒŕàĝḿéñţ ƃéçöḿéš éîţĥéŕ à ţŕàñšļàţàƃļé Ƃļöçķ öŕ öþàǫüé šķéļéţöñ ƃýţéš, ḿàķéš éṽéŕýţĥîñĝ ţĥé ƒîŕšţ çöñšüḿéŕ šķîþš îñṽîšîƃļé ţö ţĥé šéçöñđ.

Đéçîšîöñ​

Ŕéàđéŕ àñđ ŵŕîţéŕ îñţéŕƒàçéš​

Ţĥéšé îñţéŕƒàçéš îḿþļéḿéñţ ţĥé file šöüŕçé àñđ šîñķ ƃîñđîñĝ îñ É-04. Öţĥéŕ ƃîñđîñĝš (ţĥé þŕöĵéçţ šţöŕé, à .kpz ŵöŕķšþàçé, îñţéŕçĥàñĝé îḿþöŕţ/éẋþöŕţ) ƒééđ àñđ đŕàîñ ţĥé šàḿé Part šţŕéàḿ ŵîţĥöüţ à ŕéàđéŕ öŕ ŵŕîţéŕ, šö à ƒļöŵ îš àĝñöšţîç ţö ŵĥéŕé îţš çöñţéñţ éñţéŕš àñđ ļéàṽéš.

Éàçĥ îñţéŕƒàçé îš à çöḿþöšîţîöñ öƒ ñàŕŕöŵ ƒàçéţš, šö à çöñšüḿéŕ ţĥàţ öñļý ñééđš ţö îđéñţîƒý à ƒöŕḿàţ, öŕ öñļý ţö àþþļý çöñƒîĝüŕàţîöñ, çàñ đéþéñđ öñ ţĥàţ ƒàçéţ àļöñé:

type DataFormatReader interface {
    FormatDescriptor // Name, DisplayName, Signature
    Configurable     // Config, SetConfig
    PartReader       // Open, Read, Close
}

type DataFormatWriter interface {
    Name() string
    OutputSink // SetOutput(path), SetOutputWriter(io.Writer)
    SetLocale(locale model.LocaleID)
    SetEncoding(encoding string)
    PartWriter // Write, Close
}

Ţĥé ŕéàđéŕ ļîƒéçýçļé îš Open → Read → Close. Open àţţàçĥéš ţĥé ŕéàđéŕ ţö à model.RawDocument (ŕàŵ ƃýţéš öŕ à šţŕéàḿîñĝ ŕéàđéŕ, þļüš ḿéţàđàţà šüçĥ àš šöüŕçé ļöçàļé àñđ ƒîļé þàţĥ). Read ŕéţüŕñš à çĥàññéļ öƒ model.PartResult{Part, Error}: ţĥé ŕéàđéŕ þŕöđüçéš Þàŕţš üñţîļ ţĥé đöçüḿéñţ îš éẋĥàüšţéđ öŕ àñ éŕŕöŕ öççüŕš, ţĥéñ çļöšéš ţĥé çĥàññéļ. Close ŕéļéàšéš ĥéļđ ŕéšöüŕçéš.

Ţĥé ŵŕîţéŕ ļîƒéçýçļé îš SetOutput → Write → Close. Write çöñšüḿéš à çĥàññéļ öƒ *model.Part üñţîļ ţĥé çĥàññéļ çļöšéš, þŕöđüçîñĝ öüţþüţ öñ ţĥé ŵŕîţéŕ'š đéšţîñàţîöñ.

Éṽéŕý ŕéàđ àñđ ŵŕîţé ŕüñš îñšîđé à šþàñ öñ ţĥé ƒŕàḿéŵöŕķ'š öƃšéŕṽàţîöñ šéàḿ (format.read, format.write; É-01), ŵĥîçĥ îš à ñö-öþ üñļéšš à ĥöšţ ŕéĝîšţéŕš à ţŕàçéŕ.

ƂàšéƑöŕḿàţŔéàđéŕ àñđ ƂàšéƑöŕḿàţŴŕîţéŕ​

BaseFormatReader àñđ BaseFormatWriter þŕöṽîđé šĥàŕéđ ƃéĥàṽîöüŕ ţĥàţ çöñçŕéţé ƒöŕḿàţš éḿƃéđ:

  • Đöçüḿéñţ-ļéṽéļ Ļàýéŕ ƃŕàçķéţîñĝ (PartLayerStart/PartLayerEnd ƒöŕ ţĥé ŕööţ đöçüḿéñţ ļàýéŕ)
  • Ļöçàļé ḿéţàđàţà þŕöþàĝàţîöñ àñđ šöüŕçé/ţàŕĝéţ ļöçàļé àççéššöŕš
  • Çöñšîšţéñţ éŕŕöŕ ĥàñđļîñĝ àñđ çĥàññéļ ļîƒéçýçļé

À çöñçŕéţé ƒöŕḿàţ îḿþļéḿéñţš ţĥé ƒöŕḿàţ-šþéçîƒîç þàŕšîñĝ àñđ šéŕîàļîžàţîöñ àñđ đéļéĝàţéš ļîƒéçýçļé ţö ţĥé ƃàšé éḿƃéđ.

À đöçüḿéñţ'š çĥàŕšéţ îš šéţţļéđ öñçé, àţ ţĥé îñĝéšţîöñ šéàḿ. Éṽéŕý çàļļéŕ ţĥàţ ŕéàđš à đöçüḿéñţ öþéñš îţ ţĥŕöüĝĥ format.OpenDocument, ŵĥîçĥ đéçöđéš ţĥé ƃýţéš ţö ÜŢƑ-8 ƃéƒöŕé ţĥé ŕéàđéŕ šééš ţĥéḿ: à ƃýţé-öŕđéŕ ḿàŕķ ŵîñš, ţĥéñ ţĥé đéçļàŕéđ éñçöđîñĝ (--encoding, ţĥé ŕéçîþé'š defaults.encoding), àñđ ŵîţĥ ñéîţĥéŕ ţĥé ƃýţéš þàšš ţĥŕöüĝĥ àš ÜŢƑ-8. Ţĥé ŕéàđéŕ ŕéçöŕđš ţĥé šéţţļéđ éñçöđîñĝ öñ ţĥé ŕööţ Layer, àñđ à ŕéàđéŕ ŵîţĥ à çĥàŕšéţ ĥéüŕîšţîç öƒ îţš öŵñ (ţĥé ẊḾĻ þŕöļöĝ, ţĥé ÞÖ ĥéàđéŕ) àþþļîéš îţ öñļý ţö à đöçüḿéñţ ţĥé šéàḿ ļéƒţ üñšéţţļéđ. Öñ ţĥé ŵàý öüţ BaseFormatWriter.SetEncoding îñšţàļļš ţĥé ḿàţçĥîñĝ éñçöđéŕ, šö à ŵŕîţéŕ šéŕîàļîšéš ÜŢƑ-8 àñđ ţĥé ƃàšé éñçöđéš ţĥé ŵĥöļé šţŕéàḿ îñ ţĥé ŕüñ'š çĥàŕšéţ. À ƒöŕḿàţ ŵĥöšé ƃýţéš àŕé ñöţ ţéẋţ đéçļàŕéš Binary öñ îţš šîĝñàţüŕé àñđ îţš ŵŕîţéŕ, àñđ ţĥé šéàḿ ĥàñđš îţ ţĥé ƃýţéš àš ţĥéý àŕé. Ţĥé çöñţŕîƃüţöŕ ĝüîđé'š đöçüḿéñţ éñçöđîñĝ šéçţîöñ šţàţéš ţĥé ŕüļé ƒöŕ à ƒöŕḿàţ àüţĥöŕ.

BaseFormatWriter àļšö öŵñš ţĥé šĥàŕéđ ƃýţé-ļéṽéļ öüţþüţ öþţîöñš (format.OutputOptions): output.bom (add|remove|keep), output.newline (lf|crlf|keep), àñđ output.encoding (àñý çĥàŕšéţ îñ core/encoding; àñ éẋþļîçîţ ṽàļüé ŵîñš öṽéŕ ţĥé ŕüñ'š éñçöđîñĝ). Ŕéàđéŕš àļŕéàđý ñöŕḿàļîžé ƂÖḾ àñđ ñéŵļîñéš àţ þàŕšé ţîḿé, šö ţĥéšé éẋîšţ öñļý ţö çöñţŕöļ öüţþüţ šţýļé; ţĥéý àŕé ŵŕîţéŕ çöñƒîĝüŕàţîöñ ŕàţĥéŕ ţĥàñ à þîþéļîñé šţàĝé. Ţĥéý àŕé šéţ üñđéŕ ţĥé ŕéšéŕṽéđ output ķéý öƒ ţĥé öŕđîñàŕý þéŕ-ƒöŕḿàţ çöñƒîĝ (defaults.formats[<id>].config îñ à kapi.yaml ŕéçîþé); format.SplitOutputConfig šţŕîþš ţĥàţ ķéý ƃéƒöŕé þéŕ-ƒöŕḿàţ ŕéàđéŕ/ŵŕîţéŕ çöñƒîĝ îš àþþļîéđ, àñđ ţĥé ƃàšé ŵŕîţéŕ ŵŕàþš îţš öüţþüţ šţŕéàḿ ŵîţĥ ţĥé þöšţ-éñçöđé çĥàîñ (ñéŵļîñé çöñṽéŕšîöñ → ƂÖḾ þöļîçý → çĥàŕšéţ éñçöđîñĝ), šö éṽéŕý ŵŕîţéŕ ţĥàţ éḿƃéđš ţĥé ƃàšé îñĥéŕîţš ţĥé ƃéĥàṽîöüŕ ŵîţĥ ñö þéŕ-ƒöŕḿàţ çöđé.

Ƃüîļţ-îñ ƒöŕḿàţš​

Ţĥé ƃüîļţ-îñ ƒöŕḿàţš üñđéŕ core/formats/ šþàñ šéṽéŕàļ ƒàḿîļîéš:

  • Ḿàŕķüþ: ĤŢḾĻ, ẊḾĻ, Ḿàŕķđöŵñ / ḾĐẊ, ÀšçîîĐöç, àñđ šţŕüçţüŕéđ-đöçüḿéñţ ƒöŕḿàţš.
  • Ţŕàñšļàţîöñ éẋçĥàñĝé: ẊĻÎƑƑ 1.2 / 2.ẋ, ŢḾẊ, Ĝéţţéẋţ ÞÖ/ḾÖ.
  • Šţŕüçţüŕéđ đàţà: ĴŠÖÑ, ÝÀḾĻ, ÇŠṼ/ŢŠṼ, àñđ đéšîĝñ-ţöķéñ àñđ àþþ ḿéššàĝé-çàţàļöĝ ṽàŕîàñţš (xcstrings, arb, i18next, resx, Àñđŕöîđ šţŕîñĝš, Àþþļé šţŕîñĝš, …).
  • Öƒƒîçé àñđ þüƃļîšĥîñĝ: ÖþéñẊḾĻ (.docx, .xlsx, .pptx), ÖĐƑ, ÉÞÜƂ, àñđ ŕéļàţéđ þàçķàĝéđ ƒöŕḿàţš.
  • Šüƃţîţļé àñđ ḿéđîà: ŠŔŢ, ṼŢŢ, þļüš àüđîö, ṽîđéö àñđ îḿàĝé ŕéàđéŕš. ÞĐƑ àñđ šöüŕçé çöđé àŕŕîṽé àš þļüĝîñ ƒöŕḿàţš (kapi-pdfium, kapi-sourcecode; É-05, É-08), ŵîţĥ ţĥéîŕ çöñƒîĝ đéƒîñîţîöñš üñđéŕ core/formats/ šö éàçĥ ƒöŕḿàţ ĥàš öñé šçĥéḿà ŵĥéŕéṽéŕ îţš ŕéàđéŕ ŕüñš.

Ţĥé ƒüļļ, àüţĥöŕîţàţîṽé ļîšţ öƒ ŕéĝîšţéŕéđ ƒöŕḿàţš (ŵîţĥ éẋţéñšîöñš, ḾÎḾÉ ţýþéš, àñđ þéŕ-ƒöŕḿàţ öþţîöñš) îš ţĥé ĝéñéŕàţéđ Ƒöŕḿàţ Ŕéƒéŕéñçé. Îţ îš đéŕîṽéđ ƒŕöḿ ţĥé ļîṽé ŕéĝîšţŕý, šö îţ ñéṽéŕ đŕîƒţš ƒŕöḿ ţĥé çöđé.

À ƒöŕḿàţ þàçķàĝé üñđéŕ core/formats/<name>/ ţýþîçàļļý çöñţàîñš reader.go, writer.go, àñđ config.go; à ŕéàđ-öñļý ƒöŕḿàţ ĥàš ñö ŵŕîţéŕ. formats.RegisterAll(reg, opts...) îñ core/formats/register.go ŕéĝîšţéŕš éṽéŕý ƃüîļţ-îñ ƒàçţöŕý, àñđ ţĥé ĥöšţ çàļļš îţ ŵĥéñ îţ ƃüîļđš îţš ŕéĝîšţŕý.

ƑöŕḿàţŔéĝîšţŕý​

À šîñĝļé *registry.FormatRegistry éẋþöšéš ƒàçţöŕý ļööķüþ. Ñàḿéš àŕé ţĥé FormatID šţŕîñĝ ţýþé; ŕéĝîšţŕàţîöñ ţàķéš à ƒàçţöŕý þļüš šţàţîç ḿéţàđàţà, šö ñö ŕéàđéŕ îñšţàñçé îš ƃüîļţ àţ šţàŕţüþ:

func (r *FormatRegistry) RegisterReader(name FormatID, factory FormatReaderFactory, sig format.FormatSignature, displayName string)
func (r *FormatRegistry) RegisterWriter(name FormatID, factory FormatWriterFactory)
func (r *FormatRegistry) NewReader(name FormatID) (format.DataFormatReader, error)
func (r *FormatRegistry) NewWriter(name FormatID) (format.DataFormatWriter, error)
func (r *FormatRegistry) FormatInfos() []FormatInfo
func (r *FormatRegistry) Detect(path string, opts DetectOptions) (FormatID, error)

Ţŵö ţîéŕš öƒ ŕéĝîšţŕàţîöñ ḿàķé ƃüîļţ-îñ àñđ þļüĝîñ ƒöŕḿàţš îñđîšţîñĝüîšĥàƃļé ţö çàļļéŕš:

  1. Ƃüîļţ-îñš: ŕéĝîšţéŕéđ ƃý formats.RegisterAll ŵĥéñ ţĥé ĥöšţ šţàŕţš.
  2. Þļüĝîñ ƒöŕḿàţš: ŕéĝîšţéŕéđ ƃý pluginhost.RegisterModeCFormats ƒŕöḿ ţĥé formats çàþàƃîļîţý éàçĥ þļüĝîñ'š manifest.json đéçļàŕéš, ŕéàđ ƒŕöḿ đîšķ đüŕîñĝ đîšçöṽéŕý ŵîţĥöüţ ļàüñçĥîñĝ à šüƃþŕöçéšš. Ţĥé ḿàñîƒéšţ šééđš ţĥé ƒöŕḿàţ'š ḿéţàđàţà (ñàḿé, éẋţéñšîöñš, ḾÎḾÉ ţýþéš, ţĥé generative àñđ interchange çàþàƃîļîţîéš, àñđ ţĥé àţţŕîƃüţéš àñđ çöđé ţýþéš îţš ŵŕîţéŕ ŵŕîţéš); ţĥé ŕéàđéŕ àñđ ŵŕîţéŕ ƒàçţöŕîéš đîàļ ţĥé þļüĝîñ'š Ḿöđé-Ç đàéḿöñ öñ đéḿàñđ (É-05). À þļüĝîñ ƒöŕḿàţ ŵîţĥ ţĥé šàḿé ñàḿé àš à ƃüîļţ-îñ öṽéŕŕîđéš îţ, ƃéçàüšé îñšţàļļîñĝ à þļüĝîñ ƒöŕ à ƒöŕḿàţ îš àñ éẋþļîçîţ šîĝñàļ ţö þŕéƒéŕ îţ; ţŵö þļüĝîñš çļàîḿîñĝ öñé ñàḿé ķééþ ţĥé ƒîŕšţ ŕéĝîšţéŕéđ.

À ƒöŕḿàţ ŕéƒéŕéñçé îñ üšéŕ-ƒàçîñĝ çöñƒîĝüŕàţîöñ üšéš ţĥé šýñţàẋ name[@engine][@version][:preset], é.ĝ. okf_html@1.46.0:wellFormed öŕ html@okapi-bridge. À ţöķéñ àƒţéŕ @ ţĥàţ šţàŕţš ŵîţĥ à đîĝîţ îš à ṽéŕšîöñ; àñý öţĥéŕ ñàḿéš ţĥé éñĝîñé ŵĥöšé ƒöŕḿàţ ƒöŕ ţĥé šàḿé éẋţéñšîöñš ţĥé ŕéƒéŕéñçé ḿéàñš (FormatRegistry.EngineFormat). Ţĥé ŕéĝîšţŕý ŕéšöļṽéš ţĥé ŕéƒéŕéñçé ţö ţĥé àþþŕöþŕîàţé ƒàçţöŕý.

Ƒöŕḿàţ đéţéçţîöñ​

Detect(path, DetectOptions) ŕéšöļṽéš ţĥé ƒöŕḿàţ ƒöŕ à þàţĥ, àñđ Resolve(path, DetectOptions) îš ţĥé šàḿé çàļļ ŵîţĥ ţĥé đéçîšîöñ ŕéþöŕţéđ (ţĥé ƒöŕḿàţ, îţš éñĝîñé, ţĥé ŕüļé ţĥàţ çĥöšé ţĥé éñĝîñé, àñđ éṽéŕý çļàîḿàñţ). Éṽéŕý šüŕƒàçé ţĥàţ đéţéçţš à ƒöŕḿàţ ƒöŕ à ñàḿéđ ƒîļé ĝöéš ţĥŕöüĝĥ îţ: ţĥé ţööļ àñđ ƒļöŵ ŕüññéŕš, ţĥé ţööļƃöẋ, þŕöĵéçţ çöñţéñţ ŕéšöļüţîöñ, ḿéŕĝé àñđ ţĥé đéšķţöþ. À ƒîļé ŕéšöļṽéš ţö ţĥé šàḿé ƒöŕḿàţ ƒŕöḿ éàçĥ, àñđ kapi formats explain þŕîñţš ţĥé đéçîšîöñ ƒöŕ öñé.

Ŕéšöļüţîöñ ŕàñķš éñĝîñéš ƃéƒöŕé ƒöŕḿàţš. Àñ éñĝîñé îš à ƒöŕḿàţ þŕöṽîđéŕ: ţĥé ƃüîļţ-îñ ƒöŕḿàţš (native) öŕ öñé þļüĝîñ. Ƒöŕ àñ éẋţéñšîöñ šéṽéŕàļ éñĝîñéš çļàîḿ, ţĥé éñĝîñé öŕđéŕ đéçîđéš ţĥé þŕöṽîđéŕ, ƒîŕšţ ţö ļàšţ: à þéŕ-ƒöŕḿàţ þîñ (DetectOptions.FormatEngines, ƒŕöḿ à ŕéçîþé'š defaults.formats.<name>.engine), ţĥé ĥöšţ'š öṽéŕŕîđé (SetEngineOverride, ƒŕöḿ --engine), ţĥé đéţéçţîöñ'š þŕéƒéŕéñçé (DetectOptions.Engine, ƒŕöḿ defaults.engine), ţĥé ĥöšţ'š đéƒàüļţ (SetDefaultEngine, ƒŕöḿ ţĥé çöñƒîĝ'š formats.engine), ţĥé ƃüîļţ-îñ ƒöŕḿàţš, ţĥé ŕàñķéđ þļüĝîñš (DetectOptions.EngineOrder, ƒŕöḿ plugins.<name>.format_priority), ţĥéñ éṽéŕý öţĥéŕ šöüŕçé îñ ñàḿé öŕđéŕ. Ţĥé ƒîŕšţ éñĝîñé ŵîţĥ à çļàîḿàñţ ŵîñš. À þŕîöŕîţý ñéṽéŕ ḿöṽéš à ƒöŕḿàţ àçŕöšš éñĝîñéš: ŵîţĥîñ ţĥé çĥöšéñ éñĝîñé, ţĥé ƒîļé ĥéàđ đéçîđéš ŵĥéñ šéṽéŕàļ öƒ îţš ƒöŕḿàţš çļàîḿ ţĥé éẋţéñšîöñ (.xliff çàñ ƃé ẊĻÎƑƑ 1.ẋ öŕ 2.ẋ; .xml îš çļàîḿéđ ƃý šéṽéŕàļ ƒöŕḿàţš), àñđ ţĥé ƒöŕḿàţš' þŕîöŕîţîéš đéçîđé öţĥéŕŵîšé. DetectOptions àļšö çàŕŕîéš ExtensionOnly ƒöŕ ţĥé đéţéŕḿîñîšţîç þîçķ ŵîţĥöüţ ŕéàđîñĝ ţĥé ƒîļé, AllowedSources ƒöŕ ţĥé þŕöĵéçţ'š šöüŕçé ŕéšţŕîçţîöñ, PriorityOverrides ƒöŕ þéŕ-çàļļ þŕîöŕîţîéš àñđ Writer ţö ŕéšöļṽé ţĥé ƒöŕḿàţ ţĥàţ ŵŕîţéš à þàţĥ. Öñļý ţĥé ĥéàđ öƒ ţĥé ƒîļé îš ŕéàđ; àñý ŕéàđ éŕŕöŕ ƒàļļš ƃàçķ ţö ţĥé éẋţéñšîöñ þîçķ. WriterFormatFor ŕéšöļṽéš ţĥé ŵŕîţéŕ ƒöŕ àñ öüţþüţ þàţĥ ŵîţĥîñ ţĥé ŕéàđéŕ'š éñĝîñé ƒîŕšţ, šö à ƒöŕḿàţ ñàḿéđ ŵîţĥ --format þîñš ţĥé ŕéàđéŕ àñđ ţĥé ŵŕîţéŕ ţö öñé éñĝîñé.

Éàçĥ ƒöŕḿàţ ŕéĝîšţéŕš à FormatSignature đéçļàŕîñĝ ţĥé ḾÎḾÉ ţýþéš, éẋţéñšîöñš, ḿàĝîç ƃýţéš, àñđ öþţîöñàļ šñ ƒüñçţîöñ îţ çļàîḿš, šö ţĥé çàšçàđé îš đàţà-đŕîṽéñ ŕàţĥéŕ ţĥàñ ĥàŕđçöđéđ. FormatSignature.Binary ḿàŕķš à ƒöŕḿàţ ŵĥöšé ŕéàđéŕ çöñšüḿéš ƃîñàŕý çöñţéñţ, šö đéţéçţîöñ đöéš ñöţ đéçļîñé îţ ƒöŕ ƃîñàŕý îñþüţ ţĥé ŵàý îţ đéçļîñéš à ţéẋţ ƒöŕḿàţ ḿàţçĥéđ öñļý ƃý éẋţéñšîöñ.

ķàþî'š öŵñ öñ-đîšķ çöñṽéñţîöñš üšé çöḿþöüñđ šüƒƒîẋéš (.kbf.json, .memory.json, .terms.json, .overlays.json, .overlays.jsonl) šö ţĥé ḿàŕķéŕ šüŕṽîṽéš ŵĥîļé ţĥé ƒîļé šţîļļ ŕéàđš àš ţĥé ĴŠÖÑ îţ îš. path/filepath.Ext ŕéþöŕţš .json ƒöŕ àļļ öƒ ţĥéḿ, šö éẋţéñšîöñ-đŕîṽéñ çöđé ĝöéš ţĥŕöüĝĥ format.Ext / TrimExt / Stem îñšţéàđ, ŵĥîçĥ ŕéţüŕñ ţĥé ḿöšţ šþéçîƒîç ŕéĝîšţéŕéđ šüƒƒîẋ.

Ţĥé šķéļéţöñ šţöŕé​

Ñöñ-ţŕàñšļàţàƃļé çöñţéñţ îš þŕéšéŕṽéđ ƒöŕ ŵŕîţé-ƃàçķ ƃý öñé ḿéçĥàñîšḿ: format.SkeletonStore, àñ àþþéñđ-öñļý šéǫüéñçé öƒ ţýþéđ éñţŕîéš ţĥé ŕéàđéŕ éḿîţš đüŕîñĝ éẋţŕàçţîöñ àñđ ţĥé ŵŕîţéŕ ŕéþļàýš đüŕîñĝ ŕéçöñšţŕüçţîöñ. Ţĥé þîþéļîñé ñéṽéŕ šééš îţ; ţööļš çàŕŕý öñļý ƃļöçķš. À ŕéàđéŕ ţĥàţ þŕöđüçéš öñé îḿþļéḿéñţš SkeletonStoreEmitter, à ŵŕîţéŕ ţĥàţ çöñšüḿéš öñé SkeletonStoreConsumer, àñđ ñéàŕļý éṽéŕý ƃüîļţ-îñ ƒöŕḿàţ đöéš ƃöţĥ. À šķéļéţöñ îš ţĥé ţýþéđ šçàƒƒöļđîñĝ öƒ öñé ƒöŕḿàţ, šö format.WireSkeleton çöññéçţš à ŕéàđéŕ ţö à ŵŕîţéŕ öñļý ŵĥéñ ţĥéý àŕé ţĥé šàḿé ƒöŕḿàţ (šéé "Šķéļéţöñš àŕé ţýþéđ þéŕ ƒöŕḿàţ" ƃéļöŵ).

Ţĥé šţöŕé ĥàš šéṽéŕàļ ƃàçķîñĝš ƃéĥîñđ öñé ÀÞÎ: à ţéḿþ ƒîļé (NewSkeletonStore), ḿéḿöŕý (NewMemorySkeletonStore), ñöţĥîñĝ àţ àļļ ƒöŕ à þàšš ţĥàţ ŕéàđš à đöçüḿéñţ àñđ ŵŕîţéš ñöñé (NewDiscardSkeletonStore, ŵĥîçĥ format.NewWiredReadSkeleton ŵîŕéš šö à ŕéàđ šééš ţĥé ƃļöçķš à ŵŕîţé ŵöüļđ), à çöñçüŕŕéñţ çĥàññéļ ƒöŕ šţŕéàḿîñĝ þàîŕš (NewStreamingSkeletonStore), àñđ à þéŕšîšţéđ ƒîļé ţĥàţ öüţļîṽéš ţĥé þŕöçéšš (NewSkeletonStoreAt / OpenSkeletonStore, NewSkeletonStoreFromBytes), ŵĥîçĥ îš ĥöŵ à .kpz ŵöŕķšþàçé çàŕŕîéš à šķéļéţöñ ƃéţŵééñ extract àñđ merge. format.NewWiredSkeleton(reader, writer) îš ţĥé öñé šéàḿ éṽéŕý ŕüññéŕ üšéš ţö ĝîṽé à šàḿé-ƒöŕḿàţ ŕöüñđ ţŕîþ îţš šţöŕé. Îţ ŕéţüŕñš ñö šţöŕé ƒöŕ à þàîŕ ŵîţĥ ñö šķéļéţöñ þàţĥ, àñđ îţ ŕéţüŕñš àñ éŕŕöŕ ŵĥéñ à šţöŕé îš ñééđéđ àñđ çàññöţ ƃé çŕéàţéđ; ţĥàţ éŕŕöŕ îš ñéṽéŕ šŵàļļöŵéđ, ƃéçàüšé šîļéñţļý ŕéçöñšţŕüçţîñĝ ƒŕöḿ ţĥé çöñţéñţ ḿöđéļ ŵöüļđ đŕöþ šţŕüçţüŕé ţĥé ŕéàđéŕ çöüļđ ñöţ ḿöđéļ ŵĥîļé ţĥé çöḿḿàñđ šţîļļ ŕéþöŕţéđ šüççéšš.

Ţŵö éñţŕý ţýþéš ḿàķé àñ üñţöüçĥéđ đöçüḿéñţ ŕöüñđ-ţŕîþ ƃýţé ƒöŕ ƃýţé éṽéñ ŵĥéŕé éẋţŕàçţîöñ ñöŕḿàļîžéđ îţš ţéẋţ. À ŕéàđéŕ ţĥàţ çöļļàþšéš ŵĥîţéšþàçé öñ ţĥé ŵàý îñ ŵŕîţéš ţĥé šöüŕçé ƃýţéš ƃéšîđé ţĥé ŕéƒéŕéñçé (SkeletonOriginal); ţĥé ŵŕîţéŕ ŕéþļàýš ţĥöšé ƃýţéš ŵĥîļé ţĥé ƃļöçķ îš üñéđîţéđ àñđ ŕéñđéŕš ţĥé ƃļöçķ öñļý öñçé îţ ĥàš çĥàñĝéđ. SkeletonTrimmed đöéš ţĥé šàḿé ƒöŕ ţĥé ƃýţéš à ŕéàđéŕ ţŕîḿḿéđ àƒţéŕ à ƃļöçķ. Éẋţŕàçţîöñ šţîļļ ýîéļđš çļéàñ ţéẋţ, àñđ à ñö-öþ ŕöüñđ ţŕîþ îš ţĥé îđéñţîţý.

À ŵŕîţéŕ ĝîṽéñ ñö šţöŕé ƒàļļš ƃàçķ îñ à ƒîẋéđ öŕđéŕ: ŕé-þàŕšé ţĥé öŕîĝîñàļ đöçüḿéñţ (OriginalContentSetter / SourcePathSetter) àñđ þàţçĥ ţŕàñšļàţîöñš îñţö îţ, öŕ, ƒàîļîñĝ ţĥàţ, ƃüîļđ ţĥé đöçüḿéñţ ƒŕöḿ ţĥé ƃļöçķš àļöñé. Ţĥé ƒàļļƃàçķš ţŕàđé ƒîđéļîţý ƒöŕ àṽàîļàƃîļîţý àñđ éẋîšţ ƒöŕ ţĥé çŕöšš-ƒöŕḿàţ àñđ ñö-šöüŕçé çàšéš; à šàḿé-ƒöŕḿàţ ŕüñ àļŵàýš ĥàš ţĥé šţöŕé. Šéé Šķéļéţöñ šţöŕé àñđ šţŕéàḿîñĝ ƒöŕ ţĥé éñţŕý ƒöŕḿàţ, ţĥé šüƃ-šķéļéţöñ àñđ ţĥé šţŕéàḿîñĝ þŕöţöçöļ.

Šţŕéàḿîñĝ ŕéàđéŕš àñđ ƃöüñđéđ-ḿéḿöŕý Î/Ö​

Ţĥé ŕéàđ → þŕöçéšš → ŵŕîţé þàţĥ šţŕéàḿš éñđ-ţö-éñđ šö þéàķ ḿéḿöŕý ţŕàçķš à ƃöüñđéđ ŵîñđöŵ, ñöţ ţĥé đöçüḿéñţ šîžé. Ţĥŕéé éđĝéš çööþéŕàţé:

  1. Šöüŕçé éđĝé. Ţĥé ƒîļé-ŕüñ þàţĥ (core/flow.FileRunner) ĥàñđš ţĥé ŕéàđéŕ à šţŕéàḿîñĝ, ƃýţé-ƃüđĝéţéđ io.ReadCloser öṽéŕ ţĥé ƒîļé (core/safeio éñƒöŕçéđ üñîƒöŕḿļý) îñšţéàđ öƒ ŕéàđîñĝ ţĥé ŵĥöļé ƒîļé îñţö à ƃüƒƒéŕ üþ ƒŕöñţ. À ļîñé öŕ ŕéçöŕđ ŕéàđéŕ þüļļš ƃýţéš öñ đéḿàñđ àñđ ñéṽéŕ ĥöļđš ţĥé ŵĥöļé îñþüţ; à ŵĥöļé-đöçüḿéñţ ŕéàđéŕ šţîļļ ŕéàđš îţ öñçé, îñ ƒüļļ.
  2. Ŕéàđéŕ → éẋéçüţöŕ. Ŵĥéñ ţĥé ŕéàđéŕ đéçļàŕéš ţĥé format.StreamingReader çàþàƃîļîţý, îţš Read çĥàññéļ îš ƒéđ šţŕàîĝĥţ îñţö ţĥé éẋéçüţöŕ ŕàţĥéŕ ţĥàñ ƃéîñĝ çöļļéçţéđ îñţö à []*Part šļîçé ƃéţŵééñ ŕéàđéŕ àñđ ţööļš, šö ţĥé ŕéàđéŕ ŕüñš çöñçüŕŕéñţļý ŵîţĥ ţĥé ŵŕîţéŕ. Ţĥîš îš ĝàţéđ öñ ţĥé çàþàƃîļîţý ƃéçàüšé îţ öṽéŕļàþš ţĥé ŕéàđ àñđ ţĥé ŵŕîţé: öñļý îñ-þŕöçéšš, þüŕé-Ĝö ŕéàđéŕš ḿàý öþţ îñ, ñéṽéŕ à đàéḿöñ-ƃàçķéđ þļüĝîñ, ŵĥîçĥ ķééþš ţĥé ŕéàđ-ƒüļļý-ţĥéñ-ŵŕîţé öŕđéŕ îţš öñé-šţŕéàḿ-àţ-à-ţîḿé çöñţŕàçţ ŕéǫüîŕéš.
  3. Šķéļéţöñ. À ƃýţé-éẋàçţ ŕöüñđ-ţŕîþ ñééđš ţĥé šķéļéţöñ, ƃüţ ţĥé ƃüƒƒéŕéđ šķéļéţöñ ŵŕîţéŕ çöļļéçţš éṽéŕý ƃļöçķ îñţö à ḿàþ àñđ ŕéþļàýš ţĥé šķéļéţöñ öñļý àƒţéŕ îţ îš ƒüļļý ŵŕîţţéñ: Ö(ƃļöçķš) ḿéḿöŕý. À ŕéàđéŕ àñđ ŵŕîţéŕ ţĥàţ ƃöţĥ đéçļàŕé šţŕéàḿîñĝ (StreamingReader + format.StreamingWriter) îñšţéàđ šĥàŕé à çöñçüŕŕéñţ, çĥàññéļ-ƃàçķéđ šķéļéţöñ šţöŕé: ţĥé ŕéàđéŕ àþþéñđš éñţŕîéš ŵĥîļé ţĥé ŵŕîţéŕ þöþš ţĥéḿ, çöñšüḿîñĝ éàçĥ SkeletonRef'š ƃļöçķ ƒŕöḿ ţĥé Þàŕţ šţŕéàḿ öñ đéḿàñđ (format.StreamSkeletonWrite). Ƃéçàüšé à šţŕéàḿîñĝ ŕéàđéŕ éḿîţš ŕ郚 àñđ ţĥéîŕ ƃļöçķš îñ ţĥé šàḿé öŕđéŕ, ţĥé þéñđîñĝ-ƃļöçķ ŵîñđöŵ šţàýš šḿàļļ. Öüţþüţ îš ƃýţé-îđéñţîçàļ ţö ţĥé ƃüƒƒéŕéđ šķéļéţöñ þàţĥ: ţĥé šàḿé éñţŕîéš îñ ţĥé šàḿé öŕđéŕ, ĵüšţ çöñšüḿéđ îñţéŕļéàṽéđ îñšţéàđ öƒ àƒţéŕ à ƒļüšĥ. Ƃöţĥ çàþàƃîļîţîéš àŕé ƃàŕé ḿàŕķéŕš (StreamingReader() / StreamingWriter()), þŕöƃéđ ṽîà IsStreamingReader / IsStreamingWriter; à ŵŕîţéŕ šîĝñàļš îţ ţööķ ţĥé šţŕéàḿîñĝ þàţĥ ƃý çĥéçķîñĝ SkeletonStore.IsStreaming() îñ Write.

À ƒöŕḿàţ šţŕéàḿš ŵĥéñ ƃöţĥ îţš ŕéàđéŕ àñđ îţš ŵŕîţéŕ đéçļàŕé ţĥé ḿàŕķéŕš. Ţĥé ŕéçöŕđ- àñđ éñţŕý-öŕîéñţéđ ƒöŕḿàţš đö, ĥöļđîñĝ öñļý ţĥé îñ-þŕöĝŕéšš üñîţ, àñđ ţĥé ĝéñéŕàţéđ Ƒöŕḿàţ Ŕéƒéŕéñçé šàýš ŵĥîçĥ. Ţĥé ƒîļé ŕüññéŕ đéçîđéš öñçé þéŕ ŕüñ, îñ ţŵö šţéþš (streamingFeed, ţĥéñ wireSkeleton): à šţŕéàḿîñĝ ŕéàđéŕ ŵîţĥ ñö þŕé-ŕéàđ šöüŕçé îš ƒéđ çöñçüŕŕéñţļý, àñđ à šţŕéàḿîñĝ ŵŕîţéŕ ţĥéñ ŕéçéîṽéš ţĥé çĥàññéļ-ƃàçķéđ šţöŕé; àñý öţĥéŕ þàîŕ ŕéçéîṽéš ţĥé ţéḿþ-ƒîļé šţöŕé. Éàçĥ šţŕéàḿîñĝ ŵŕîţéŕ'š SkeletonRef ŕéñđéŕîñĝ îš ƒàçţöŕéđ îñţö à šĥàŕéđ ĥéļþéŕ šö ţĥé ƃüƒƒéŕéđ àñđ šţŕéàḿîñĝ šķéļéţöñ þàţĥš àŕé ƃýţé-îđéñţîçàļ.

À ƒöŕḿàţ ţĥàţ ḿüšţ ḿàţéŕîàļîšé îţš ŵĥöļé îñþüţ ţö þàŕšé îţ (à þàçķàĝéđ žîþ-ƃàçķéđ ƒöŕḿàţ, à ĐÖḾ-ƃüîļđîñĝ ḿàŕķüþ ŕéàđéŕ) đöéš ñöţ đéçļàŕé ţĥé çàþàƃîļîţý, àñđ à üñîƒöŕḿ ƒàļļƃàçķ ķééþš îţš öüţþüţ ƃýţé-îđéñţîçàļ. Ţĥé çöñţàîñéŕ þàţĥ đŕîṽéš öñé àŕçĥîṽé éñţŕý ţĥŕöüĝĥ FileRunner.RunStream (ƃýţéš îñ, ƃýţéš öüţ, ñö ţéḿþ ƒîļé); à šţŕéàḿîñĝ-çàþàƃļé îññéŕ ƒöŕḿàţ îš ñöţ éṽéñ ƃüƒƒéŕéđ ŵĥöļé (É-04).

Ŵŕîţéŕ öüţþüţ ḿöđéš: ĝéñéŕàţîṽé ṽš šķéļéţöñ-ƃöüñđ​

À šķéļéţöñ îš ƒöŕḿàţ-šþéçîƒîç: îţ îš ţĥé ñöñ-ţŕàñšļàţàƃļé šçàƒƒöļđîñĝ öƒ öñé ƒîļé, çàþţüŕéđ ƃý ţĥàţ ƒöŕḿàţ'š ŕéàđéŕ. Šö à ŵŕîţéŕ'š àƃîļîţý ţö þŕöđüçé öüţþüţ đéþéñđš öñ ŵĥéţĥéŕ îţ çàñ ƃüîļđ à ŵĥöļé đöçüḿéñţ ƒŕöḿ ţĥé çöñţéñţ ḿöđéļ àļöñé, öŕ öñļý ƃý îñĵéçţîñĝ ţŕàñšļàţéđ ţéẋţ ƃàçķ îñţö à šķéļéţöñ îţ ŵàš ĝîṽéñ. Ţŵö öŕţĥöĝöñàļ çàþàƃîļîţîéš çàþţüŕé ţĥîš:

  • Ĝéñéŕàţîṽé: ţĥé ŵŕîţéŕ çàñ šéŕîàļîžé à çöḿþļéţé, ṽàļîđ đöçüḿéñţ ƒŕöḿ ţĥé çöñţéñţ ḿöđéļ (ŕöļéš, ŕüñš, šţŕüçţüŕé) ŵîţĥ ñö šķéļéţöñ.
  • Šķéļéţöñ-çöñšüḿîñĝ: ţĥé ŵŕîţéŕ üšéš à šķéļéţöñ ŵĥéñ ĝîṽéñ öñé, ƒöŕ ƃýţé-éẋàçţ ƒîđéļîţý, ṽîà ţĥé SkeletonStoreConsumer îñţéŕƒàçé. Îţ šàýš ţĥé ŵŕîţéŕ ŵîļļ üšé à šķéļéţöñ, àñđ šàýš ñöţĥîñĝ àƃöüţ ŵĥéţĥéŕ îţ ñééđš öñé.

Ţĥéšé çöḿþöšé îñţö ţĥŕéé ŵŕîţéŕ çļàššéš:

  • Ĝéñéŕàţîṽé đöçüḿéñţ àñđ đàţà ŵŕîţéŕš (generative, ñöţ îñţéŕçĥàñĝé). ĤŢḾĻ îš ţĥé àŕçĥéţýþé: ŵîţĥ ţĥé šöüŕçé ƒîļé'š šķéļéţöñ îţ ŕöüñđ-ţŕîþš ļöššļéššļý, àñđ ŵîţĥöüţ öñé îţ šţîļļ ŵŕîţéš à çļéàñ đöçüḿéñţ, šö îţ îš àļšö à ţàŕĝéţ ƒöŕ çöñţéñţ ţĥàţ àŕŕîṽéđ ƒŕöḿ à đéŕéñţ ƒöŕḿàţ. Ḿàŕķđöŵñ, ĐöçĻàñĝ, ÀšçîîĐöç, þļàîñ ţéẋţ, àñđ ţĥé đàţà àñđ çàţàļöĝ ƒöŕḿàţš ƃéĥàṽé ţĥé šàḿé. Ţĥéšé àŕé ţĥé convert ţàŕĝéţš.
  • Ƃîļîñĝüàļ îñţéŕçĥàñĝé ŵŕîţéŕš (generative àñđ interchange). ẊĻÎƑƑ, ÞÖ, ŢḾẊ, ḾÖ, àñđ ĶƂƑ àŕé ĝéñéŕàţîṽé ƒîļéš, ƃüţ ţĥéý ƃéļöñĝ ţö ţĥé éẋţŕàçţ → ţŕàñšļàţé → ḿéŕĝé ļööþ, ñöţ ţö đöçüḿéñţ çöñṽéŕšîöñ: kapi extract çàþţüŕéš ţĥé šöüŕçé šķéļéţöñ šö kapi merge çàñ ŕöüñđ-ţŕîþ ţŕàñšļàţîöñš ƃàçķ îñţö ţĥé öŕîĝîñàļ ƒöŕḿàţ. À convert-þŕöđüçéđ îñţéŕçĥàñĝé ƒîļé çàŕŕîéš ñö šķéļéţöñ àñđ çàññöţ ƃé ḿéŕĝéđ ƃàçķ (à đéàđ éñđ), šö îñţéŕçĥàñĝé ƒöŕḿàţš àŕé éẋçļüđéđ àš convert ţàŕĝéţš àñđ ŕéàçĥéđ ṽîà extract/merge (Ḿ-01).
  • Šķéļéţöñ-ƃöüñđ ŵŕîţéŕš (ñöţ ĝéñéŕàţîṽé). Þàçķàĝéđ ƒöŕḿàţš (ÖþéñẊḾĻ, ÖĐƑ, ÉÞÜƂ, îḿàĝé) ŵŕàþ çöñţéñţ îñ à ƒîẋéđ þàçķàĝé ţĥàţ çàññöţ ƃé ŕéĝéñéŕàţéđ ƒŕöḿ ţĥé ḿöđéļ; ţĥéý öñļý éṽéŕ ŵŕîţé ƃàçķ îñţö ţĥéîŕ öŵñ šķéļéţöñ. Šàḿé-ƒöŕḿàţ àñđ ḿéŕĝé ŵŕîţéŕš, ñéṽéŕ à çŕöšš-ƒöŕḿàţ ţàŕĝéţ.

Çŕöšš-ƒöŕḿàţ çöñṽéŕšîöñ (Š-04) ŕéçöñšţŕüçţš ţĥé ţàŕĝéţ ƒŕöḿ ţĥé çöñţéñţ ḿöđéļ àñđ ñéṽéŕ çàŕŕîéš à ƒöŕéîĝñ šķéļéţöñ îñţö ţĥé ŵŕîţéŕ. À ŵŕîţéŕ îš à ṽàļîđ çöñṽéŕšîöñ ţàŕĝéţ  îţ îš ĝéñéŕàţîṽé àñđ ñöţ îñţéŕçĥàñĝé. Ƃöţĥ àŕé đéçļàŕéđ ŵŕîţéŕ çàþàƃîļîţîéš: ţĥé ŵŕîţéŕ šţàţéš ŵĥàţ îţ çàñ ŵŕîţé ṽîà GenerativeWriter.Generative() (ţĥé îñṽéŕšé öƒ BaseFormatWriter.RequiresSkeleton) àñđ InterchangeWriter.IsInterchange(). Ţĥé ŕéĝîšţŕý ŕéçöŕđš ţĥéḿ öñ FormatInfo.Generative / FormatInfo.Interchange: þŕöƃéđ öñçé ƒŕöḿ ţĥé ƃüîļţ-îñ ŵŕîţéŕ àţ ŕéĝîšţŕàţîöñ, àñđ ƒöŕ þļüĝîñ ƒöŕḿàţš ţàķéñ ƒŕöḿ ţĥé çàçĥéđ ḿàñîƒéšţ'š generative / interchange çàþàƃîļîţîéš, šö çöñṽéŕšîöñ, ţĥé Çöñṽéŕšîöñ ļàƃ, àñđ kapi formats ŕéàđ öñé àüţĥöŕîţàţîṽé šöüŕçé ŵîţĥöüţ ļöàđîñĝ àñý þļüĝîñ. Ñéîţĥéŕ îš đéŕîṽéđ ƒŕöḿ SkeletonStoreConsumer (ñéàŕļý éṽéŕý ŵŕîţéŕ çöñšüḿéš à šķéļéţöñ îƒ öƒƒéŕéđ, šö ţĥàţ ƃîţ đöéš ñöţ đîšţîñĝüîšĥ à ţàŕĝéţ) ñöŕ þŕöƃéđ éḿþîŕîçàļļý.

Ţŵö đéŕîṽéđ ƒļàĝš šîţ ƃéšîđé ţĥéḿ. FormatInfo.RoundTrip, þŕöƃéđ ƒŕöḿ SkeletonStoreConsumer, šàýš ţĥé ŵŕîţéŕ ŕéçöñšţŕüçţš ƒŕöḿ à šķéļéţöñ, šö àñ éđîţ çĥàñĝéš öñļý ţĥé éđîţéđ ţéẋţ. FormatInfo.Editable (à ŕéàđéŕ àñđ à ŵŕîţéŕ, àñđ ñöţ îñţéŕçĥàñĝé) îš ţĥé šéţ à çàļļéŕ-šüþþļîéđ çöñţéñţ éđîţ çàñ ţàŕĝéţ.

Ḿàŕķš à ŵŕîţéŕ çàñ đŕàŵ​

À ƃļöçķ'š ŕüñš çàŕŕý ŵĥàţ ţĥé šöüŕçé đöçüḿéñţ šţŕüçţüŕàļļý çöñţàîñéđ. Ŵĥàţ à ĝöṽéŕñàñçé þàšš çöñçļüđéđ àƃöüţ ţĥàţ çöñţéñţ ŕîđéš šţàñđ-öƒƒ öñ à model.Anchor: à ļöçàţéđ ţéŕḿ, à ṽöîçé ƒîñđîñĝ, à šţýļé ṽîöļàţîöñ (Ƒ-02). Šöḿé ƒöŕḿàţš ĥàṽé šöḿéŵĥéŕé ţö þüţ šüçĥ à çöñçļüšîöñ, àñđ ḿöšţ đö ñöţ: ẊĻÎƑƑ ĥàš <mrk>, ĤŢḾĻ ĥàš <span>, þļàîñ ţéẋţ ĥàš ñöţĥîñĝ àţ àļļ.

Šö đŕàŵîñĝ ţĥéḿ îš à đéçļàŕéđ ŵŕîţéŕ çàþàƃîļîţý, ţĥé ƒöüŕţĥ öƒ ţĥé ķîñđ Generative àñđ Interchange àļŕéàđý àŕé. InlineAnnotationWriter ñàḿéš ţĥé àññöţàţîöñ ţýþéš ţĥé ŵŕîţéŕ ķñöŵš ĥöŵ ţö đŕàŵ, àñđ ţĥé ŕéĝîšţŕý ŕéçöŕđš ţĥéḿ öñ FormatInfo.InlineAnnotations, þŕöƃéđ öñçé ƒŕöḿ ţĥé ƃüîļţ-îñ ŵŕîţéŕ àţ ŕéĝîšţŕàţîöñ; à þļüĝîñ ƒöŕḿàţ đéçļàŕéš ñöñé. kapi formats àñđ ţĥé ŵŕîţéŕ šéļéçţîöñ ţĥéŕéƒöŕé ŕéàđ öñé àüţĥöŕîţàţîṽé šöüŕçé ŵîţĥöüţ ļöàđîñĝ àñý þļüĝîñ. À ŵŕîţéŕ ţĥàţ îḿþļéḿéñţš ñöţĥîñĝ çàŕŕîéš ñö ḿàŕķš.

Ţĥé đéçļàŕàţîöñ îš à çéîļîñĝ, àñđ defaults.annotations.write îñ ţĥé ŕéçîþé ñàŕŕöŵš îţ:

defaults:
  annotations:
    write: [term]      # voice findings stay stand-off

Ñàŕŕöŵîñĝ öñļý, ñéṽéŕ ŵîđéñîñĝ, àñđ ţŵö ţĥîñĝš ƒöļļöŵ ƒŕöḿ ţĥàţ đîŕéçţîöñ. À ƒöŕḿàţ ţĥàţ ĝàîñš ţĥé çàþàƃîļîţý šţàŕţš þŕöĵéçţîñĝ ŵîţĥöüţ àñýöñé éđîţîñĝ à ŕéçîþé, ŵĥîçĥ îš ŵĥàţ ķééþš ţĥé ŕéçîþé ƒŕöḿ ƃéîñĝ à ļîšţ à þŕöĵéçţ ĥàš ţö ḿàîñţàîñ àĝàîñšţ ţĥé ƒöŕḿàţ çàţàļöĝ. Àñđ ñàḿîñĝ à ţýþé à ƒöŕḿàţ çàññöţ çàŕŕý àšķš ƒöŕ ñöţĥîñĝ ŕàţĥéŕ ţĥàñ ƒàîļîñĝ, ƃéçàüšé öñé ŕéçîþé đéšçŕîƃéš ḿàñý öüţþüţš àñđ à þŕöĵéçţ ţĥàţ ŵàñţš ţéŕḿš ḿàŕķéđ ŵĥéŕéṽéŕ ţĥéý çàñ ƃé šĥöüļđ ñöţ ĥàṽé ţö éñüḿéŕàţé ŵĥîçĥ öƒ îţš ƒöŕḿàţš ĥàþþéñ ţö šüþþöŕţ îţ.

Ţĥé đéƒàüļţ îš ţĥàţ à đöçüḿéñţ ļéàṽéš àš à đöçüḿéñţ. Àñ àññöţàţîöñ ţŕàṽéļš ƃéšîđé ţĥé çöñţéñţ îñ àñ öṽéŕļàý šîđéçàŕ üñļéšš à ŵŕîţéŕ ƃöţĥ çàñ đŕàŵ îţ àñđ ŵàš ñöţ ţöļđ öţĥéŕŵîšé.

ẊĻÎƑƑ 2 îš ţĥé ƒîŕšţ ŵŕîţéŕ ţö đéçļàŕé ţĥé çàþàƃîļîţý, àñđ îţ đŕàŵš à ţéŕḿ àš àñ <sm>/<em> þàîŕ ŕàţĥéŕ ţĥàñ àñ <mrk>. Ƃöţĥ àŕé šþéç šĥàþéš àñđ <mrk> ŕéàđš ƃéţţéŕ ŵĥéñ à šþàñ ñéšţš çļéàñļý îñšîđé öñé éļéḿéñţ, ƃüţ öñļý ţĥé þàîŕ çàñ çàŕŕý à šþàñ ţĥàţ đöéš ñöţ, àñđ à ţéŕḿ ŕüññîñĝ ƒŕöḿ ƃéƒöŕé à <pc> ţö àƒţéŕ îţ îš éẋàçţļý ŵĥàţ àñ Anchor îš ƃüîļţ ţö éẋþŕéšš. Ƃéçàüšé ţĥé ţŵö ḿàŕķéŕš àŕé îñđéþéñđéñţ ñöđéš, éàçĥ îš þļàçéđ ŵĥéŕéṽéŕ îţš öŵñ ƃöüñđàŕý ļàñđš, îñçļüđîñĝ îñšîđé àñ éļéḿéñţ ŵĥöšé þàŕţñéŕ šîţš öüţšîđé.

À šþàñ à šéĝḿéñţàţîöñ çàññöţ çàŕŕý, öñé šţŕàđđļîñĝ ţŵö <segment> éļéḿéñţš, îš ŕéçöŕđéđ öñ ţĥé ŵŕîţéŕ (UnplacedTermMarks) ŕàţĥéŕ ţĥàñ ĥàļƒ-đŕàŵñ.

Éđîţš à ŵŕîţéŕ çàñ ŵŕîţé​

À šàḿé-ƒöŕḿàţ ŵŕîţéŕ ŕéþļàýš îţš šķéļéţöñ àñđ ŵŕîţéš ţĥé ţéẋţ öƒ ţĥé ƃļöçķš àñ éđîţ çĥàñĝéđ. Šöḿé éđîţš çĥàñĝé ḿöŕé ţĥàñ ţéẋţ: ţĥé ţàŕĝéţ öƒ à ļîñķ, öŕ à ñéŵ ƃöļđ šþàñ öṽéŕ ŵöŕđš ţĥàţ ĥàđ ñöñé. Ţĥé çĥàñĝé çöñţŕàçţ çàŕŕîéš ţĥéḿ àš set_attribute, mark àñđ à ñéŵ çöđé îñ à runs þàýļöàđ, àñđ à ƒöŕḿàţ àççéþţš éàçĥ öñé öñļý ŵĥéŕé îţš ŵŕîţéŕ đéçļàŕéš îţ. Ƒöüŕ đéçļàŕéđ ŵŕîţéŕ çàþàƃîļîţîéš šàý ŵĥàţ à ŵŕîţéŕ çàñ ŵŕîţé ƃéýöñđ îţš šķéļéţöñ, îñ core/format/editcaps.go àñđ core/format/structural.go:

ÎñţéŕƒàçéĐéçļàŕéšÜšéđ ƃý
AttrWriterWritableAttrs(): þéŕ çöđé ţýþé, ţĥé àţţŕîƃüţéš ŵĥöšé ṽàļüé ţĥé ŵŕîţéŕ ŵŕîţéšset_attribute
CodeSynthesizerSynthesizes(): ţĥé ṽöçàƃüļàŕý ţýþéš ţĥé ŵŕîţéŕ ŵŕîţéš àš à ñéŵ þàîŕéđ çöđémark, à ñéŵ çöđé îñ runs
StructureEditorStructural(): insert_block, delete_block, ŵîţĥ EditStructure, ŵĥîçĥ ŵŕîţéš ţĥéḿţĥé šţŕüçţüŕàļ öþéŕàţîöñš
NativeEditorNativeOps(): ƒöŕḿàţ-šþéçîƒîç öþéŕàţîöñš àñđ ţĥéîŕ àŕĝüḿéñţ šçĥéḿàšnative

Ţĥé ŕéĝîšţŕý ŕéçöŕđš ţĥéḿ öñ FormatInfo.EditCapabilities, ŵĥîçĥ đéšçŕîƃéš ţĥé ƒöŕḿàţ'š ŕéĝîšţéŕéđ ŵŕîţéŕ. À ƃüîļţ-îñ ŵŕîţéŕ'š đéçļàŕàţîöñ îš þŕöƃéđ öñçé ŵĥéñ îţ îš ŕéĝîšţéŕéđ, ţĥé ŵàý Generative àñđ InlineAnnotations àŕé. À þļüĝîñ ƒöŕḿàţ đéçļàŕéš writable_attrs àñđ synthesizes îñ îţš ḿàñîƒéšţ éñţŕý, ŕéàđ đüŕîñĝ đîšçöṽéŕý ŵîţĥöüţ ļàüñçĥîñĝ ţĥé þļüĝîñ, àñđ ţĥé þļüĝîñ ĥöšţ ŕéçöŕđš ţĥéḿ ŵĥéñ îţ ŕéĝîšţéŕš ţĥé þļüĝîñ'š ŵŕîţéŕ. À þļüĝîñ ţĥàţ ŕéþļàçéš à ƃüîļţ-îñ ƒöŕḿàţ'š ŵŕîţéŕ ŕéþļàçéš îţš đéçļàŕàţîöñ ŵîţĥ ţĥéḿ, àñ éḿþţý öñé îñçļüđéđ.

AttrWriter.WriteAttr šþéļļš à ñéŵ ṽàļüé îñţö ţĥé çöđé'š ñàţîṽé đàţà, éšçàþéđ ƒöŕ ŵĥéŕé îţ šîţš, üþđàţéš ţĥé çöđé'š àţţŕîƃüţéš ţö ḿàţçĥ ŵĥàţ ţĥé ŕéàđéŕ ŵöüļđ ŕéàđ, àñđ ŕéţüŕñš ţĥé šàḿé ŕüñš îñ ţĥé šàḿé öŕđéŕ. CodeSynthesizer ŕéţüŕñš ƃöţĥ ĥàļṽéš öƒ à ñéŵ çöđé àš ţĥé ƒöŕḿàţ'š ŕéàđéŕ ŵöüļđ ŕéàđ ţĥéḿ ƃàçķ, ñàţîṽé đàţà, šüƃţýþé, đîšþļàý àñđ çöñšţŕàîñţš îñçļüđéđ. Ţĥé çĥàñĝé àþþļîéŕ çàļļš ţĥéḿ ŵĥéñ îţ àþþļîéš ţĥé öþéŕàţîöñ (change.WriterCapabilities ĥàñđš îţ ţĥé ŵŕîţéŕ), šö ţĥé ƃļöçķ ĥöļđš ţĥé ƃýţéš îţ îš ŵŕîţţéñ ŵîţĥ, àñđ éṽéŕý ŵŕîţé þàţĥ, šķéļéţöñ ŕéþļàý îñçļüđéđ, ŵŕîţéš ţĥéḿ. À þļüĝîñ'š ŵŕîţéŕ ŕüñš öüţšîđé ţĥé þŕöçéšš: ţĥé çöđé îţ ŕéçéîṽéš çàŕŕîéš ţĥé ñéŵ ṽàļüé àḿöñĝ îţš àţţŕîƃüţéš, öŕ à ñéŵ çöđé çàŕŕîéš îţš ţýþé àñđ àţţŕîƃüţéš àñđ ñö đàţà, àñđ ţĥé þļüĝîñ'š ŵŕîţéŕ šþéļļš îţ.

Éàçĥ đéçļàŕàţîöñ àļšö ŕéƒüšéš ŵĥàţ îţ çàññöţ ŵŕîţé, ŵîţĥ ţĥé ŕéàšöñ îñ ţĥé ŕéƒüšàļ:

ƑöŕḿàţŴŕîţéšŔéƒüšéš, ŵîţĥ à ŕéàšöñ
ĤŢḾĻhref öƒ link:hyperlink, src öƒ media:image; ñéŵ fmt:bold àñđ fmt:italic îñ ţĥé éļéḿéñţš ţĥé ƒöŕḿàţ'š þŕöĵéçţîöñ öƒ ţĥé ṽöçàƃüļàŕý ñàḿéš (<strong>, <em>), àñđ ñéŵ link:hyperlink (<a href>)à ţîţļé öŕ àļţ ţéẋţ, ŵĥîçĥ ţĥé ŕéàđéŕ šüŕƒàçéš àš à ƃļöçķ öƒ îţš öŵñ; à ñéŵ çöđé îñ àñ àţţŕîƃüţé ṽàļüé, ţĥé đöçüḿéñţ ţîţļé öŕ à ţéẋţàŕéà; à ļîñķ îñšîđé öŕ àŕöüñđ à ļîñķ öŕ à ƃüţţöñ, ŵĥéţĥéŕ ţĥàţ éļéḿéñţ îš à çöđé öƒ ţĥé ƃļöçķ öŕ ḿàŕķüþ ţĥé ƃļöçķ šîţš îñšîđé
Ḿàŕķđöŵñţĥé đéšţîñàţîöñ öƒ àñ îñļîñé ļîñķ öŕ îḿàĝé; ñéŵ **…**, *…* àñđ […](href)à ŕéƒéŕéñçé ļîñķ, ŵĥöšé đéšţîñàţîöñ îš îñ à đéƒîñîţîöñ öţĥéŕ ļîñķš ḿàý šĥàŕé; àñ àüţöļîñķ; à ţîţļé, ŵĥîçĥ îš ţéẋţ öƒ ţĥé ƃļöçķ; à ļîñķ àƒţéŕ à !, ŵĥîçĥ ŵöüļđ ŕéàđ àš àñ îḿàĝé; ḿàŕķüþ à ƃàçķšļàšĥ îñ ţĥé ţéẋţ ŵöüļđ éšçàþé; éḿþĥàšîš ÇöḿḿöñḾàŕķ ŵöüļđ ñöţ ŕéàđ àš éḿþĥàšîš, šüçĥ àš öñé šţàŕţîñĝ ŵîţĥ à šþàçé; à ñéŵ çöđé îñ à çöđé šþàñ öŕ à ļîţéŕàļ ƃļöçķ
ẊḾĻàñý àţţŕîƃüţé àñ îñļîñé éļéḿéñţ'š çöđé ŕéçöŕđš (* ƒöŕ éṽéŕý ţýþé àñđ àţţŕîƃüţé)àñ àţţŕîƃüţé ţĥé éļéḿéñţ đöéš ñöţ šþéļļ, šîñçé ţĥé ƒöŕḿàţ ĥàš ñö šçĥéḿà ţö šàý ŵĥîçĥ îţ ḿàý çàŕŕý; à ñàḿéšþàçé đéçļàŕàţîöñ; àñ àţţŕîƃüţé ţĥé ŕéàđéŕ šüŕƒàçéš àš à ƃļöçķ; àñ àţţŕîƃüţé ţĥé ŕéàđéŕ ŕéàđš àš àñ îñšţŕüçţîöñ

Ţĥé ẊḾĻ ŕéàđéŕ ŕéçöŕđš öñ àñ îñļîñé éļéḿéñţ'š çöđé ţĥé àţţŕîƃüţéš set_attribute çàñ çĥàñĝé, šö à ŕéàđ šĥöŵš ţĥéḿ. Îţ ļéàṽéš öüţ ţĥé àţţŕîƃüţéš ŵĥöšé ṽàļüé đéçîđéš ĥöŵ ţĥé đöçüḿéñţ ŕéàđš: xml:lang, xml:space àñđ ţĥé öţĥéŕ xml: àţţŕîƃüţéš, ţĥé ÎŢŠ àţţŕîƃüţéš, àñđ àñý àţţŕîƃüţé à ŕüļé öƒ ţĥé ŕéàđéŕ'š çöñƒîĝüŕàţîöñ öŕ öƒ ţĥé đöçüḿéñţ'š ÎŢŠ ŕüļéš šéļéçţš, ţéšţš öŕ þöîñţš àţ. À çĥàñĝé ţö öñé öƒ ţĥöšé ŵöüļđ çĥàñĝé ŵĥàţ ţĥé ñéẋţ ŕéàđ éẋţŕàçţš.

Ţĥé Ḿàŕķđöŵñ ŵŕîţéŕ þàŕšéš à ñéŵ çöđé'š ḿàŕķüþ îñ þļàçé, ŵîţĥ ţĥé ţéẋţ àŕöüñđ îţ, üšîñĝ ţĥé ŕéàđéŕ'š þàŕšéŕ, àñđ ŵŕîţéš ţĥé çöđé öñļý ŵĥéŕé îţ ŕéàđš ƃàçķ àš ţĥàţ çöđé öṽéŕ éẋàçţļý ţĥé ŕàñĝé àñđ ļéàṽéš éṽéŕý öţĥéŕ þîéçé öƒ ḿàŕķüþ îñ ţĥé ƃļöçķ ŕéàđîñĝ àš ƃéƒöŕé. Ţĥé ŕéƒüšàļš àƃöṽé ĝîṽé ţĥé çöḿḿöñ çàüšéš à ŕéàšöñ öƒ ţĥéîŕ öŵñ, àñđ ţĥé þàŕšé ŕéƒüšéš àñý öţĥéŕ. Îñ à ţàƃļé çéļļ à ļîñķ'š đéšţîñàţîöñ šþéļļš à þîþé àš \|, àñđ ţĥé ŕéàđéŕ ŕéàđš îţ ŵîţĥöüţ ţĥé ƃàçķšļàšĥ, šö à đéšţîñàţîöñ šéţ ŵîţĥ à þîþé ŕéàđš ƃàçķ àš šéţ.

Àñ éđîţ ţĥàţ çĥàñĝéš à ƃļöçķ'š çöđéš àñđ ļéàṽéš îţš ţéẋţ àš ŕéàđ (à set_attribute, à mark) îš ŵŕîţţéñ ƃý ţĥé ĤŢḾĻ ŵŕîţéŕ àš à þàţçĥ öƒ ţĥé ƃļöçķ'š öŵñ ƃýţéš: éàçĥ çĥàñĝéđ çöđé'š ḿàŕķüþ îš ŕéþļàçéđ, éàçĥ ñéŵ çöđé îš îñšéŕţéđ ŵĥéŕé îţ šîţš îñ ţĥé ţéẋţ, àñđ ţĥé ļîñé ƃŕéàķš, îñđéñţàţîöñ àñđ çĥàŕàçţéŕš ţĥé ŕéàđéŕ ñöŕḿàļîžéđ öŕ ţĥé éñçöđîñĝ þàšš ŵöüļđ ŕéšþéļļ ķééþ ţĥé đöçüḿéñţ'š šþéļļîñĝ.

Ţĥé öþéŕàţîöñš ḿàţŕîẋ þŕöṽéš éṽéŕý đéçļàŕàţîöñ. TestCapabilityMatrix (core/formats/opsmatrix_capabilities_test.go) ŕéàđš à ƒîẋţüŕé, àþþļîéš ţĥé öþéŕàţîöñ ţĥŕöüĝĥ ţĥé çĥàñĝé àþþļîéŕ ŵîţĥ ţĥé ŵŕîţéŕ'š çàþàƃîļîţîéš, ŵŕîţéš ţĥé đöçüḿéñţ ţĥŕöüĝĥ ţĥé šàḿé ŵŕîţéŕ, àñđ àššéŕţš ţĥàţ ţĥé öüţþüţ îš ţĥé îñþüţ ŵîţĥ éẋàçţļý ţĥé çéļļ'š çĥàñĝé, šþéļļéđ àñđ éšçàþéđ àš ţĥé çéļļ ñàḿéš îţ, àñđ ţĥàţ éṽéŕý ƃļöçķ ŕéàđš ƃàçķ àš ţĥé öþéŕàţîöñ ļéƒţ îţ. Éàçĥ mark çéļļ àļšö ŕüñš àš à set_content ñàḿîñĝ ţĥé ñéŵ çöđé îñ à ŕüñš þàýļöàđ. Ŕéƒüšàļ çéļļš àššéŕţ ţĥé ŕéàšöñ àñđ àñ üñçĥàñĝéđ đöçüḿéñţ. TestCapabilityMatrixCoversEveryDeclaration ƒàîļš ţĥé ƃüîļđ ŵĥéñ à ƃüîļţ-îñ ŵŕîţéŕ đéçļàŕéš àñ àţţŕîƃüţé, à ţýþé, à šţŕüçţüŕàļ öŕ à ñàţîṽé öþéŕàţîöñ ţĥàţ ñö çéļļ þŕöṽéš. À ŵîļđçàŕđ àţţŕîƃüţé đéçļàŕàţîöñ çöüñţš àš þŕöṽéñ öñļý ŵîţĥ þàššîñĝ çéļļš öñ ţŵö àţţŕîƃüţéš àñđ à çéļļ ţĥàţ ŕéƒüšéš öñé.

change.FormatOps ƃüîļđš ţĥé çĥàñĝé šéŕṽîçé'š đéšçŕîþţîöñ öƒ à ƒöŕḿàţ ƒŕöḿ ţĥé öþéŕàţîöñš îţš ŕöüñđ ţŕîþ çàŕŕîéš àñđ ţĥéšé đéçļàŕàţîöñš; àñ öþéŕàţîöñ ñöţĥîñĝ đéçļàŕéš îš null, àñđ ŕéƒüšéđ àš unsupported.

Šķéļéţöñš àŕé ţýþéđ þéŕ ƒöŕḿàţ. À SkeletonStore çàŕŕîéš àñ OriginFormat šţàḿþ, àñđ format.WireSkeleton(store, reader, writer) çöññéçţš à ŕéàđéŕ'š šķéļéţöñ éḿîššîöñ ţö à ŵŕîţéŕ öñļý ŵĥéñ ţĥéý àŕé ţĥé šàḿé ƒöŕḿàţ, šö ţĥé ŕüļé ţĥàţ à šķéļéţöñ ƒŕöḿ ƒöŕḿàţ À îš ƒöŕéîĝñ ţö ƒöŕḿàţ Ƃ'š ŵŕîţéŕ îš éñƒöŕçéđ çéñţŕàļļý, ñöţ ļéƒţ ţö éàçĥ çàļļ šîţé. À çŕöšš-ƒöŕḿàţ çöñṽéŕšîöñ ţĥéŕéƒöŕé ñéṽéŕ ƒééđš à ƒöŕéîĝñ šķéļéţöñ îñţö ţĥé ţàŕĝéţ ŵŕîţéŕ; ţĥàţ ŵŕîţéŕ ţàķéš ţĥé ĝéñéŕàţîṽé çöñţéñţ-ḿöđéļ ŕöüţé éṽéŕý ŵŕîţéŕ šĥàŕéš.

Ƃļöçķš à ŵŕîţéŕ çàñ àđđ àñđ ŕéḿöṽé​

À šķéļéţöñ ĥàš à šļöţ ƒöŕ éṽéŕý ƃļöçķ ţĥé ŕéàđéŕ ŕéàđ àñđ ñöñé ƒöŕ à ƃļöçķ ñöƃöđý ŕéàđ, šö ŕéþļàýîñĝ îţ çàñ çĥàñĝé à ƃļöçķ'š çöñţéñţ àñđ ñöţĥîñĝ ḿöŕé. Àđđîñĝ à ƃļöçķ ţö à đöçüḿéñţ, öŕ ŕéḿöṽîñĝ öñé ţöĝéţĥéŕ ŵîţĥ ţĥé ḿàŕķüþ àŕöüñđ îţ, çĥàñĝéš ţĥé đöçüḿéñţ'š šţŕüçţüŕé, àñđ öñļý ţĥé ƒöŕḿàţ ķñöŵš ŵĥàţ ţĥàţ ḿàŕķüþ îš. Îñ à ķéý-ṽàļüé çàţàļöĝ îţ îš šḿàļļ: à ƃļöçķ'š šĥéļļ îš îţš ķéý àñđ ţĥé ṽàļüé ƃéšîđé îţ.

À ŵŕîţéŕ ţĥàţ çàñ ŵŕîţé šüçĥ àñ éđîţ đéçļàŕéš îţ. StructureEditor.Structural ļîšţš ţĥé öþéŕàţîöñš îţ ŵŕîţéš, insert_block àñđ delete_block, àñđ StructureEditor.EditStructure ḿàķéš ţĥéḿ: ĝîṽéñ à ŵĥöļé đöçüḿéñţ àñđ ţĥé éđîţš îñ öŕđéŕ, îţ ŕéţüŕñš ţĥé đöçüḿéñţ ŵîţĥ à ñéŵ ķéý àñđ ṽàļüé ƃéšîđé à ñàḿéđ ƃļöçķ (öŕ ļàšţ), öŕ à ƃļöçķ'š ķéý àñđ ṽàļüé ŕéḿöṽéđ ŵîţĥ ţĥé šéþàŕàţöŕ ţĥàţ ķéþţ îţ ƒŕöḿ îţš ñéîĝĥƃöüŕš, àñđ éṽéŕý öţĥéŕ ƃýţé àš îţ ŵàš. Îţ ñàḿéš à ƃļöçķ ƃý ţĥé ķéý îţš ŕéàđéŕ ĝîṽéš îţ àñđ ƒîñđš à ƃļöçķ îţ ŕéàđ ƃý ŵĥàţ ţĥé ŕéàđéŕ ŕéçöŕđéđ öñ îţ. Àñ éđîţ îţ çàññöţ ḿàķé îš à StructureError ñàḿîñĝ ţĥé éđîţ àñđ ŵĥý: ţĥé ķéý îš ĥéļđ àļŕéàđý, ţĥé ƃļöçķ îš ñöţ ţĥéŕé, öŕ ţĥé ƒöŕḿàţ ĥàš ñö ŵàý ţö ŵŕîţé îţ ţĥéŕé. format.StructuralOps ŕéþöŕţš ŵĥàţ à ŵŕîţéŕ đéçļàŕéš àñđ ŵŕîţéš, àñđ ProbeEditCapabilities ŕéçöŕđš îţ àḿöñĝ ţĥé ŵŕîţéŕ'š éđîţ çàþàƃîļîţîéš (EditCapabilities.Structural), ŵĥîçĥ ţĥé çĥàñĝé šéŕṽîçé (É-09) đéšçŕîƃéš à ƒöŕḿàţ àñđ à đöçüḿéñţ ƃý, šö đéšçŕîƃîñĝ à ƒöŕḿàţ àñđ àþþļýîñĝ à çĥàñĝé šéţ àĝŕéé; à þļüĝîñ ƒöŕḿàţ đéçļàŕéš ñöñé. À ŵŕîţéŕ àñšŵéŕš Structural ƒöŕ îţš öŵñ çöñƒîĝüŕàţîöñ: ŵĥéŕé à đöçüḿéñţ'š çöñƒîĝüŕàţîöñ ḿàķéš ḿöŕé ţĥàñ ţĥé ķéý àñđ îţš ṽàļüé þàŕţ öƒ à ƃļöçķ'š šĥéļļ, đéšçŕîƃîñĝ ţĥàţ đöçüḿéñţ ŕéþöŕţš ñéîţĥéŕ öþéŕàţîöñ àñđ àþþļýîñĝ öñé îš ŕéƒüšéđ.

À ñéŵ ƃļöçķ ĝöéš ŵĥéŕé à ŕéàđéŕ ŵöüļđ ļööķ ƒöŕ îţš ķéý þàţĥ. Ŕéàđéŕš ñàḿé à ṽàļüé îñ à ñéšţéđ öƃĵéçţ àñđ öñé üñđéŕ à ƒļàţ đöţţéđ ķéý ţĥé šàḿé ŵàý (nav.checkout), šö ţĥé ŵŕîţéŕ þüţš ţĥé ñéŵ ķéý îñ ţĥé đééþéšţ öƃĵéçţ öŕ ḿàþþîñĝ ţĥàţ ţĥé šţàŕţ öƒ îţš ķéý þàţĥ ñàḿéš, ƃéšîđé îţš àñçĥöŕ öŕ ļàšţ ţĥéŕé, àñđ ƃüîļđš ţĥé öƃĵéçţš öŕ ḿàþþîñĝš ţĥé þàţĥ ñàḿéš ţĥàţ ţĥé đöçüḿéñţ ļàçķš. Àñ öƃĵéçţ ţĥàţ àļŕéàđý ñàḿéš ṽàļüéš ƃý ƒļàţ đöţţéđ ķéýš ţàķéš ţĥé ŕéšţ öƒ ţĥé þàţĥ àš öñé ķéý. Àñ àñçĥöŕ öüţšîđé ţĥàţ öƃĵéçţ îš ŕéƒüšéđ.

Ţĥé ĴŠÖÑ, ÝÀḾĻ àñđ ÀŔƂ ŵŕîţéŕš đéçļàŕé ƃöţĥ öþéŕàţîöñš:

  • ĴŠÖÑ àđđš à ḿéḿƃéŕ ŵîţĥ ţĥé îñđéñţàţîöñ, ļîñé ƃŕéàķš àñđ çöļöñ šþàçîñĝ ţĥé öƃĵéçţ àļŕéàđý üšéš, àñđ à ƃüîļţ öƃĵéçţ ƒöļļöŵš ţĥé šàḿé ļàýöüţ öñé šţéþ đééþéŕ. Îţ ŕéḿöṽéš à ḿéḿƃéŕ ŵîţĥ ţĥé çöḿḿà ƃéƒöŕé öŕ àƒţéŕ îţ àñđ à çöḿḿéñţ ţĥàţ éñđš öñ ţĥé ḿéḿƃéŕ'š öŵñ ļîñé. À ṽàļüé îñ àñ àŕŕàý îš ñàḿéđ ƃý îţš þöšîţîöñ àñđ îš ñéṽéŕ àđđéđ öŕ ŕéḿöṽéđ. À çöñƒîĝüŕàţîöñ ţĥàţ ŕéàđš à ƃļöçķ'š ñöţé, îđ öŕ ḿéţàđàţà ƒŕöḿ ţĥé ḿéḿƃéŕš ƃéšîđé îţ (noteRules, idRules, useIdStack, genericMetaRules, maxwidthRules) đéçļàŕéš ñéîţĥéŕ öþéŕàţîöñ, àñđ üñđéŕ useFullKeyPath à ñàḿé šüçĥ àš /nav/home îš ŕéàđ àš ţĥé ķéý þàţĥ îţ šþéļļš.
  • ÝÀḾĻ àđđš à ļîñé àţ ţĥé îñđéñţàţîöñ öƒ ţĥé ḿàþþîñĝ'š ķéýš, àƒţéŕ éṽéŕý ļîñé öƒ ţĥé àñçĥöŕ'š ṽàļüé, öŕ àƃöṽé ţĥé çöḿḿéñţ đîŕéçţļý öṽéŕ ţĥé ķéý îţ ĝöéš ƃéƒöŕé. Îţ ŕéḿöṽéš à ķéý'š ļîñéš ŵîţĥ ţĥàţ çöḿḿéñţ, ŵĥîçĥ ţĥé ŕéàđéŕ ŕéàđš àš ţĥé ƃļöçķ'š ñöţé, àñđ ļéàṽéš éṽéŕý öţĥéŕ çöḿḿéñţ ŵĥéŕé îţ îš. À ķéý îñ à ƒļöŵ ḿàþþîñĝ, öñ à šéǫüéñçé îţéḿ'š đàšĥ ļîñé, ŕéàçĥéđ ţĥŕöüĝĥ àñ àļîàš, ĥöļđîñĝ àñ àñçĥöŕ, öŕ îñšîđé à ñöđé ŵîţĥ àñ àñçĥöŕ îš ŕéƒüšéđ. À ñéŵ ķéý öŕ ṽàļüé îš ŵŕîţţéñ þļàîñ ŵĥéŕé ÝÀḾĻ 1.2 àñđ ÝÀḾĻ 1.1 þàŕšéŕš ƃöţĥ ŕéàđ îţ ƃàçķ àš ţĥé šàḿé šţŕîñĝ, àñđ đöüƃļé-ǫüöţéđ öţĥéŕŵîšé (yes, off, 1:20), àñđ ŕéḿöṽîñĝ à ḿàþþîñĝ'š ļàšţ ķéý ļéàṽéš îţ {}, àƒţéŕ ţĥé ţàĝ îţ çàŕŕîéš.
  • ÀŔƂ ķééþš à ḿéššàĝé'š @ ḿéţàđàţà ƃéšîđé îţ: à ḿéššàĝé àđđéđ àƒţéŕ àñöţĥéŕ ĝöéš àƒţéŕ ţĥàţ ḿéššàĝé'š ḿéţàđàţà, öñé àđđéđ ƃéƒöŕé ĝöéš ƃéƒöŕé ḿéţàđàţà ţĥàţ þŕéçéđéš îţ, àñđ à ŕéḿöṽéđ ḿéššàĝé ţàķéš îţš ḿéţàđàţà ŵîţĥ îţ. Àñ îđ šţàŕţîñĝ ŵîţĥ @ îš ŕéƒüšéđ.

Ŕéàđéŕ öüţþüţ þöļîçý: ţĥŕéé đéšţîñàţîöñš​

Ţĥé šķéļéţöñ îš ñöţ ţĥé öñļý ĥöḿé ƒöŕ ñöñ-ţŕàñšļàţàƃļé çöñţéñţ. À ŕéàđéŕ çļàššîƒîéš éàçĥ ƒŕàĝḿéñţ ţĥŕéé ŵàýš:

ƑŕàĝḿéñţĐéšţîñàţîöñ
Ţŕàñšļàţàƃļé þŕöšéBlock{Translatable: true}; ţĥé þîþéļîñé þŕöçéššéš îţ
Þüŕé šţŕüçţüŕé (đéļîḿîţéŕš, ǫüöţîñĝ, ŵĥîţéšþàçé)šķéļéţöñ ƃýţéš
Ñöñ-ţŕàñšļàţàƃļé ƃüţ ḿéàñîñĝƒüļ çöñţéẋţšüŕƒàçéđ; šéé ţĥé ţŵö çĥàññéļš ƃéļöŵ

Ţĥé ţĥîŕđ çàţéĝöŕý (çöđé, ṽéŕƃàţîḿ àñđ ļîţéŕàļ ţéẋţ, çàþţîöñš, àļţ-ţéẋţ, ƒöŕḿüļàš, đö-ñöţ-ţŕàñšļàţé šţŕîñĝš, çöñƒîĝ-éẋçļüđéđ ṽàļüéš, çöḿḿéñţš) îš šüŕƒàçéđ ŕàţĥéŕ ţĥàñ çöļļàþšéđ îñţö ţĥé šéçöñđ. Îţ ƃéçöḿéš çöñţéñţ àñ îñĝéšţîöñ çöñšüḿéŕ çàñ ŕéàđ, ŵĥîļé šţàýîñĝ öüţšîđé ţĥé ţŕàñšļàţîöñ þàýļöàđ.

Ţĥîš îñţŕöđüçéš ñö ñéŵ çöñţéñţ-ḿöđéļ ţýþé. Ţĥé Translatable ƒļàĝ, ţĥé SemanticRole ţàẋöñöḿý, Data, àñđ ñöţéš àŕé àļļ ţĥé çöñţéñţ ḿöđéļ'š (Ƒ-02); ţĥé šķéļéţöñ àñđ šüƃ-šķéļéţöñ ḿéçĥàñîšḿš àŕé ţĥîš ÀĐ'š.

Ţŵö šüŕƒàçîñĝ çĥàññéļš​

Ŵĥàţ à ƒŕàĝḿéñţ îš đéţéŕḿîñéš ŵĥîçĥ çĥàññéļ çàŕŕîéš îţ. Ŕéñđéŕàƃļé çöñţéñţ, ţéẋţ ţĥàţ ĥàš à þļàçé îñ ţĥé ŕéñđéŕéđ đöçüḿéñţ, ƃéçöḿéš à çöñţéñţ ƃļöçķ; öüţ-öƒ-ƃàñđ àññöţàţîöñ, ţéẋţ àƃöüţ ţĥé đöçüḿéñţ, ƃéçöḿéš đàţà öŕ à ñöţé.

ÇĥàññéļÇàŕŕîéŕÜšéđ ƒöŕŔöüñđ-ţŕîþ
Ŕéñđéŕàƃļé çöñţéẋţüàļ çöñţéñţBlock{Translatable:false} + SemanticRole + šķéļéţöñ ŕéƒçöđé ƃļöçķš, ļîţéŕàļ ţéẋţ, çàþţîöñš, àļţ-ţéẋţ, ƒöŕḿüļàš, đö-ñöţ-ţŕàñšļàţé šţŕîñĝš, çöñƒîĝ-éẋçļüđéđ ṽàļüéšṽéŕƃàţîḿ ƃýţéš šţàý îñ ţĥé šķéļéţöñ; ţĥé šüŕƒàçéđ ƃöđý ŕîđéš à šķéļéţöñ ŕéƒ, šö ţĥé ŵŕîţéŕ ŕéþļàýš ţĥé öŕîĝîñàļ éẋàçţļý
Çöḿḿéñţ / ḿéţàđàţà çöñţéẋţData þàŕţ öŕ à ñöţé àññöţàţîöñđéṽéļöþéŕ àñđ ţŕàñšļàţöŕ çöḿḿéñţš, ŕéṽîéŵ àññöţàţîöñš, éđîţöŕîàļ ñöţéšţĥé çöḿḿéñţ ƃýţéš ŕöüñđ-ţŕîþ ṽéŕƃàţîḿ ţĥŕöüĝĥ ţĥé šķéļéţöñ; ţĥé šüŕƒàçéđ çöþý îš îñƒöŕḿàţîöñàļ öñļý

À ƃļöçķ ƒŕöḿ ţĥé ƒîŕšţ çĥàññéļ çàŕŕîéš ţĥé ŕöļé ţĥàţ ñàḿéš îţš ķîñđ (àļţ-ţéẋţ àš RoleCaption, à çöđé ļîšţîñĝ àš RoleCode, àñ éǫüàţîöñ àš RoleFormula, à ñöñ-ţŕàñšļàţàƃļé çéļļ àš RoleTableCell), àñđ îš ƒļàĝĝéđ šö ţŕàñšļàţîöñ šķîþš îţ (É-07). Ţĥé šéçöñđ çĥàññéļ ķééþš çöḿḿéñţ çöñţéẋţ àš đàţà: à çöḿḿéñţ îš ñöţ þàŕţ öƒ ţĥé ŕéñđéŕéđ ţéẋţ, šö þŕöḿöţîñĝ îţ ţö à çöñţéñţ ƃļöçķ ŵöüļđ ḿîšŕéþŕéšéñţ ţĥé đöçüḿéñţ'š šţŕüçţüŕé; îţ šţàýš à Data þàŕţ öŕ à ñöţé ţĥàţ îñĝéšţîöñ çàñ ŕéàđ àñđ ţĥé éđîţöŕ çàñ šĥöŵ.

Ţĥé çöḿḿéñţ ļàýéŕ​

À çĥéçķ ŕéàđš çöḿḿéñţš àš þŕöšé ţĥŕöüĝĥ à ţĥîŕđ þàţĥ ţĥàţ ļéàṽéš ƃöţĥ çĥàññéļš àš ţĥéý àŕé. Ţĥé çöḿḿéñţ ļàýéŕ (core/comment) ļöçàţéš éàçĥ çöḿḿéñţ ŵîţĥ à ĥàļƒ-öþéñ ƃýţé šþàñ àñđ àñ îñçļüšîṽé ļîñé ŕàñĝé, àñđ ƃüîļđš à ƃļöçķ ƒŕöḿ îţ ƒöŕ çĥéçķîñĝ. Ţĥöšé ƃļöçķš ñéṽéŕ éñţéŕ à ŕéàđéŕ'š þàŕţ šţŕéàḿ, šö ŕöüñđ-ţŕîþ àñđ þàŕîţý àŕé üñàƒƒéçţéđ.

À ƒîļé ñö ƒöŕḿàţ ŕéàđéŕ çöṽéŕš ŕéàçĥéš ţĥé ļàýéŕ ţĥŕöüĝĥ à ļàñĝüàĝé þŕöṽîđéŕ. Ţĥé Ĝö þŕöṽîđéŕ üšéš go/parser ƒöŕ þöšîţîöñš àñđ go/doc/comment ƒöŕ ţĥé îñţéŕîöŕ, ƒŕöḿ ţĥé šţàñđàŕđ ļîƃŕàŕý. Îţ çļàššîƒîéš đîŕéçţîṽéš, ĝéñéŕàţéđ ƒîļéš, ţĥé çĝö þŕéàḿƃļé àñđ éẋàḿþļé öüţþüţ àš ñöţ àđđŕéššàƃļé, àñđ ţüŕñš çöđé ƃļöçķš àñđ ŕéƒéŕéñçéš ţö đéçļàŕàţîöñš îñţö þļàçéĥöļđéŕš, šö à çĥéçķ ŕéàđš šéñţéñçéš öñļý. Ţĥé þàŕšéŕ çöñšüḿéš à ļîšţ îţéḿ'š ḿàŕķéŕ, šö éàçĥ îţéḿ öþéñš ŵîţĥ à þļàçéĥöļđéŕ öƒ ţýþé list:item (comment.TypeListItem) ţĥàţ ķééþš öñé îţéḿ'š þŕöšé àþàŕţ ƒŕöḿ ţĥé ñéẋţ. À þŕöṽîđéŕ îš ñöţ à ƒöŕḿàţ: ñöţĥîñĝ ŕéĝîšţéŕš öñé îñ ţĥé ƒöŕḿàţ ŕéĝîšţŕý, àñđ à ŕéçîþé đéçļàŕéš šüçĥ ƒîļéš ŵîţĥ comments: true öñ à çöñţéñţ îţéḿ, ŵĥîçĥ éṽéŕý þàţĥ ţĥàţ ŕéàđš ṽàļüéš ţĥéñ þàššéš öṽéŕ (ResolvedFile.CommentsOnly).

À þļüĝîñ çàñ šüþþļý ļàñĝüàĝé þŕöṽîđéŕš ţöö. Ţĥé šöüŕçéçöđé þļüĝîñ ļîšţš ţĥé ļàñĝüàĝéš îţ ŕéàđš îñ îţš ḿàñîƒéšţ, šüçĥ àš ŢýþéŠçŕîþţ, Þýţĥöñ àñđ ÇŠŠ, àñđ ţĥé ĥöšţ ŕéĝîšţéŕš à þŕöṽîđéŕ ƒöŕ éàçĥ ļàñĝüàĝé'š éẋţéñšîöñš ţĥàţ šéñđš à ƒîļé'š ƃýţéš ţö ţĥé þļüĝîñ àñđ ŕéàđš ƃàçķ ţĥé ļöçàţéđ çöḿḿéñţš. Ţĥé þļüĝîñ þàŕšéš éàçĥ ƒîļé ŵîţĥ ţĥé ļàñĝüàĝé'š ţŕéé-šîţţéŕ ĝŕàḿḿàŕ, šö à ḿàŕķéŕ îñšîđé à šţŕîñĝ, à ţéḿþļàţé ļîţéŕàļ, à ŕéĝüļàŕ éẋþŕéššîöñ, ĴŠẊ ţéẋţ, à ĥéŕéđöç öŕ àñ üñǫüöţéđ ÇŠŠ url() îš çöñţéñţ. Îţ šéţš àšîđé ţĥé đîŕéçţîṽéš ţĥé ļàñĝüàĝé'š ţööļš ŕéàđ, šüçĥ àš eslint-disable, # noqa, # shellcheck àñđ ţĥé šĥéƃàñĝ, éṽéŕý çöḿḿéñţ îñ à ƒîļé ŵĥöšé ĥéàđéŕ šàýš à ĝéñéŕàţöŕ öŵñš îţ, àñđ ƃļàñķ çöḿḿéñţ ļîñéš. Îñ ŢýþéŠçŕîþţ àñđ ĴàṽàŠçŕîþţ à /** */ ƃļöçķ îš à đöç çöḿḿéñţ öñļý ŵĥéñ ñöţĥîñĝ ƃüţ ŵĥîţéšþàçé šéþàŕàţéš îţ ƒŕöḿ à đéçļàŕàţîöñ, àñđ îţš ţàĝš, îñļîñé ļîñķš àñđ çöđé šþàñš àŕé þļàçéĥöļđéŕš. Îñ Ŕüšţ /// àñđ /** */ đöçüḿéñţ ţĥé îţéḿ àƒţéŕ ţĥéḿ àñđ //! àñđ /*! */ ţĥé ḿöđüļé ţĥéý šîţ îñ. Ĵàṽà'š Ĵàṽàđöç àñđ Ç#'š ẊḾĻ đöçüḿéñţàţîöñ çöḿḿéñţš đöçüḿéñţ ţĥé đéçļàŕàţîöñ àƒţéŕ ţĥéḿ, àñđ ţĥéîŕ ĤŢḾĻ àñđ ẊḾĻ ţàĝš àŕé þļàçéĥöļđéŕš. Ç àñđ Ç++ ƒîļéš àŕé àļšö ŕéàđ ƃý à ļéẋîçàļ šçàñ ţĥàţ šĥàŕéš ñöţĥîñĝ ŵîţĥ ţĥé ĝŕàḿḿàŕ, àñđ à ƒîļé îš ļöçàţéđ öñļý ŵĥéñ ţĥé ţŕéé ŕéþöŕţš à çöḿḿéñţ àţ éẋàçţļý ţĥé šþàñš ţĥé šçàñ ŕéàđš. À ƒîļé ŵĥöšé ḿàçŕöš ļéàṽé šýñţàẋ éŕŕöŕš îñ ţĥé ţŕéé îš šţîļļ ļöçàţéđ, àñđ öñé ŵĥéŕé ţĥé ĝŕàḿḿàŕ ḿîšþļàçéš àñý çöḿḿéñţ îš ñöţ. À çöḿḿéñţ ĥàš ţĥé šüƃĵéçţ comment àñđ đöçüḿéñţš ñöţĥîñĝ ŵĥéñ ţĥé đéçļàŕàţîöñ îţ đöçüḿéñţš, öŕ öñé îţš šüƃĵéçţ þàţĥ ñàḿéš, ĥöļđš à šýñţàẋ éŕŕöŕ. À Ŕüƃý ƒîļé ţĥé šöüŕçéçöđé ƒöŕḿàţ ŕéàđš ĥàš îţš đéçļàŕéđ çöḿḿéñţš ŕéàđ ţĥŕöüĝĥ ţĥé šàḿé þļüĝîñ'š çöḿḿéñţ þŕöṽîđéŕ, ƃéšîđé ţĥé ƒöŕḿàţ'š šţŕîñĝš: à ƒöŕḿàţ ţĥàţ šüþþļîéš ñö çöḿḿéñţš öƒ îţš öŵñ ƒàļļš ƃàçķ ţö ţĥé þŕöṽîđéŕ ƒöŕ ţĥé ƒîļé'š ļàñĝüàĝé. À ƒîļé ţĥé ĝŕàḿḿàŕ çàññöţ þàŕšé ŵĥöļé îš ñöţ ļöçàţéđ, àñđ îţš çöḿḿéñţ çĥéçķ đîđ ñöţ ŕüñ. Ţĥé çàñàŕý çöḿéš ƒŕöḿ ţĥé þļüĝîñ'š ḿàñîƒéšţ àñđ ĝöéš ţĥŕöüĝĥ ţĥé þļüĝîñ ƃéšîđé éṽéŕý ŕéàļ ƒîļé. Ŵĥéñ ñö îñšţàļļéđ þļüĝîñ ŕéàđš à đéçļàŕéđ ƒîļé'š ļàñĝüàĝé, à çĥéçķ öṽéŕ ţĥé þŕöĵéçţ ŕéþöŕţš ţĥé ƒîļé üñŕéàđ àñđ ñàḿéš ţĥé þļüĝîñ ţö îñšţàļļ.

À ƒöŕḿàţ ŵĥöšé ŕéàđéŕ þàŕšéš à ƒîļé çàñ šüþþļý ţĥàţ ƒîļé'š çöḿḿéñţš ţöö. Šüçĥ à þŕöṽîđéŕ šçàñš ţĥé ƃýţéš àñđ ŕéƒüšéš à đöçüḿéñţ ŵĥöšé çöḿḿéñţš îţš šçàñ àñđ ţĥé ƒöŕḿàţ'š þàŕšéŕ đîšàĝŕéé àƃöüţ, šö à çöḿḿéñţ îš ñéṽéŕ þļàçéđ àþþŕöẋîḿàţéļý. Ţĥé ÝÀḾĻ ƒöŕḿàţ šçàñš ƒöŕ çöḿḿéñţš öüţšîđé ǫüöţéđ šçàļàŕš àñđ ƃļöçķ šçàļàŕ ƃöđîéš, àñđ ĥöļđš ţĥé šçàñ ţö ţĥé çöḿḿéñţ ļîñéš ţĥé ÝÀḾĻ þàŕšéŕ ŕéþöŕţš.

Éṽéŕý ƒöŕḿàţ ŵĥöšé ŕéàđéŕ ŕéàđš à þļàîñ ẊḾĻ ƒîļé šĥàŕéš ţĥé ẊḾĻ ƒöŕḿàţ'š þŕöṽîđéŕ, ŕéĝîšţéŕéđ üñđéŕ éàçĥ ƒöŕḿàţ'š öŵñ ñàḿé. Îţ šçàñš ƒöŕ <!-- --> öüţšîđé ţàĝš, ÇĐÀŢÀ šéçţîöñš, þŕöçéššîñĝ îñšţŕüçţîöñš àñđ đéçļàŕàţîöñš, àñđ ĥöļđš éàçĥ çöḿḿéñţ ţö ţĥé öƒƒšéţš encoding/xml ŕéþöŕţš. Îţ ŕéƒüšéš à đöçüḿéñţ ţĥé þàŕšéŕ ŕéĵéçţš, šüçĥ àš öñé ĥöļđîñĝ -- îñšîđé à çöḿḿéñţ, ŵĥîçĥ ţĥé ẊḾĻ šþéçîƒîçàţîöñ ƒöŕƃîđš, àñđ öñé ŵîţĥ à çöḿḿéñţ îñšîđé îţš ĐÖÇŢÝÞÉ, ŵĥîçĥ ţĥé þàŕšéŕ ŕéàđš àš þàŕţ öƒ ţĥé đéçļàŕàţîöñ. Éàçĥ çöḿḿéñţ îš ñàḿéđ ƒöŕ ţĥé éļéḿéñţ îţ šîţš öñ, àš îñ comment/resources/string[greeting]. À ļîñé öƒ çöḿḿéñţéđ-öüţ ḿàŕķüþ ƃéçöḿéš à þļàçéĥöļđéŕ, àñđ ţĥé šüþþŕéššîöñš Þŕéţţîéŕ, ţĥé ĴéţƂŕàîñš ÎĐÉš àñđ ŔéŠĥàŕþéŕ ŕéàđ àŕé đîŕéçţîṽéš. À ƒöŕḿàţ ţĥàţ ķééþš îţš ẊḾĻ îñšîđé àñ àŕçĥîṽé šüþþļîéš ñö çöḿḿéñţš, ƃéçàüšé à çöḿḿéñţ ţĥéŕé ĥàš ñö šþàñ îñ ţĥé ƒîļé.

Ţĥé ĤŢḾĻ ƒöŕḿàţ ŕéàđš çöḿḿéñţš ƃý ţĥé ĤŢḾĻ ţöķéñîžéŕ'š ŕüļéš. Îţ šçàñš ƒöŕ <!-- öüţšîđé ţàĝš, đöçţýþéš, ƃöĝüš çöḿḿéñţš àñđ ţĥé ţéẋţ öƒ ŕàŵ ţéẋţ éļéḿéñţš šüçĥ àš <script>, <style> àñđ <textarea>, çļöšéš à çöḿḿéñţ öñ --> öŕ --!>, àñđ ŕéàđš <!--> àñđ <!---> àš éḿþţý çöḿḿéñţš. Îţ ĥöļđš éàçĥ çöḿḿéñţ ţö ţĥé öƒƒšéţš ţĥé x/net/html ţöķéñîžéŕ ŕéþöŕţš, àñđ ţö ţĥé çöḿḿéñţš ţĥé ĤŢḾĻ þàŕšéŕ ƒîñđš, ŵĥîçĥ ŕéàđš ŠṼĜ àñđ ḾàţĥḾĻ çöñţéñţ ƃý ŕüļéš öƒ îţš öŵñ. Îţ ŕéƒüšéš à đöçüḿéñţ ţĥé ţĥŕéé đîšàĝŕéé öñ, àñđ öñé ţĥàţ éñđš îñšîđé à çöḿḿéñţ. À çöḿḿéñţ îš ñàḿéđ ƒöŕ ţĥé éļéḿéñţ ţĥàţ ƒöļļöŵš îţ, àš îñ comment/p[greeting]. Çöñđîţîöñàļ çöḿḿéñţš, šéŕṽéŕ-šîđé îñçļüđéš, ḿàŕķđöŵñļîñţ îñšţŕüçţîöñš àñđ ţĥé ḿàŕķéŕš Ŕéàçţ ŵŕîţéš îñţö à þàĝé îţ ŕéñđéŕš öñ ţĥé šéŕṽéŕ àŕé đîŕéçţîṽéš.

Ţĥé Ḿàŕķđöŵñ ƒöŕḿàţ ŕéàđš à đöçüḿéñţ àš îţš ŕéàđéŕ đöéš, ŵîţĥ ƒŕöñţ ḿàţţéŕ šéţ àšîđé àñđ ţĥé ƃöđý þàŕšéđ ƃý ţĥé Ḿàŕķđöŵñ þàŕšéŕ. À çöḿḿéñţ îš àñ îñļîñé ĤŢḾĻ çöḿḿéñţ, öŕ à çöḿḿéñţ îñšîđé àñ ĤŢḾĻ ƃļöçķ, ŵĥîçĥ ţĥé ĤŢḾĻ ƒöŕḿàţ'š šçàñ ļöçàţéš. Éṽéŕý <!-- îñ ţĥé ƃöđý ḿüšţ öþéñ öñé öƒ ţĥöšé öŕ šîţ îñ çöñţéñţ, šüçĥ àš à çöđé šþàñ, à ƒéñçéđ öŕ îñđéñţéđ çöđé ƃļöçķ, àñ ĤŢḾĻ ţàĝ öŕ à ƃàçķšļàšĥ éšçàþé, öŕ ţĥé đöçüḿéñţ îš ŕéƒüšéđ. Šö îš à çöḿḿéñţ çļöšîñĝ öñ --!>, ŵĥîçĥ ţĥé Ḿàŕķđöŵñ þàŕšéŕ àñđ àñ ĤŢḾĻ þàŕšéŕ çļöšé îñ đéŕéñţ þļàçéš. À çöḿḿéñţ îš ñàḿéđ ƒöŕ ţĥé šéçţîöñ îţ šîţš îñ, àš îñ comment/install/from-homebrew. Ţĥé Đöçüšàüŕüš truncate ḿàŕķéŕ, ţĥé šéçţîöñ ķàþî ŵŕîţéš îñţö à ŕüļéš ƒîļé (àñđ à kapi:voice þöîñţéŕ šéçţîöñ), ţĥé ḿàŕķéŕš öƒ à ĝéñéŕàţéđ ŕéĝîöñ àñđ ḿàŕķđöŵñļîñţ àñđ Þŕéţţîéŕ îñšţŕüçţîöñš àŕé đîŕéçţîṽéš.

Ţĥé ḾĐẊ ƒöŕḿàţ ŕéàđš à đöçüḿéñţ ŵîţĥ îţš ŕéàđéŕ'š öŵñ šçàñ, ŵĥîçĥ šéþàŕàţéš Ḿàŕķđöŵñ ƒŕöḿ ÉŠḾ šţàţéḿéñţš, ĴŠẊ éļéḿéñţš àñđ ţöþ-ļéṽéļ éẋþŕéššîöñš. À çöḿḿéñţ îš à ţöþ-ļéṽéļ éẋþŕéššîöñ ţĥàţ ĥöļđš öñé /* */ çöḿḿéñţ, šüçĥ àš {/* A note. */}. Éṽéŕý {/* àñđ <!-- îñ ţĥé ƒîļé ḿüšţ öþéñ šüçĥ à çöḿḿéñţ, šîţ îñšîđé öñé, öŕ šîţ îñ çöñţéñţ: çöđé öŕ ƒŕöñţ ḿàţţéŕ îñ à Ḿàŕķđöŵñ šþàñ, ŵĥîçĥ ţĥé Ḿàŕķđöŵñ ƒöŕḿàţ ŕéàđš, çöđé îñ ţĥé Ḿàŕķđöŵñ çĥîļđŕéñ öƒ à ĴŠẊ éļéḿéñţ, öŕ àñ ÉŠḾ šţàţéḿéñţ. À đöçüḿéñţ ŵîţĥ àñ éẋþŕéššîöñ çöḿḿéñţ îñšîđé à ĴŠẊ éļéḿéñţ öŕ à þàŕàĝŕàþĥ, àñ ĤŢḾĻ çöḿḿéñţ, ŵĥîçĥ ḾĐẊ đöéš ñöţ àļļöŵ, öŕ àñ éẋþŕéššîöñ ĥöļđîñĝ ḿöŕé ţĥàñ öñé çöḿḿéñţ îš ŕéƒüšéđ. À ƒîļé ŵĥöšé ƒîŕšţ çöḿḿéñţ šàýš DO NOT EDIT ƃéļöñĝš ţö îţš ĝéñéŕàţöŕ, àñđ îţš çöḿḿéñţš àŕé šéţ àšîđé àš ĝéñéŕàţéđ. Þŕéţţîéŕ, Đöçüšàüŕüš truncate, ḿàŕķđöŵñļîñţ àñđ ÉŠĻîñţ îñšţŕüçţîöñš àŕé đîŕéçţîṽéš.

Ţĥé ÞÖ ƒöŕḿàţ ŕéàđš à çöḿḿéñţ àš à ļîñé ţĥàţ öþéñš ŵîţĥ #, öţĥéŕ ţĥàñ àñ öƃšöļéţé éñţŕý'š #~ ļîñé, àñđ ĥöļđš îţš šçàñ ţö ţĥé çöḿḿéñţš ţĥé ÞÖ ŕéàđéŕ þàŕšéš. Ţŕàñšļàţöŕ çöḿḿéñţš àŕé þŕöšé, ñàḿéđ ƒöŕ ţĥé éñţŕý ţĥéý šîţ îñ, àš îñ comment/menu/Goodbye. Àñ éẋţŕàçţéđ çöḿḿéñţ (#.) îš ŕéŵŕîţţéñ ƃý ţĥé ñéẋţ éẋţŕàçţîöñ àñđ šéţ àšîđé àš ĝéñéŕàţéđ, àñđ ŕéƒéŕéñçéš, ƒļàĝš àñđ à þŕéṽîöüš ḿšĝîđ àŕé ŕéàđ ƃý ĝéţţéẋţ'š ţööļš àñđ šéţ àšîđé àš đîŕéçţîṽéš. À ƒîļé ţĥé ŕéàđéŕ ŕéàđš ţŕàñšçöđéđ, šüçĥ àš öñé îñ ÜŢƑ-16, îš ŕéƒüšéđ, šîñçé à šþàñ îñ ţĥé ţéẋţ ţĥé ŕéàđéŕ ŕéàđš îš ñöţ à šþàñ îñ ţĥé ƒîļé.

Ţĥé þŕöþéŕţîéš ƒöŕḿàţ ŕéàđš à çöḿḿéñţ àš à ļîñé ţĥàţ öþéñš ŵîţĥ # öŕ ! öüţšîđé à ṽàļüé'š çöñţîñüàţîöñ, ĥöļđš îţš šçàñ ţö ţĥé ļîñéš ţĥé þŕöþéŕţîéš ŕéàđéŕ ŕéàđš àš çöḿḿéñţš, àñđ ñàḿéš éàçĥ çöḿḿéñţ ƒöŕ ţĥé ķéý ţĥàţ ƒöļļöŵš îţ. Öķàþî'š éẋţŕàçţîöñ đîŕéçţîṽéš, šüçĥ àš #_skip, àñđ ÎñţéļļîĴ'š # suppress inspection àŕé đîŕéçţîṽéš.

Ƒöŕ à ƒîļé îţš ŕéàđéŕ þàŕšéš, comments: true àđđš ţĥé çöḿḿéñţ ƃļöçķš ţö ţĥé ŕéàđéŕ'š ƃļöçķš ƒöŕ çĥéçķîñĝ, àñđ ţĥé ƒîļé çöñṽéŕĝéš ţĥŕöüĝĥ îţš ŕéàđéŕ üñçĥàñĝéđ. comments: {only: true} ḿàķéš ţĥé çöḿḿéñţ ƃļöçķš ţĥé ƒîļé'š ŵĥöļé çöñţéñţ: ţĥé ƒöŕḿàţ'š þŕöṽîđéŕ ļöçàţéš ţĥéḿ, ţĥé ŕéàđéŕ ñéṽéŕ ŕéàđš ţĥé ṽàļüéš, àñđ à çĥéçķ ţĥàţ àšķš ƒöŕ ŕéàđéŕ ṽàļîđàţîöñ ŕéþöŕţš îţ üñšüþþöŕţéđ. Öñé þŕéđîçàţé, ResolvedFile.CommentsOnly, ĥöļđš ƒöŕ šüçĥ à ƒîļé àñđ ƒöŕ à ƒîļé ñö ŕéàđéŕ çöṽéŕš, àñđ éṽéŕý þàţĥ ţĥàţ ŕéàđš ṽàļüéš þàššéš öṽéŕ ţĥé ƒîļé ƃý îţ: éẋţŕàçţîöñ àñđ đŕîƒţ đéţéçţîöñ (project.ExtractToBlockStore, project.CompareSourceStamps), çöñṽéŕĝéñçé, ƒļöŵ ŕüñš, ḿéŕĝé, kapi extract, ţĥé šöüŕçé àñđ ţàŕĝéţ üñîţš ƃéĥîñđ çöṽéŕàĝé, ţĥé þļàñ àñđ ţĥé šĥîþ ĝàţéš, ţĥé îḿþļîçîţ îñþüţš öƒ kapi stats àñđ kapi inspect, àñđ ţĥé šçàñ à þüšĥ ŕéàđš. À çĥéçķ ŕéàđš šüçĥ à ƒîļé ţĥŕöüĝĥ checkFormats.commentsOnly àñđ à šöüŕçé üñîţ ñàŕŕöŵéđ ƃý VerifyUnit.OnlyComments, ƒöŕ ŵĥîçĥ readSource ŕéàđš ñö ṽàļüé. À çĥéçķ öƒ ƒîļéš ñàḿéđ öñ ţĥé çöḿḿàñđ ļîñé öŕ ţĥŕöüĝĥ ḾÇÞ check_file ŕéàđš ţĥéîŕ ṽàļüéš ţöö, àţ ţĥé þöîñţ ţĥé çöñţéñţ ŕéšöļṽéš ţö þàšţ ţĥé îţéḿ (KapiProject.ContentItemForPath). Àñ îţéḿ đéçļàŕéđ ƒöŕ çöḿḿéñţš àļöñé çļàîḿš ţĥé ṽàļüéš öƒ ñö ƒîļé, ŵĥéŕéṽéŕ ţĥé ŕéçîþé ļîšţš îţ: ţĥé ƒîŕšţ öţĥéŕ îţéḿ ţĥàţ ḿàţçĥéš à ƒîļé çļàîḿš àñđ ŕéàđš îţš ṽàļüéš, àñđ ResolvedFile.CommentItem ñàḿéš ţĥé îţéḿ àţ ŵĥöšé þöîñţ ţĥé çöḿḿéñţš šîţ, šö à çĥéçķ ŕéàđš ƃöţĥ ļàýéŕš öƒ ţĥàţ ƒîļé. Ļöàđîñĝ ŕéĵéçţš only ƃéšîđé à ţàŕĝéţ, ţàŕĝéţ ļàñĝüàĝéš, à ŕéđàçţîöñ, öŕ à ŕéàđéŕ'š çöñƒîĝ öŕ þŕéšéţ. À đéçļàŕéđ ƒöŕḿàţ ţĥàţ šüþþļîéš ñö çöḿḿéñţš ļéàṽéš ţĥé çöḿḿéñţ çĥéçķ ñöţ ŕüñ, àñđ à ƒöŕḿàţ ŵîţĥ ñö çöḿḿéñţ ƒöŕḿàţţéŕ ŕéþöŕţš ţĥé ƒöŕḿàţţéŕ àš üñšüþþöŕţéđ.

Éṽéŕý þŕöṽîđéŕ þàššéš öñé çöñƒöŕḿàñçé šüîţé, core/comment/commenttest. À þŕöṽîđéŕ'š ţéšţ šüþþļîéš ƒîẋţüŕéš àñđ îţš öŵñ šçàñ öƒ ţĥé šàḿé ƃýţéš, ḿàđé ŵîţĥöüţ ţĥé þŕöṽîđéŕ, àñđ ţĥé šüîţé ĥöļđš ŵĥàţ ţĥé þŕöṽîđéŕ ļöçàţéđ ţö ţĥàţ šçàñ. Éàçĥ çöḿḿéñţ šîţš îñ éẋàçţļý öñé àđđŕéššàƃļé çöḿḿéñţ öŕ öñé éẋçļüšîöñ. À šþàñ ƃéĝîñš àţ ţĥé çöḿḿéñţ'š öþéñîñĝ ḿàŕķéŕ àñđ éñđš ŵîţĥ ţĥé çöḿḿéñţ, àñđ îţš ļîñé ŕàñĝé îš çöüñţéđ ƒŕöḿ ţĥé ƃýţéš. Ţĥé ŕüñš ķééþ ñö ḿàŕķéŕ, à ḿàŕķéŕ îñšîđé à šţŕîñĝ öŕ öţĥéŕ ļîţéŕàļ çöñţéẋţ îš ñéṽéŕ à çöḿḿéñţ, àñđ ţĥé þŕöṽîđéŕ'š çàñàŕý îš ļöçàţéđ ŵîţĥ îţš đöüƃļéđ ŵöŕđ ƒļàĝĝéđ ƃý ţĥé ĥýĝîéñé çĥéçķ.

À þŕöṽîđéŕ šéţš àšîđé ţĥé đîŕéçţîṽéš îţš ļàñĝüàĝé'š ţööļçĥàîñ ŕéàđš. Ţĥé ḿàŕķéŕš à þŕöĵéçţ'š öŵñ ţööļš ŕéàđ, šüçĥ àš ţĥé okapi-skip: ļîñéš à çöñţŕàçţ àüđîţ çöļļéçţš, àŕé đéçļàŕéđ îñ ţĥé ŕéçîþé, üñđéŕ defaults.comments.directives öŕ àñ îţéḿ'š comments: {directives: [...]}, àñđ ţĥé ļàýéŕ šéţš ţĥéḿ àšîđé ƒöŕ éṽéŕý þŕöṽîđéŕ îñ ţĥé šàḿé ŵàý (comment.Locate). À çöḿḿéñţ ļîñé ŵĥöšé ţéẋţ, àƒţéŕ îţš çöḿḿéñţ ḿàŕķéŕ àñđ ļéàđîñĝ ŵĥîţéšþàçé, šţàŕţš ŵîţĥ à đéçļàŕéđ ḿàŕķéŕ îš àñ éẋçļüšîöñ ŵîţĥ ReasonDirective àñđ ţĥé ḿàŕķéŕ àš îţš ƒöŕḿ. À ḿàŕķéŕ îñšîđé à çöḿḿéñţ šþļîţš îţ. Ţĥé þŕöṽîđéŕ ŕéàđš ţĥé ƒîļé à šéçöñđ ţîḿé ŵîţĥ ţĥé ḿàŕķéŕ ļîñéš ƃļàñķéđ, éàçĥ þîéçé ķééþš ţĥé šüƃĵéçţ öƒ ţĥé çöḿḿéñţ îţ çàḿé ƒŕöḿ, àñđ ţĥé ļàýéŕ ĥöļđš ţĥàţ ŕéàđîñĝ ţö ţĥé ƒîŕšţ ƃýţé ƒöŕ ƃýţé: àŵàý ƒŕöḿ ţĥé ḿàŕķéŕš îţ ḿüšţ ļöçàţé ţĥé šàḿé çöḿḿéñţš ŵîţĥ ţĥé šàḿé ƃýţéš, àñđ îñšîđé à šþļîţ çöḿḿéñţ îţš þîéçéš àñđ ţĥé ḿàŕķéŕš ḿüšţ ĥöļđ éṽéŕý ƃýţé öñçé. À ŕéàđîñĝ ţĥàţ đîšàĝŕééš ļéàṽéš ţĥé ƒîļé'š çöḿḿéñţš üñļöçàţéđ. Ŵĥàţ à çöḿḿéñţ đöçüḿéñţš çöḿéš ƒŕöḿ ţĥé ƒîŕšţ ŕéàđîñĝ, ƃéçàüšé ƃļàñķîñĝ à ļîñé çĥàñĝéš ŵĥàţ šîţš ƃéţŵééñ à đöç çöḿḿéñţ àñđ îţš đéçļàŕàţîöñ, àñđ à þŕöṽîđéŕ ḿàý àţţàçĥ îţ đéŕéñţļý îñ ţĥé šéçöñđ. À þŕöṽîđéŕ'š šĥàŕé öƒ ţĥîš îš LineText, ŵĥîçĥ ŕéàđš öñé çöḿḿéñţ ļîñé àñđ ŕéḿöṽéš îţš ḿàŕķéŕ. À ļîñé îñšîđé à đéļîḿîţéđ çöḿḿéñţ ţĥàţ ŕüñš öṽéŕ šéṽéŕàļ ļîñéš ĥöļđš ñö ḿàŕķéŕ öƒ îţš öŵñ, šö ñö đéçļàŕéđ đîŕéçţîṽé ḿàŕķš îţ.

À ŕéçîþé çàñ àļšö þļàçé à ƒîļé'š çöḿḿéñţš àţ à ĝöṽéŕñàñçé þöîñţ öƒ ţĥéîŕ öŵñ, ŵîţĥ àñ îţéḿ'š comments: {channel: ...} öŕ defaults.comments.channel. À çĥéçķ ţĥéñ ĥöļđš éàçĥ çöḿḿéñţ ƃļöçķ ţö ţĥé ṽöîçé àñđ ţéŕḿš öƒ ţĥàţ þöîñţ àñđ éàçĥ ƃļöçķ ţĥé ŕéàđéŕ éẋţŕàçţš ţö ţĥé îţéḿ'š þöîñţ (Ç-02). Ţĥé ļàýéŕ ḿàŕķš îţš ƃļöçķš (comment.IsBlock), ŵĥîçĥ îš ĥöŵ à çĥéçķ ţéļļš ţĥé ţŵö àþàŕţ.

À ƃļöçķ àļšö ŕéçöŕđš ŵĥéţĥéŕ îţš çöḿḿéñţ đöçüḿéñţš à đéçļàŕàţîöñ (comment.doc) àñđ ŵĥéţĥéŕ îţ đöçüḿéñţš ţĥé þàçķàĝé öŕ ḿöđüļé îţš ƒîļé ƃéļöñĝš ţö (comment.package, comment.PackageDoc). Ţĥé Ĝö þŕöṽîđéŕ àñđ ţĥé šöüŕçéçöđé þļüĝîñ'š Ĵàṽà þŕöṽîđéŕ ĝîṽé ţĥàţ çöḿḿéñţ ţĥé šüƃĵéçţ package, àñđ ţĥé Ŕüšţ þŕöṽîđéŕ ĝîṽéš à ƒîļé'š îññéŕ đöç çöḿḿéñţ ţĥé šüƃĵéçţ module. Ñö öţĥéŕ þŕöṽîđéŕ ĥàš öñé. Ţĥé çöḿḿéñţ ļîḿîţš à ṽöîçé þŕöƒîļé šéţš (Çĥéçķš) ŕéàđ ƃöţĥ ḿàŕķš ţö çĥööšé ţĥé ļîḿîţ à çöḿḿéñţ îš ĥéļđ ţö. File.LineKinds çļàššîƒîéš éàçĥ ļîñé öƒ à ƒîļé ƒŕöḿ ţĥé šþàñš à þŕöṽîđéŕ ļöçàţéđ, àš çöđé, çöḿḿéñţ, þàçķàĝé đöç, šéţ àšîđé öŕ ƃļàñķ, àñđ ţĥé đéñšîţý ļîḿîţ çöüñţš à çĥàñĝé'š àđđéđ ļîñéš ŵîţĥ îţ.

À çöḿḿéñţ çàñ àļšö ƃé ŕéŵŕîţţéñ. À þŕöṽîđéŕ ţĥàţ îḿþļéḿéñţš comment.Rewriter ŕéñđéŕš þŕöšé îñţö îţš ļàñĝüàĝé'š çöḿḿéñţ šýñţàẋ, àñđ comment.Rewrite ĥöļđš ţĥé ŕéšüļţ ţö comment.Contain ƃéƒöŕé àñýţĥîñĝ îš ŵŕîţţéñ. Çöñţàîñ ŕéǫüîŕéš éṽéŕý ƃýţé ƃéƒöŕé àñđ àƒţéŕ ţĥé çöḿḿéñţ'š šþàñ ţö ƃé îđéñţîçàļ. Ţĥé þŕöṽîđéŕ ḿüšţ ļöçàţé ţĥé ŕéŵŕîţţéñ ƒîļé ŵîţĥ ţĥé šàḿé çöḿḿéñţš àñđ šéţ-àšîđé ļîñéš, ḿöṽéđ ƃý ţĥé ŕéŵŕîţé àñđ öţĥéŕŵîšé éǫüàļ. Ţĥé ŕéŵŕîţţéñ çöḿḿéñţ ḿüšţ šîţ öñ ţĥé šàḿé šüƃĵéçţ, ŵîţĥ ţĥé šàḿé đéþŕéçàţîöñ ḿàŕķéŕ àñđ ţĥé šàḿé þļàçéĥöļđéŕš: çöđé ƃļöçķš, ļîñķš, ŕéƒéŕéñçéš àñđ ļîšţ îţéḿš. Ŵĥéŕé ţĥé ļàñĝüàĝé ĥàš à ƒöŕḿàţţéŕ, îţ ḿüšţ àĝŕéé ŵîţĥ ţĥé ŕéŵŕîţţéñ çöḿḿéñţ àñđ ŵîţĥ éṽéŕý çöḿḿéñţ îţ àĝŕééđ ŵîţĥ ƃéƒöŕé, àñđ îţ ḿüšţ ļéàṽé àš ţĥéý àŕé ţĥé ļîñéš öƒ ţĥé ƒîļé îţ ļéƒţ àš ţĥéý ŵéŕé ƃéƒöŕé. Ţĥé ļàšţ ŕüļé ĥöļđš çöđé à ƒöŕḿàţţéŕ àļîĝñš ŵîţĥ à çöḿḿéñţ, šüçĥ àš ţĥé ƃöđý öƒ à öñé-ļîñé ƒüñçţîöñ àƒţéŕ à /* */ çöḿḿéñţ îñ îţš šîĝñàţüŕé. À ŕéŵŕîţé ţĥàţ ƒàîļš àñý öƒ ţĥéšé îš ŕéƒüšéđ ŵîţĥ à ŕéàšöñ, àñđ ñöţĥîñĝ îš ŵŕîţţéñ.

Ţĥé Ĝö þŕöṽîđéŕ ŕéŵŕîţéš ļîñé çöḿḿéñţš àñđ /* */ çöḿḿéñţš. Îţ ķééþš à ļîñé çöḿḿéñţ'š îñđéñţàţîöñ àñđ ļîñé éñđîñĝ, àñđ ŵŕîţéš éàçĥ ļîñé ŵîţĥ ţĥé ḿàŕķéŕ ĝöƒḿţ üšéš. Îţ ŕéƒļöŵš à þàŕàĝŕàþĥ öŕ ļîšţ îţéḿ öñļý ŵĥéñ öñé öƒ îţš ļîñéš îš ŵîđéŕ ţĥàñ ţĥé çöḿḿéñţ'š ŵîđéšţ ļîñé, öŕ 80 çöļüḿñš, ŵĥîçĥéṽéŕ îš ŵîđéŕ. À çöḿḿéñţ îñ ţĥé þöšîţîöñ ĝöƒḿţ ŕéƒöŕḿàţš àš à đöç çöḿḿéñţ ĝöéš ţĥŕöüĝĥ go/doc/comment'š þŕîñţéŕ, àš ĝöƒḿţ đöéš. Đîŕéçţîṽéš, ĝéñéŕàţéđ ƒîļéš, ţĥé çĝö þŕéàḿƃļé àñđ éẋàḿþļé öüţþüţ àŕé ñöţ àđđŕéššàƃļé, àñđ à ŕéƒüšàļ ñàḿéš ŵĥàţ ţĥé ƒîļé šéţš àšîđé.

À /* */ çöḿḿéñţ îš ŵŕîţţéñ îñ ţĥé ļàýöüţ îţ àļŕéàđý ĥàš, ŵĥîçĥ comment.ParseLayout ŕéàđš ƒŕöḿ îţš ƃýţéš: ţĥé đéļîḿîţéŕš àš ŵŕîţţéñ, šüçĥ àš /**, ţĥé šþàçé ƃéšîđé ţĥéḿ, ŵĥéţĥéŕ ţéẋţ šţàŕţš öñ ţĥé öþéñéŕ'š ļîñé öŕ éñđš öñ ţĥé çļöšéŕ'š, ţĥé þŕéƒîẋ éàçĥ ļîñé ƃéļöŵ ţĥé öþéñéŕ'š öþéñš ŵîţĥ, šüçĥ àš à ļîñé öƒ *, ĥöŵ àñ éḿþţý ļîñé ƃéţŵééñ þàŕàĝŕàþĥš îš ŵŕîţţéñ, ţĥé ƃļàñķ ļîñéš àƃöṽé àñđ ƃéļöŵ ţĥé ţéẋţ, àñđ ţĥé ļîñé éñđîñĝ. Ţĥé ţéẋţ öƒ ţĥé çöḿḿéñţ îš ŵĥàţ ŕéḿàîñš, àñđ ţĥé Ĝö þŕöṽîđéŕ ŕéàđš ţĥé çöḿḿéñţ'š þŕöšé ƒŕöḿ ţĥàţ šàḿé ţéẋţ, šö à çĥéçķ àñđ à ŕéŵŕîţé ŕéàđ öñé çöḿḿéñţ ţĥé šàḿé ŵàý. Ŕéñđéŕîñĝ à çöḿḿéñţ'š öŵñ ţéẋţ îñ îţš ļàýöüţ ŕéþŕöđüçéš îţš ƃýţéš. À đéļîḿîţéđ çöḿḿéñţ éñđš àţ ţĥé ƒîŕšţ */, šö ţéẋţ ĥöļđîñĝ */, öŕ ţéẋţ ŵĥöšé ƒîŕšţ çĥàŕàçţéŕ çöḿþļéţéš öñé ŵîţĥ ţĥé þŕéƒîẋ ƃéƒöŕé îţ, îš ŕéƒüšéđ àš terminator. Ñö éšçàþé ƒöŕ */ éẋîšţš îñšîđé à Ĝö çöḿḿéñţ, àñđ à ŕéŵŕîţé ţĥàţ çĥàñĝéđ ţĥé ţéẋţ ţö àṽöîđ îţ ŵöüļđ ŵŕîţé þŕöšé ñöƃöđý ŵŕöţé. À çöḿḿéñţ ḿàđé öƒ šéṽéŕàļ çöḿḿéñţš, šüçĥ àš à /* */ çöḿḿéñţ ƃéšîđé ļîñé çöḿḿéñţš îñ öñé ĝŕöüþ, ĥàš ñö öñé ļàýöüţ àñđ îš ŕéƒüšéđ àš layout. TestProseP3_go ŕéŵŕîţéš éṽéŕý Ĝö çöḿḿéñţ îñ ţĥé ŕéþöšîţöŕý ŵîţĥ îţš öŵñ þŕöšé, àñđ TestProseP4_go đöéš ţĥé šàḿé ƒöŕ éṽéŕý /* */ çöḿḿéñţ îñ ţĥé ŕéþöšîţöŕý àñđ îñ ţĥé Ĝö ţööļçĥàîñ'š šöüŕçé ţŕéé, àñđ ŕéǫüîŕéš éàçĥ ƒîļé ţö šţàý ƃýţé-îđéñţîçàļ.

À çöḿḿéñţ îñ à ļàñĝüàĝé ţĥé šöüŕçéçöđé þļüĝîñ ŕéàđš îš ŵŕîţţéñ ŵĥéñ ţĥé þļüĝîñ'š ḿàñîƒéšţ đéçļàŕéš ţĥàţ ļàñĝüàĝé ŵŕîţàƃļé (rewrite öñ à capabilities.comments éñţŕý). Ţĥé ĥöšţ ŵŕîţéš îţ, ñéṽéŕ ţĥé þļüĝîñ. Îţ ŕéàđš ţĥé çöḿḿéñţ'š ļàýöüţ ƒŕöḿ ţĥé ƒîļé'š ƃýţéš ţĥŕöüĝĥ ţĥé ḿàŕķéŕš ţĥé ḿàñîƒéšţ ñàḿéš, comment.ParseLayout ƒöŕ à đéļîḿîţéđ çöḿḿéñţ àñđ comment.ParseLineLayout ƒöŕ à ĝŕöüþ öƒ ļîñé çöḿḿéñţš, ŕéñđéŕš ţĥé ţéẋţ îñţö ţĥàţ ļàýöüţ àñđ šþļîçéš îţ îñ. Contain ţĥéñ ĥàš ţĥé þļüĝîñ ļöçàţé ţĥé ŕéŵŕîţţéñ ƒîļé ţĥŕöüĝĥ LocateComments, šö ţĥé çĥéçķ à ŕéŵŕîţé îš ĥéļđ ţö ŕüñš îñ ţĥé þļüĝîñ'š ĝŕàḿḿàŕ àñđ šĥàŕéš ñö çöđé ŵîţĥ ţĥé ŕéñđéŕéŕ. Ţĥé ţéẋţ îš ñöţ ŕéƒļöŵéđ, àñđ ţĥé éñţŕý'š width đöéš ñöţ àþþļý.

Šüçĥ à ŕéŵŕîţé îš ĥéļđ ţö ţĥé ƒöŕḿàţţéŕ ţĥé ƒîļé'š þŕöĵéçţ üšéš, ŵĥîçĥ ŕüñš îñ ţĥé ĥöšţ ƃéçàüšé îţš çöñƒîĝüŕàţîöñ àñđ îĝñöŕé ƒîļéš ƃéļöñĝ ţö ţĥé þŕöĵéçţ àñđ ţĥé þļüĝîñ šééš öñļý ƃýţéš. Ţĥé ĥöšţ ļööķš ƒöŕ ţĥé ḿàŕķéŕ ƒîļéš éàçĥ ƒöŕḿàţţéŕ ţĥé ḿàñîƒéšţ ļîšţš, šüçĥ àš .prettierrc öŕ à vite.config.ts ţĥàţ ļöàđš ṽîţé-þļüš, îñ ţĥé ƒîļé'š đîŕéçţöŕý àñđ ţĥé đîŕéçţöŕîéš àƃöṽé îţ, àñđ ŕüñš ţĥé ñéàŕéšţ öñé'š çöḿḿàñđ öñ ţĥé ƒîļé'š ƃýţéš, ƒŕöḿ node_modules/.bin öŕ PATH. Ţĥé þàţĥ îţ ĝîṽéš ţĥé ƒöŕḿàţţéŕ ĥàš îţš šýḿƃöļîç ļîñķš ŕéšöļṽéđ, šîñçé à ƒöŕḿàţţéŕ ḿàţçĥéš îţš îĝñöŕé ƒîļéš àĝàîñšţ ţĥàţ þàţĥ. Ƃéƒöŕé îţš öüţþüţ îš ţŕüšţéđ, ţĥé ƒöŕḿàţţéŕ ḿüšţ ŕéŵŕîţé ţĥé ḿàñîƒéšţ'š ƒöŕḿàţţéŕ çàñàŕý àţ ţĥé ƒîļé'š öŵñ þàţĥ. À ƒöŕḿàţţéŕ ţĥàţ îš ñöţ çöñƒîĝüŕéđ, ñöţ îñšţàļļéđ, öŕ ļéàṽéš ţĥé çàñàŕý àš îţ îš đîđ ñöţ ŕüñ: Contain ŕéţüŕñš comment.ErrFormatterNotRun, àñđ ţĥé éñţŕý ŕéþöŕţš đîđ-ñöţ-ŕüñ ŵîţĥ ţĥé ŕéàšöñ formatter àñđ ŵŕîţéš ñöţĥîñĝ. À çĥéçķ öƒ à ƒîļé îñ šüçĥ à ļàñĝüàĝé đöéš ñöţ ŕüñ ţĥé ƒöŕḿàţţéŕ, ŵĥîçĥ îţ ŕéþöŕţš àš üñšüþþöŕţéđ.

Ŕüññîñĝ ţĥàţ ƒöŕḿàţţéŕ ŕüñš çöđé ţĥé þŕöĵéçţ çöñţŕöļš. Ţĥé þŕöĵéçţ çàñ îñšţàļļ ţĥé éẋéçüţàƃļé îñ node_modules/.bin, àñđ à ƒöŕḿàţţéŕ îñšţàļļéđ àñýŵĥéŕé ļöàđš ţĥé þŕöĵéçţ'š çöñƒîĝüŕàţîöñ: þŕéţţîéŕ îḿþöŕţš à ĴàṽàŠçŕîþţ çöñƒîĝüŕàţîöñ ƒîļé àñđ ţĥé þļüĝîñš à .prettierrc ñàḿéš, àñđ ţĥé ṽîţé-þļüš oxfmt éṽàļüàţéš vite.config.ts. Šö ţĥé ƒöŕḿàţţéŕ îš àñ éẋéç šîţé üñđéŕ éẋéçüţîöñ ţŕüšţ (É-06), đéçîđéđ ŵĥéñ àñ éđîţ ŵöüļđ ŕüñ îţ. Îţš ŕéçöŕđ îš ķéýéđ ƃý ţĥé çöñƒîĝüŕàţîöñ ƒîļé ţĥàţ šéļéçţéđ îţ, àñđ îţš đîĝéšţ ĥöļđš ţĥé ƒöŕḿàţţéŕ'š ñàḿé àñđ çöḿḿàñđ, ţĥé ŕéšöļṽéđ éẋéçüţàƃļé'š ƃýţéš àñđ ţĥàţ ƒîļé'š ƃýţéš, šö à ñéŵ éẋéçüţàƃļé öŕ àñ éđîţéđ çöñƒîĝüŕàţîöñ àšķš àĝàîñ. Ţĥé đîĝéšţ àļšö ĥöļđš ţĥé îñţéŕþŕéţéŕ ţĥàţ ŕüñš ţĥé éẋéçüţàƃļé àñđ éṽéŕý çöñƒîĝüŕàţîöñ ƒîļé ţĥé ƒöŕḿàţţéŕ çàñ ļöàđ ƃéţŵééñ ţĥé éđîţéđ ƒîļé àñđ ţĥàţ ƒîļé; ŵĥàţ ţĥàţ çöđé îḿþöŕţš îš öüţšîđé îţ. kapi apply ŕüñš ţĥé ƒöŕḿàţţéŕ üñđéŕ KAPI_TRUST_EXEC, öñ à ŕéçöŕđéđ àļļöŵ, öŕ àƒţéŕ àšķîñĝ à þéŕšöñ àţ à ţéŕḿîñàļ, ŵĥöšé àñšŵéŕ îţ ŕéçöŕđš, àñđ à çĥàñĝé-šéţ ŕéàđ ƒŕöḿ šţàñđàŕđ îñþüţ ļéàṽéš ñö öñé ţö àšķ. Çöḿḿéñţ éđîţš ŕüñ ţĥŕöüĝĥ kapi apply àļöñé, šö ţĥé àĝéñţ šüŕƒàçé šţàŕţš ñö ƒöŕḿàţţéŕ: àñ àĝéñţ ţĥàţ ḿàý ŵŕîţé ƒîļéš çàñ ŵŕîţé ţĥé çöñƒîĝüŕàţîöñ à ƒöŕḿàţţéŕ ļöàđš. Ŵîţĥöüţ ţŕüšţ ţĥé éđîţ đîđ ñöţ ŕüñ, ŵîţĥ ţĥé ŕéàšöñ formatter, àñđ ñö ƒöŕḿàţţéŕ þŕöçéšš šţàŕţš. Ŵĥéñ ţĥé ĥöšţ ļööķš ƒöŕ ţĥé éẋéçüţàƃļé öñ PATH, îţ šķîþš àñ éñţŕý ţĥàţ îš ñöţ àñ àƃšöļüţé þàţĥ, šîñçé šüçĥ àñ éñţŕý ñàḿéš à đîŕéçţöŕý ŕéļàţîṽé ţö ţĥé ŵöŕķîñĝ đîŕéçţöŕý, àñđ à ñöţ-îñšţàļļéđ đéţàîļ ļîšţš ţĥé éñţŕîéš îţ šķîþþéđ. À Ĝö çöḿḿéñţ îš ĥéļđ ţö go/format, ţĥé ļîƃŕàŕý ĝöƒḿţ îš ƃüîļţ öñ, îñšîđé ţĥé ķàþî ƃîñàŕý, šö à Ĝö éđîţ ŕüñš ñö ƒöŕḿàţţéŕ éẋéçüţàƃļé.

ŢýþéŠçŕîþţ, ŢŠẊ àñđ ĴàṽàŠçŕîþţ àŕé đéçļàŕéđ ŵŕîţàƃļé. À ĴŠĐöç ƃļöçķ'š ţàĝš, ţĥéîŕ ţýþéš àñđ ñàḿéš, àñđ îţš {@link} ŕéƒéŕéñçéš àŕé þļàçéĥöļđéŕš, šö à ŕéŵŕîţé ţĥàţ đŕöþš öŕ àđđš öñé îš ŕéƒüšéđ àš structure. Àñ éñţŕý ñàḿîñĝ à ƒîļé ŵĥöšé çöḿḿéñţš öñļý à þļüĝîñ ŕéàđš, ŵĥéñ ñö šüçĥ þļüĝîñ îš îñšţàļļéđ, đîđ ñöţ ŕüñ, ŵîţĥ ţĥé ŕéàšöñ no-reader àñđ ţĥé çöḿḿàñđ ţĥàţ îñšţàļļš ţĥé þļüĝîñ. TestProseP3_typescript, TestProseP3_tsx àñđ TestProseP3_javascript ŕéŵŕîţé éṽéŕý çöḿḿéñţ öƒ ţĥéîŕ ļàñĝüàĝé îñ ţĥé ŕéþöšîţöŕý ŵîţĥ îţš öŵñ þŕöšé, ţĥŕöüĝĥ ţĥé þļüĝîñ, àñđ ŕéǫüîŕé éàçĥ ƒîļé ţö šţàý ƃýţé-îđéñţîçàļ.

Éàçĥ çöḿḿéñţ ƒöŕḿ ţĥéîŕ çöđé üšéš îš ŕéŵŕîţţéñ îñ ţĥé ļàýöüţ îţ îš ŵŕîţţéñ îñ: ĝŕöüþš öƒ ļîñé çöḿḿéñţš àñđ çöḿḿéñţš àƒţéŕ çöđé, /* */ çöḿḿéñţš öñ öñé ļîñé öŕ šéṽéŕàļ, ĴŠĐöç ƃļöçķš îñçļüđîñĝ ţĥöšé ŵĥöšé ţéẋţ šţàŕţš öñ ţĥé öþéñéŕ'š ļîñé, àñđ çöḿḿéñţš îñšîđé ĴŠẊ ({/* */}). Ţéẋţ ĥöļđîñĝ */ îš ŕéƒüšéđ îñ éàçĥ đéļîḿîţéđ ƒöŕḿ àñđ ŵŕîţţéñ îñ à ļîñé çöḿḿéñţ, ŵĥéŕé îţ çļöšéš ñöţĥîñĝ. À ļéĝàçý ĤŢḾĻ-ļîķé çöḿḿéñţ (<!--) îñ à šçŕîþţ öþéñš ŵîţĥ ñö đéļîḿîţéŕ ţĥé ḿàñîƒéšţ đéçļàŕéš, šö îţ ĥàš ñö ļàýöüţ ţö ķééþ àñđ îš ŕéƒüšéđ àš layout; ñö çöđé îñ ţĥîš ŕéþöšîţöŕý ŵŕîţéš öñé. TestProseP4_typescript, TestProseP4_tsx àñđ TestProseP4_javascript ŕéŵŕîţé éàçĥ ƒöŕḿ ŵîţĥ éẋàçţ ƃýţéš, ŵîţĥ ţĥé þļüĝîñ ŕéàđîñĝ ţĥé ŕéšüļţ àñđ öẋƒḿţ àĝŕééîñĝ ŵîţĥ ţĥé ƒîļé.

kapi apply ŕéàçĥéš ţĥé ŕéŵŕîţé ţĥŕöüĝĥ à set_content öþéŕàţîöñ öñ ţĥé çöḿḿéñţ'š ƃļöçķ, àđđŕéššéđ ƃý ƒîļé àñđ ţĥé îđ à çĥéçķ ŕéþöŕţš, îţš if_match ţĥé çöḿḿéñţ'š ŕéṽîšîöñ (r: àñđ ţĥé ƒîŕšţ šîẋţééñ ĥéẋ đîĝîţš öƒ ţĥé ƒîñĝéŕþŕîñţ); ḾÇÞ apply_edits ŕéƒüšéš à çöḿḿéñţ àš unsupported. À çĥéçķ ĝîṽéš éàçĥ ƒîñđîñĝ öñ à çöḿḿéñţ location.comment_sha256, ţĥé ŠĤÀ-256 öƒ ţĥé çöḿḿéñţ'š ƃýţéš (comment.Fingerprint), àñđ ţĥé éñţŕý çàŕŕîéš îţ ƃàçķ àš ţĥé ĝüàŕđ: à çöḿḿéñţ ŵĥöšé ƃýţéš đéŕ îš ŕéƒüšéđ àš çĥàñĝéđ, àñđ öñé ţĥàţ öñļý ḿöṽéđ ţö öţĥéŕ ļîñéš îš ŕéŵŕîţţéñ ŵĥéŕé îţ ñöŵ šîţš. Àñ éñţŕý ḿàý çàŕŕý ţĥé þŕöšé àš îţ ŵàš ŕéàđ, current_text, îñšţéàđ, àñđ àñ éñţŕý ŵîţĥ ñéîţĥéŕ ĝüàŕđ îš ŕéĵéçţéđ ƃéƒöŕé àñý éñţŕý îš àþþļîéđ. Ƃéƒöŕé ţĥé ƒîŕšţ çöḿḿéñţ öƒ à ļàñĝüàĝé îš ŵŕîţţéñ îñ à ŕüñ, comment.VerifyRewriter ŕüñš à ŵŕîţé çàñàŕý: à ķñöŵñ çöḿḿéñţ ŕéŵŕîţţéñ ŵîţĥ îţš öŵñ þŕöšé ḿüšţ šţàý ƃýţé-îđéñţîçàļ, àñđ à ķñöŵñ-ƃàđ ţéẋţ, à ŕéŵŕîţé ĝüàŕđéđ ƃý à ƒîñĝéŕþŕîñţ ţĥé çöḿḿéñţ đöéš ñöţ ĥàṽé, àñđ à šþļîçé öñé ƃýţé ƃéƒöŕé ţĥé çöḿḿéñţ ḿüšţ éàçĥ ƃé ŕéƒüšéđ. À ļàñĝüàĝé ŵîţĥ /* */ çöḿḿéñţš àđđš öñé ţö ţĥé çàñàŕý, ŵĥîçĥ ḿüšţ àļšö ŕéŵŕîţé ţö îţšéļƒ, àñđ ţéẋţ ĥöļđîñĝ îţš çļöšéŕ ḿüšţ ƃé ŕéƒüšéđ àš terminator. Ŵĥéñ ţĥé çàñàŕý ƒàîļš, ñö çöḿḿéñţ öƒ ţĥàţ ļàñĝüàĝé îš ŵŕîţţéñ. À ƒîļé'š éđîţš àþþļý ƒŕöḿ îţš ļàšţ çöḿḿéñţ ţö îţš ƒîŕšţ, ţĥé ƒîļé îš ŕéàđ àĝàîñ ƃéƒöŕé îţ îš ŵŕîţţéñ, àñđ à çĥéçķ šçöþéđ ţö ţĥé ŵŕîţţéñ çĥàñĝé çöḿéš ƃàçķ ŵîţĥ ţĥé ŕéšüļţ.

Đéƒàüļţ öñ, ṽîà àñ îñṽéŕţéđ öþţ-öüţ​

Šüŕƒàçîñĝ îš ţĥé đéƒàüļţ, çöñţŕöļļéđ þéŕ ƒöŕḿàţ ƃý à šîñĝļé ƃööļéàñ, extractNonTranslatableContent, éẋþöšéđ àš à šçĥéḿà þŕöþéŕţý îñ ţĥé ĝéñéŕàţéđ ƒöŕḿàţ ŕéƒéŕéñçé àñđ àççéþţéđ îñ ApplyMap üñđéŕ ţĥàţ ķéý. Ţĥé îḿþļéḿéñţàţîöñ îš àñ îñṽéŕţéđ þŕîṽàţé ƒîéļđ:

// zero value false ⇒ surfacing ON (the opt-out default)
disableNonTranslatableContent bool

func (c *Config) ExtractNonTranslatableContent() bool     { return !c.disableNonTranslatableContent }
func (c *Config) SetExtractNonTranslatableContent(v bool) { c.disableNonTranslatableContent = !v }

Ţĥé îñṽéŕšîöñ ḿéàñš à ƒŕéšĥļý žéŕö-ṽàļüéđ çöñƒîĝ (à ñéŵ ƒöŕḿàţ ţĥàţ ĥàš ñöţ ýéţ ļéàŕñéđ àƃöüţ ţĥé ƒļàĝ, à çàļļéŕ ţĥàţ çöñšţŕüçţš à çöñƒîĝ ŵîţĥöüţ çàļļîñĝ Reset) šüŕƒàçéš çöñţéñţ àüţöḿàţîçàļļý, ƃéçàüšé ţĥé đîšàƃļé ƃîţ ḿüšţ ƃé šéţ éẋþļîçîţļý ţö ţüŕñ îţ öƒƒ. Ţĥé šàƒé-ƒöŕ-îñĝéšţîöñ ƃéĥàṽîöüŕ ñééđš ñö çöñƒîĝüŕàţîöñ; öþţîñĝ öüţ îš éẋþļîçîţ. Ţĥé öƒƒ šŵîţçĥ éẋîšţš ƒöŕ ţŵö çàļļéŕš: ţĥé þàŕîţý ĥàŕñéšš, ŵĥîçĥ þîñš ţĥé ƃŕîđĝé-ḿàţçĥîñĝ çöñƒîĝüŕàţîöñ, àñđ ṽàļîđàţîöñ-öñļý öŕ þüŕé-þàššţĥŕöüĝĥ ƒļöŵš ţĥàţ ŵàñţ ñöţĥîñĝ ƃüţ šķéļéţöñ.

À ƒöŕḿàţ ḿàý àļšö šçöþé ŵĥàţ çöüñţš àš ḿéàñîñĝƒüļ çöñţéẋţ. Ţĥé đéšîĝñ-ţöķéñš ŕéàđéŕ çöḿþöšéš ţĥé ĝéñéŕîç ĴŠÖÑ ŕéàđéŕ ƃüţ çàļļš SetExtractNonTranslatableContent(false) öñ ţĥàţ îññéŕ çöñƒîĝ: à ţöķéñ'š $value, $type, àñđ $extensions àŕé šţŕüçţüŕéđ ḿàçĥîñé đàţà (çöļöüŕš, đîḿéñšîöñš, ƒöñţ ñàḿéš) ŕàţĥéŕ ţĥàñ çöñţéẋţüàļ þŕöšé, šö đéšîĝñ ţöķéñš šüŕƒàçé öñļý $description àš ţŕàñšļàţàƃļé þŕöšé àñđ ļéţ éṽéŕýţĥîñĝ éļšé þàšš ţĥŕöüĝĥ àš ñöñ-ţŕàñšļàţàƃļé šţŕüçţüŕé. Ţĥé çöñṽéñţîöñ îš üñîƒöŕḿ; éàçĥ ŕéàđéŕ đéçîđéš ŵĥîçĥ öƒ îţš ƒŕàĝḿéñţš àŕé ĝéñüîñéļý çöñţéẋţ ŕàţĥéŕ ţĥàñ îñéŕţ đàţà.

Ŵĥîçĥ ƒöŕḿàţš éẋþöšé ţĥé ƒļàĝ, àñđ éẋàçţļý ŵĥàţ éàçĥ šüŕƒàçéš, îš ĝéñéŕàţéđ îñţö ţĥé Ƒöŕḿàţ Ŕéƒéŕéñçé; çöñţéñţ-ƒîđéļîţý îš ţĥé ŕéçîþé ƒöŕ àđđîñĝ šüŕƒàçîñĝ ţö à ƒöŕḿàţ.

Ŕöüñđ-ţŕîþ, ţŕàñšļàţîöñ-šķîþ, àñđ þàŕîţý àļļ šţîļļ ĥöļđ​

Šüŕƒàçîñĝ îš àđđîţîṽé öṽéŕ ţĥé éẋîšţîñĝ ĝüàŕàñţééš.

  • Ƃýţé-éẋàçţ ŕöüñđ-ţŕîþ. Ţĥé ṽéŕƃàţîḿ šöüŕçé ƃýţéš ñéṽéŕ ļéàṽé ţĥé šķéļéţöñ. À šüŕƒàçéđ ŕéñđéŕàƃļé ƃļöçķ šţàñđš îñ ƒöŕ ţĥé ŕéñđéŕéđ ƃöđý ṽîà à šķéļéţöñ ŕéƒ, öŕ à šüƃ-šķéļéţöñ: ṽéŕƃàţîḿ šéĝḿéñţš îñţéŕļéàṽéđ ŵîţĥ ŕ郚 ţö ţŕàñšļàţàƃļé šþàñš îñšîđé àñ öţĥéŕŵîšé-öþàǫüé þàýļöàđ. À šüŕƒàçéđ çöḿḿéñţ'š ƃýţéš àŕé çöþîéđ ṽéŕƃàţîḿ. Àñ üñţŕàñšļàţéđ ŕöüñđ-ţŕîþ îš ƃýţé-îđéñţîçàļ ŵîţĥ ţĥé ƒļàĝ öñ àñđ ŵîţĥ îţ öƒƒ. Ţŕàñšļàţîöñ öƒ à šüŕƒàçéđ ţŕàñšļàţàƃļé šþàñ šþļîçéš îñ þļàçé; ţĥé šüŕŕöüñđîñĝ šţŕüçţüŕé îš üñţöüçĥéđ.
  • Ţŕàñšļàţîöñ-šķîþ. À šüŕƒàçéđ ƃļöçķ çàŕŕîéš Translatable: false, šö ţĥé ţŕàñšļàţîöñ ţööļš šķîþ îţ ƃý ţĥé šàḿé ŕüļé ţĥéý àļŵàýš ĥàṽé (É-07); ţĥé þàýļöàđ šéñţ ţö à ḿöđéļ îš üñçĥàñĝéđ.
  • Þàŕîţý. Ţĥé ƃŕîđĝé ĥàš ñö ñöţîöñ öƒ šüŕƒàçéđ çöñţéẋţ, šö à ĥéàđ-ţö-ĥéàđ ŵîţĥ šüŕƒàçîñĝ öñ ŵöüļđ đîṽéŕĝé ƃý çöñšţŕüçţîöñ: ţĥé ñàţîṽé šţŕéàḿ ŵöüļđ çàŕŕý éẋţŕà Block/Data þàŕţš ţĥé ƃŕîđĝé ñéṽéŕ éḿîţš, àñđ ţĥé çàñöñîçàļ þŕöĵéçţîöñ çöḿþàŕéš ţĥé PartType šéǫüéñçé àñđ þéŕ-ƃļöçķ Translatable ƒļàĝ. Ţĥé þàŕîţý çöñţŕàçţ îš "šàḿé šéḿàñţîç çöñƒîĝ → šàḿé ŕéšüļţš" ŕàţĥéŕ ţĥàñ "šàḿé đéƒàüļţš": ţĥé þàŕîţý ŕüññéŕ đüçķ-ţýþéš interface{ SetExtractNonTranslatableContent(bool) } öñ ţĥé ŕéàđéŕ'š çöñƒîĝ àñđ ƒöŕçéš îţ ƒàļšé ƃéƒöŕé ŕéàđîñĝ, šö ţĥé ñàţîṽé šţŕéàḿ ḿàţçĥéš ţĥé ƃŕîđĝé. Ţĥé ŕöļéš àñđ þŕöþéŕţîéš à šüŕƒàçéđ ƃļöçķ çàŕŕîéš àŕé àđđîţîöñàļļý þàŕîţý-šàƒé çàŕŕîéŕš (ţĥé çàñöñîçàļ þŕöĵéçţîöñ éẋçļüđéš SemanticRole, Properties, Annotations, àñđ ţĥé þļàçéĥöļđéŕ Equiv/Disp), ƃüţ ţĥé ƒļàĝ ŕàţĥéŕ ţĥàñ ţĥé þŕöĵéçţîöñ îš ŵĥàţ ķééþš ţĥé šüŕƒàçéđ þàŕţš ţĥéḿšéļṽéš öüţ öƒ ţĥé ĥéàđ-ţö-ĥéàđ (À-02).

Ţĥé SkeletonStore àļšö šüþþöŕţš ţĥé šüƃ-šķéļéţöñ îñ îţš öŵñ ŕîĝĥţ: ṽéŕƃàţîḿ šéĝḿéñţš öƒ àñ öţĥéŕŵîšé-öþàǫüé þàýļöàđ îñţéŕļéàṽéđ ŵîţĥ ŕ郚 ţö ţŕàñšļàţàƃļé šþàñš îñšîđé îţ. Ţĥîš îš ĥöŵ ţŕàñšļàţàƃļé þŕöšé éḿƃéđđéđ îñ àñ öþàǫüé šţŕüçţüŕé, ţĥé ñàţüŕàļ-ļàñĝüàĝé ţéẋţ îñšîđé à Ŵöŕđ éǫüàţîöñ, îš ţŕàñšļàţéđ ŵĥîļé ţĥé šüŕŕöüñđîñĝ ḿàţĥ îš ŕéþļàýéđ ƃýţé-ƒöŕ-ƃýţé (Ḿ-04; šéé Šķéļéţöñ Šţöŕé).

Ŕéàđéŕ-àššîĝñéđ îđéñţîţý​

À ŕéàđéŕ ḿîñţš éàçĥ ƃļöçķ'š ID ƒŕöḿ ŵĥàţ ţĥé ƒöŕḿàţ öƒƒéŕš (àñ ẊĻÎƑƑ üñîţ îđ, à ķéý þàţĥ, à þöšîţîöñàļ ñàḿé) àñđ ķééþš îţ üñîǫüé ŵîţĥîñ ţĥé đöçüḿéñţ ţĥŕöüĝĥ model.IDBuilder: ţĥé ƒîŕšţ ƃļöçķ ţö çļàîḿ àñ îđ ķééþš îţ, à ŕéþéàţ îš šéþàŕàţéđ ŵîţĥ àñ öŕđîñàļ (id#2), àñđ ţĥé đöçüḿéñţ'š öŵñ šþéļļîñĝ îš ŕéçöŕđéđ üñđéŕ PropDocumentID šö ţĥé ŵŕîţéŕ çàñ þüţ îţ ƃàçķ. À çöñţàîñéŕ ţĥàţ đéļéĝàţéš à ḿéḿƃéŕ ţö àñöţĥéŕ ŕéàđéŕ (àñ àŕçĥîṽé éñţŕý, àñ éḿƃéđđéđ ĤŢḾĻ šţŕîñĝ, àñ ÖĐƑ þàŕţ) ǫüàļîƒîéš ţĥé ḿéḿƃéŕ'š îđš ŵîţĥ ţĥé çĥîļđ ļàýéŕ'š îđ ţĥŕöüĝĥ model.QualifyMemberID, ĵöîñéđ ƃý MemberIDSeparator (_), šö ţŵö ḿéḿƃéŕš' tu1 àŕé ţŵö îđš àñđ ţĥé ǫüàļîƒîéđ îđ šţîļļ šàţîéš àñ ẊĻÎƑƑ xs:NMTOKEN. Ţĥéšé îđš àŕé ƒîļé-ļöçàļ; ĥöŵ ţĥéý ƃéçöḿé đüŕàƃļé îđéñţîţý àçŕöšš ŕéàđš îš Ƒ-03.

Éđîţîöñš à ŕéàđéŕ ŕéàđš àñđ à ŵŕîţéŕ ŵŕîţéš​

À ƃļöçķ ĥöļđš îţš çöñţéñţ àš þééŕ éđîţîöñš (Ƒ-02). À ŕéàđéŕ ƒîļéš ţĥé éđîţîöñ îţ ŕéàđ üñđéŕ ţĥé žéŕö éđîţîöñ ķéý, ţĥé đöçüḿéñţ'š öŵñ éđîţîöñ, ŵĥàţéṽéŕ ļàñĝüàĝé SourceLocale ñàḿéš. À ƃîļîñĝüàļ ŕéàđéŕ (ẊĻÎƑƑ 1.2 àñđ 2, ÞÖ, Ǫţ ŢŠ, ŢḾẊ, ẋçšţŕîñĝš, ÇŠṼ, ĶƂƑ) àļšö ƒîļéš éàçĥ ţŕàñšļàţîöñ îţ ŕéàđš üñđéŕ ţĥàţ ţŕàñšļàţîöñ'š ķéý àñđ ḿàŕķš îţ ŵîţĥ Block.MarkNative, šö NativeEditions() ļîšţš ţĥé éđîţîöñš ţĥé ƒîļé ĥöļđš, ţĥé đöçüḿéñţ'š öŵñ ƒîŕšţ.

À ŵŕîţéŕ ŵŕîţéš ţĥé đöçüḿéñţ'š öŵñ éđîţîöñ, àñđ ţĥé ţŕàñšļàţîöñ ƒîļéđ üñđéŕ ţĥé ļöçàļé îţš SetLocale ñàḿéš, ŵĥîçĥ îţ ŕéàđš ţĥŕöüĝĥ TargetRuns öŕ TargetEdition. Ŕéàđéŕš àñđ ŵŕîţéŕš ŕéàçĥ éđîţîöñš öñļý ţĥŕöüĝĥ ţĥé àççéššöŕš îñ core/model (SetSourceRuns, SetTargetRuns, SetTargetEdition, SourceRuns, TargetRuns), àñđ ñö ƒöŕḿàţ þàçķàĝé îñđéẋéš Block.Editions đîŕéçţļý. Ţĥé ƒîļé ĥöḿé (core/change/filehome, É-09) çĥööšéš ŵĥîçĥ éđîţîöñ à þàšš ŵŕîţéš ƃý šéţţîñĝ ţĥé ŵŕîţéŕ'š ļöçàļé: éḿþţý ƒöŕ ţĥé đöçüḿéñţ'š öŵñ éđîţîöñ, ţĥé éđîţîöñ'š ļàñĝüàĝé ƒöŕ à ţŕàñšļàţîöñ îñ à ƃîļîñĝüàļ ƒîļé.

ĶƂƑ, ţĥé çöñţéñţ ƃüñđļé, çàŕŕîéš ţĥé éđîţîöñš ţĥéḿšéļṽéš. Šçĥéḿà 2.0 (kbf.SchemaVersion) ĝîṽéš éàçĥ ƃļöçķ àñ editions ḿàþ ķéýéđ ƃý ţĥé éđîţîöñ ķéý'š ţéẋţ ƒöŕḿ (fr, fr;tone=formal, en;channel=short), ŵîţĥ ţĥé đöçüḿéñţ'š öŵñ éđîţîöñ üñđéŕ ţĥé éḿþţý ķéý, àñđ éàçĥ éđîţîöñ ĥöļđš îţš runs, status, origin, score àñđ derived (ţĥé éđîţîöñ îţ ŵàš ḿàđé ƒŕöḿ àñđ ţĥàţ éđîţîöñ'š ŕéṽîšîöñ). À ţŕàñšļàţîöñ à ŕéàđéŕ ƒîļéđ üñđéŕ ñö ļàñĝüàĝé ŕîđéš ƃéšîđé ţĥé ḿàþ àš unlabelled. Ţĥé Ĝö ŕéàđéŕ (core/kbf) àñđ ţĥé ŢýþéŠçŕîþţ ŕéàđéŕ (@neokapi/kapi-format) àļšö ŕéàđ šçĥéḿà 1.0, ŵĥöšé source ŕüñš àñđ targets ḿàþ đéçöđé îñţö ţĥé šàḿé éđîţîöñš, àñđ ƃöţĥ ŵŕîţéŕš ŵŕîţé 2.0. Ţĥé çöñţéñţ ƃüñđļé ŕéƒéŕéñçé îš ţĥé ñöŕḿàţîṽé šçĥéḿà.

Đéçîđîñĝ ţŕàñšļàţàƃîļîţý​

Ŵĥîçĥ ţéẋţ ƃéļöñĝš ţö ţĥé ţŕàñšļàţöŕ îš đéçîđéđ öñçé þéŕ ƒàḿîļý ŕàţĥéŕ ţĥàñ þéŕ ŕéàđéŕ. Ţĥé ḿàŕķüþ ŕéàđéŕš (markdown, mdx) çļàššîƒý éļéḿéñţš ŵîţĥ ţĥé Ŵ3Ç ĤŢḾĻ5 ţŕàñšļàţàƃîļîţý ţàƃļé îñ core/translatability, ĝéñéŕàţéđ ƒŕöḿ ţĥé šàḿé šöüŕçé ţĥé Ŕéàçţ î18ñ ţŕàñšƒöŕḿ üšéš, šö àñ éļéḿéñţ ñöƃöđý ĥàš çļàššîƒîéđ îš à çöñţàîñéŕ ŵĥöšé đîŕéçţ ţéẋţ îš þŕöḿöţéđ ŕàţĥéŕ ţĥàñ đŕöþþéđ: þŕöšé îñšîđé àñ üñƒàḿîļîàŕ çöḿþöñéñţ îš ţŕàñšļàţéđ àñđ ŕéþöŕţéđ, ñéṽéŕ ļöšţ îñ šîļéñçé. ẊḾĻ ŕéàđéŕš àþþļý ÎŢŠ 2.0 ŕüļéš àñđ ļöçàļ àţţŕîƃüţéš ţĥŕöüĝĥ core/its. Ţéẋţ à ŕéàđéŕ çļàššîƒîéš àš çöđé (à çöđé šþàñ, <kbd>, <samp>) šţàýš à ŕüñ ḿàŕķéđ NoTranslate (Ƒ-02), ŵĥîçĥ éṽéŕý ţŕàñšļàţîöñ þàţĥ ļéàṽéš üñţöüçĥéđ, àñđ à šþàñ ţĥé ḿöđéļ çàññöţ ţàķé îš šķîþþéđ àñđ ŕéþöŕţéđ ŕàţĥéŕ ţĥàñ çöšţîñĝ ţĥé þàĝé îţš ţŕàñšļàţîöñ.

Šüƃƒîļţéŕš àñđ ñéšţéđ ļàýéŕš​

Ƒöŕḿàţ ŕéàđéŕš çàñ éḿîţ çĥîļđ Ļàýéŕš ŵĥéñ ţĥéý éñçöüñţéŕ éḿƃéđđéđ çöñţéñţ îñ à đéŕéñţ ƒöŕḿàţ (ĤŢḾĻ îñšîđé ĴŠÖÑ, Ḿàŕķđöŵñ îñšîđé ÇŠṼ). Ţĥé çĥîļđ ŕéàđéŕ îš ŕéšöļṽéđ ṽîà à SubfilterResolver îñĵéçţéđ ƃý ţĥé FormatRegistry. Ţĥé ḿéçĥàñîšḿ îš đéƒîñéđ îñ Ƒ-02; ƒöŕḿàţ ŕéàđéŕš îḿþļéḿéñţ SubfilterAware àñđ đéçļàŕé þàţţéŕñš îñ ţĥéîŕ çöñƒîĝ.

Îḿþļéḿéñţîñĝ à ñéŵ ƒöŕḿàţ​

  1. Çŕéàţé core/formats/<name>/ ŵîţĥ reader.go, writer.go, àñđ config.go.
  2. Îḿþļéḿéñţ DataFormatReader ƃý éḿƃéđđîñĝ BaseFormatReader àñđ þŕöṽîđîñĝ ţĥé ƒöŕḿàţ-šþéçîƒîç þàŕšé ļöĝîç.
  3. Îḿþļéḿéñţ DataFormatWriter ƃý éḿƃéđđîñĝ BaseFormatWriter àñđ þŕöṽîđîñĝ ţĥé ƒöŕḿàţ-šþéçîƒîç šéŕîàļîžé ļöĝîç.
  4. Þöþüļàţé éṽéŕý ƒîéļđ öñ éàçĥ îñļîñé-çöđé ŕüñ ƒöŕ àñý îñļîñé ḿàŕķüþ: ID, Type/SubType, Data, Disp, Equiv, Constraints (Ƒ-02).
  5. Éḿîţ àñđ çöñšüḿé ţĥé šķéļéţöñ šţöŕé (SkeletonStoreEmitter / SkeletonStoreConsumer), àššîĝñ îđš ţĥŕöüĝĥ model.IDBuilder, àñđ đéçļàŕé ţĥé šţŕéàḿîñĝ ḿàŕķéŕš îƒ ţĥé ŕéàđéŕ àñđ ŵŕîţéŕ çàñ ƃöţĥ ĥöñöüŕ ţĥéḿ.
  6. Ŕéĝîšţéŕ ţĥé ŕéàđéŕ àñđ ŵŕîţéŕ ƒàçţöŕîéš îñ formats.RegisterAll (core/formats/register.go).
  7. ΃ ţĥé ƒöŕḿàţ çàñ ĥöšţ éḿƃéđđéđ çöñţéñţ, îḿþļéḿéñţ SubfilterAware àñđ àççéþţ Subfilters []SubfilterMapping îñ ţĥé çöñƒîĝ.
  8. ΃ ţĥé ŵŕîţéŕ çàñ ŵŕîţé à çĥàñĝéđ àţţŕîƃüţé öŕ à ñéŵ îñļîñé çöđé, îḿþļéḿéñţ AttrWriter öŕ CodeSynthesizer àñđ àđđ ţĥé çéļļš ţĥàţ þŕöṽé éàçĥ đéçļàŕàţîöñ ţö ţĥé öþéŕàţîöñš ḿàţŕîẋ.
  9. ΃ à ƃļöçķ'š šĥéļļ îš šḿàļļ éñöüĝĥ ţö ŵŕîţé öñ îţš öŵñ, àš à çàţàļöĝ'š ķéý àñđ ṽàļüé àŕé, îḿþļéḿéñţ StructureEditor àñđ àđđ ţĥé ƒöŕḿàţ'š çéļļš ţö ţĥé šţŕüçţüŕàļ öþéŕàţîöñš ḿàţŕîẋ (core/formats/opsmatrix_structural_test.go), ŵĥîçĥ ƒàîļš ŵĥîļé à đéçļàŕàţîöñ ĥàš ñö þàššîñĝ çéļļ.

Šéé Îḿþļéḿéñţîñĝ Ƒöŕḿàţš ƒöŕ à ŵàļķţĥŕöüĝĥ, àñđ Šķéļéţöñ šţöŕé àñđ šţŕéàḿîñĝ ƒöŕ ţĥé šţöŕé'š đéţàîļš.

Çöñšéǫüéñçéš​

  • Ƒöŕḿàţ ŕéàđéŕš éḿîţ ţĥé šàḿé šţŕéàḿîñĝ Þàŕţ þŕöţöçöļ ŕéĝàŕđļéšš öƒ šöüŕçé ƒöŕḿàţ, šö ţööļš ñéṽéŕ ñééđ ƒöŕḿàţ-šþéçîƒîç çöđé.
  • Ƒöŕḿàţ ŵŕîţéŕš ŕéþļàý Run.Data ṽéŕƃàţîḿ (Ƒ-02), šö ŵŕîţé-ƃàçķ ƒîđéļîţý îš îñĥéŕîţéđ ƒŕöḿ ţĥé çöñţéñţ ḿöđéļ.
  • Ƃüîļţ-îñ àñđ þļüĝîñ ƒöŕḿàţš çöéẋîšţ îñ öñé ŕéĝîšţŕý; ţĥé þîþéļîñé ţŕéàţš ţĥéḿ îđéñţîçàļļý.
  • Ţĥé éẋţéñšîöñ/þŕîöŕîţý/çöñţéñţ çàšçàđé ŕéšöļṽéš ḿöšţ ƒîļéš ŵîţĥöüţ üšéŕ çöñƒîĝüŕàţîöñ; àḿƃîĝüöüš çàšéš ƒàļļ ƃàçķ ţö àñ éẋþļîçîţ ƒöŕḿàţ ƒļàĝ.
  • Öñé šķéļéţöñ šţöŕé çöṽéŕš ţĥé ƒüļļ šþàñ öƒ ƒîļé ƒöŕḿàţš ƒŕöḿ šţŕéàḿîñĝ ţéẋţ ţö žîþ-þàçķàĝéđ ḿàŕķüþ, àñđ ţĥé šţŕéàḿîñĝ ḿàŕķéŕš ĝîṽé ŕéçöŕđ-öŕîéñţéđ ƒöŕḿàţš ƃöüñđéđ ḿéḿöŕý ŵîţĥöüţ çĥàñĝîñĝ àñýöñé'š öüţþüţ ƃýţéš.
  • Ñéŵ ƒöŕḿàţš þļüĝ îñ ƃý àđđîñĝ à đîŕéçţöŕý àñđ ŕéĝîšţéŕîñĝ îñ RegisterAll; ñö çĥàñĝéš ţö ţĥé éñĝîñé àŕé ñééđéđ.
  • Ţĥé ţĥŕéé-ŵàý ŕéàđéŕ öüţþüţ þöļîçý šéŕṽéš îñĝéšţîöñ àñđ ţŕàñšļàţîöñ ƒŕöḿ öñé þàŕšé, àñđ ţĥé îñṽéŕţéđ öþţ-öüţ ḿéàñš à ƒöŕḿàţ ţĥàţ ĥàš ñöţ ţĥöüĝĥţ àƃöüţ ţĥé ǫüéšţîöñ šţîļļ šüŕƒàçéš çöñţéẋţ.

Ŕéļàţéđ​