What is the meaning of main_syntax

Question

I'm writing a vim syntax file. And I found a variable called main_syntax is used in several existing syntax files. But I can't find any documentation explaining it.

This document only describes another variable, b:current_syntax, which is used to tell another script what the current syntax is.

Looks like main_syntax has the same meaning. Is it a legacy variable?

Answer 1

Some syntax scripts support being imported into another syntax via :syntax include, e.g. javascript inside html.

The main_syntax variable keeps track which syntax was actually set by the user / filetype; included syntax scripts then omit the clearing of existing syntax items when this variable is set. (Whereas syntax scripts are supposed to :finish without any actions if b:current_syntax is set.) Another difference to b:current_syntax is that main_syntax is only defined during the actual syntax loading process, whereas the other persists.

TL;DR: If you support including / include other syntaxes yourself, copy the conditional boilerplate from an existing syntax, e.g. $VIMRUNTIME/syntax/html.vim; if not, you can ignore this.