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

É-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 ƒöŕ ţĥé ŕööţ đöçüḿéñţ ļàýéŕ)
  • Ļöçàļé ḿéţàđàţà þŕöþàĝàţîöñ àñđ šöüŕçé/ţàŕĝéţ ļöçàļé àççéššöŕš
  • Çöñšîšţéñţ éŕŕöŕ ĥàñđļîñĝ àñđ çĥàññéļ ļîƒéçýçļé

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

BaseFormatWriter àļšö öŵñš ţĥé šĥàŕéđ ƃýţé-ļéṽéļ öüţþüţ öþţîöñš (format.OutputOptions): output.bom (add|remove|keep), output.newline (lf|crlf|keep), àñđ output.encoding (àñý çĥàŕšéţ îñ core/encoding; đéƒàüļţ ÜŢƑ-8 þàššţĥŕöüĝĥ). Ŕéàđéŕš àļŕéàđý ñöŕḿàļîžé ƂÖḾ, çĥàŕšéţ, àñđ ñéŵļîñéš àţ þàŕšé ţîḿé, šö ţĥéšé éẋîšţ öñļý ţö çöñţŕöļ öüţþüţ šţýļé; ţĥéý àŕé ŵŕîţéŕ çöñƒîĝüŕàţîöñ ŕàţĥéŕ ţĥàñ à þîþéļîñé šţàĝé. Ţĥéý àŕé šéţ üñđéŕ ţĥé ŕéšéŕṽéđ 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[@version][:preset], é.ĝ. okf_html@1.46.0:wellFormed. Ţĥé ŕéĝîšţŕý ŕéšöļṽéš ţĥé ŕéƒéŕéñçé ţö ţĥé àþþŕöþŕîàţé ƒàçţöŕý.

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

Detect(path, DetectOptions) ŕéšöļṽéš ţĥé ƒöŕḿàţ ƒöŕ à þàţĥ. Ƃý đéƒàüļţ îţ đéţéçţš ƃý éẋţéñšîöñ àñđ, ŵĥéñ ţĥàţ éẋţéñšîöñ îš çļàîḿéđ ƃý ḿöŕé ţĥàñ öñé ƒöŕḿàţ, ƃý ŕéàđîñĝ ţĥé ƒîļé ĥéàđ ţö đéçîđé ƃéţŵééñ ţĥéḿ (.xliff çàñ ƃé ẊĻÎƑƑ 1.ẋ öŕ 2.ẋ; .xml îš çļàîḿéđ ƃý šéṽéŕàļ ƒöŕḿàţš). DetectOptions çàŕŕîéš ExtensionOnly ƒöŕ ţĥé đéţéŕḿîñîšţîç éẋţéñšîöñ/þŕîöŕîţý þîçķ, þļüš šöüŕçé ŕéšţŕîçţîöñ àñđ þéŕ-çàļļ þŕîöŕîţý öṽéŕŕîđéš. Öñļý ţĥé ĥéàđ öƒ ţĥé ƒîļé îš ŕéàđ; àñý ŕéàđ éŕŕöŕ ƒàļļš ƃàçķ ţö ţĥé éẋţéñšîöñ þîçķ.

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

kapi'š öŵñ öñ-đîšķ çöñṽéñţîöñš üšé çöḿþöüñđ šüƒƒîẋéš (.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), à çöñçüŕŕéñţ çĥàññéļ ƒöŕ šţŕéàḿîñĝ þàîŕš (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). ẊĻÎƑƑ, ÞÖ, ŢḾẊ, ḾÖ, àñđ KBF àŕé ĝéñéŕàţîṽé ƒîļéš, ƃüţ ţĥéý ƃéļöñĝ ţö ţĥé éẋţŕàçţ → ţŕàñšļàţé → ḿéŕĝé ļööþ, ñöţ ţö đöçüḿéñţ çöñṽéŕšîöñ: 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) ŕàţĥéŕ ţĥàñ ĥàļƒ-đŕàŵñ.

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

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

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

ƑŕàĝḿéñţĐéšţîñàţîöñ
Ţŕàñšļàţàƃļé þŕöšé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 ŵŕîţéš ƒöŕ à ṽöîçé þöîñţéŕ, ţĥé ḿàŕķéŕš öƒ à ĝéñéŕàţéđ ŕéĝîöñ àñđ ḿàŕķđöŵñļîñţ àñđ Þŕéţţîéŕ îñšţŕüçţîöñš àŕé đîŕéçţîṽéš.

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

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

Ţĥé þŕöþéŕţîéš ƒöŕḿàţ ŕéàđš à çöḿḿéñţ àš à ļîñé ţĥàţ öþéñš ŵîţĥ # öŕ ! öüţšîđé à ṽàļüé'š çöñţîñüàţîöñ, ĥöļđš îţš šçàñ ţö ţĥé ļîñéš ţĥé þŕöþéŕţîéš ŕéàđéŕ ŕéàđš àš çöḿḿéñţš, àñđ ñàḿéš éàçĥ çöḿḿéñţ ƒöŕ ţĥé ķéý ţĥàţ ƒöļļöŵš îţ. Okapi'š éẋţŕàçţîöñ đîŕéçţîṽéš, šüçĥ àš #_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, öñ à ŕéçöŕđéđ àļļöŵ, öŕ àƒţéŕ àšķîñĝ à þéŕšöñ àţ à ţéŕḿîñàļ, ŵĥöšé àñšŵéŕ îţ ŕéçöŕđš, àñđ à çĥàñĝé-šéţ ŕéàđ ƒŕöḿ šţàñđàŕđ îñþüţ ļéàṽéš ñö öñé ţö àšķ. ḾÇÞ apply_edits ñéṽéŕ ŕüñš à þŕöĵéçţ'š ƒöŕḿàţţéŕ, šîñçé àñ àĝéñţ ţĥàţ ḿàý ŵŕîţé ƒîļéš çàñ ŵŕîţé ţĥé çöñƒîĝüŕàţîöñ îţ ļöàđš. Ŵîţĥöüţ ţŕüšţ ţĥé éđîţ đîđ ñöţ ŕüñ, ŵîţĥ ţĥé ŕéàšöñ formatter, àñđ ñö ƒöŕḿàţţéŕ þŕöçéšš šţàŕţš. Ŵĥéñ ţĥé ĥöšţ ļööķš ƒöŕ ţĥé éẋéçüţàƃļé öñ PATH, îţ šķîþš àñ éñţŕý ţĥàţ îš ñöţ àñ àƃšöļüţé þàţĥ, šîñçé šüçĥ àñ éñţŕý ñàḿéš à đîŕéçţöŕý ŕéļàţîṽé ţö ţĥé ŵöŕķîñĝ đîŕéçţöŕý, àñđ à ñöţ-îñšţàļļéđ đéţàîļ ļîšţš ţĥé éñţŕîéš îţ šķîþþéđ. À Ĝö çöḿḿéñţ îš ĥéļđ ţö go/format, ţĥé ļîƃŕàŕý ĝöƒḿţ îš ƃüîļţ öñ, îñšîđé ţĥé kapi ƃîñàŕý, šö à Ĝö éđîţ ŕüñš ñö ƒöŕḿàţţéŕ éẋéçüţàƃļé.

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

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

kapi apply àñđ ḾÇÞ apply_edits ŕéàçĥ ţĥé ŕéŵŕîţé ţĥŕöüĝĥ à comment éñţŕý, àđđŕéššéđ ƃý ƒîļé àñđ ţĥé îđ à çĥéçķ ŕéþöŕţš. À çĥéçķ ĝîṽéš éàçĥ ƒîñđîñĝ öñ à çöḿḿéñţ 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.

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

Ŵĥîçĥ ţéẋţ ƃéļöñĝš ţö ţĥé ţŕàñšļàţöŕ îš đéçîđéđ öñçé þéŕ ƒàḿîļý ŕàţĥéŕ ţĥàñ þéŕ ŕéàđéŕ. Ţĥé ḿàŕķüþ ŕéàđéŕš (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 îñ ţĥé çöñƒîĝ.

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

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

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

Ŕéļàţéđ​