From a9932f8d46e6106fa60ab7591e310827cb9ffcb5 Mon Sep 17 00:00:00 2001
From: ngc92 <7938269+ngc92@users.noreply.github.com>
Date: Sat, 13 May 2023 12:16:22 +0300
Subject: [PATCH] [TeX.DocStrip] Basic DocStrip support (#3555)

This PR adds support for the `DocStrip` format of TeX, used by many LaTeX packages to specify their installation.
https://www.texlive.info/CTAN/macros/latex/base/docstrip.pdf

I've inherited from the base `TeX` syntax, and just prepended the new commands to the `main` context. This is not quite accurate, in the sense that many `plainTeX` constructs would simply be invalid in a docstrip file -- as there is no typesetting to be done, typesetting and math commands don't really make sense. But I think it is OK to highlight these commands, and probably better to handle things like this, because if we manually select the subset that is supported, and later on add something new in `TeX` that also works in `DocStrip`, we might forget to change `DocStrips` `main` context.

In general, `DocStrip` files are usually rather short and simple, and typically look like the examples given in https://texdoc.org/serve/dtxtut.pdf/0 (appendix A).

Finally, since the goal is not to produce typeset output, but instead to describe how files are generated, I've used a `source` main scope.
---
 LaTeX/DocStrip.sublime-syntax  | 96 ++++++++++++++++++++++++++++++++++
 LaTeX/syntax_test_docstrip.ins | 89 +++++++++++++++++++++++++++++++
 2 files changed, 185 insertions(+)
 create mode 100644 LaTeX/DocStrip.sublime-syntax
 create mode 100644 LaTeX/syntax_test_docstrip.ins

diff --git a/LaTeX/DocStrip.sublime-syntax b/LaTeX/DocStrip.sublime-syntax
new file mode 100644
index 0000000000..f4777a8eb4
--- /dev/null
+++ b/LaTeX/DocStrip.sublime-syntax
@@ -0,0 +1,96 @@
+%YAML 1.2
+---
+# https://www.sublimetext.com/docs/syntax.html
+# https://www.texlive.info/CTAN/macros/latex/base/docstrip.pdf
+name: TeX (DocStrip)
+scope: source.tex.docstrip
+version: 1
+extends: Packages/LaTeX/TeX.sublime-syntax
+
+file_extensions:
+  - ins
+
+contexts:
+  main:
+    - meta_prepend: true
+    - include: docstrip-preamble
+    - include: docstrip-config
+    - include: docstrip-user-io
+    - include: docstrip-keywords
+    - include: docstrip-constants
+
+  controls:
+    - meta_append: true
+    - match: (\\)endbatchfile{{endcs}}
+      scope: keyword.control.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+    - match: (\\)(?:batch)?input{{endcs}}
+      scope: meta.function.input.tex keyword.control.input.tex
+      captures:
+        1: punctuation.definition.backslash.tex
+    - match: (\\)ifToplevel{{endcs}}
+      scope: keyword.control.conditional.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+
+  docstrip-preamble:
+    - match: (\\)(?:declare)?(?:pre|post)amble{{endcs}}
+      scope: keyword.context.block.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+      push: docstrip-preamble-content
+
+  docstrip-preamble-content:
+    - meta_include_prototype: false
+    - meta_content_scope: markup.raw.verbatim.tex
+    - match: (\\)end(?:pre|post)amble{{endcs}}
+      scope: keyword.context.block.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+      pop: 1
+
+  docstrip-keywords:
+    - match: (\\)(?:file|from|generateFile){{endcs}}
+      scope: keyword.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+      push: docstrip-file-argument
+    - match: (\\)(?:generate|needed){{endcs}}
+      scope: keyword.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+
+  docstrip-file-argument:
+    - match: \{
+      scope: punctuation.definition.group.brace.begin.tex
+      set: docstrip-file-argument-path
+    - include: else-pop
+    - include: paragraph-pop
+
+  docstrip-file-argument-path:
+    - meta_content_scope: meta.path.tex.docstrip
+    - include: macro-braces-body
+
+  docstrip-config:
+    - match: (\\)(?:usedir|showdirectory|BaseDirectory|DeclareDir|UseTDS|maxfiles|maxoutfiles){{endcs}}
+      scope: support.function.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+
+  docstrip-user-io:
+     - match: (\\)(?:Msg|Ask){{endcs}}
+       scope: support.function.tex.docstrip
+       captures:
+         1: punctuation.definition.backslash.tex
+
+  docstrip-constants:
+    - match: (\\)(?:askforoverwrite(?:true|false)|askonceonly|(?:use|no)(?:pre|post)amble|showprogress|keepsilent){{endcs}}
+      scope: constant.language.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
+
+    - match: (\\)(?:(?:Double)?perCent|MetaPrefix|empty){{endcs}}
+      scope: constant.language.tex.docstrip
+      captures:
+        1: punctuation.definition.backslash.tex
diff --git a/LaTeX/syntax_test_docstrip.ins b/LaTeX/syntax_test_docstrip.ins
new file mode 100644
index 0000000000..dd2d9bccd0
--- /dev/null
+++ b/LaTeX/syntax_test_docstrip.ins
@@ -0,0 +1,89 @@
+% SYNTAX TEST "Packages/LaTeX/DocStrip.sublime-syntax"
+
+\input docstrip.tex
+%^^^^^ meta.function.input.tex keyword.control.input.tex
+
+
+\keepsilent
+%^^^^^^^^^^ constant.language.tex.docstrip
+
+
+\usedir{tex/latex/somewhere}
+%^^^^^^ support.function.tex.docstrip
+
+
+
+\preamble
+%^^^^^^^^ keyword.context.block.tex.docstrip
+This is a generated file.
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.3 of this license or (at your option) any later
+version. The latest version of this license is in:
+http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+% ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ markup.raw.verbatim.tex
+\endpreamble
+%^^^^^^^^^^^ keyword.context.block.tex.docstrip
+
+\declarepostamble
+%^^^^^^^^^^^^^^^^ keyword.context.block.tex.docstrip
+some text to copy
+%^^^^^^^^^^^^^^^^^ markup.raw.verbatim.tex
+\endpostamble
+%^^^^^^^^^^^^ keyword.context.block.tex.docstrip
+
+\askforoverwritefalse
+%^^^^^^^^^^^^^^^^^^^^ constant.language.tex.docstrip
+
+\askforoverwritetrue
+%^^^^^^^^^^^^^^^^^^^ constant.language.tex.docstrip
+
+\nopreamble
+%^^^^^^^^^^ constant.language.tex.docstrip
+
+\usepostamble
+%^^^^^^^^^^^^ constant.language.tex.docstrip
+
+\askonceonly
+%^^^^^^^^^^^ constant.language.tex.docstrip
+
+\showprogress
+%^^^^^^^^^^^^ constant.language.tex.docstrip
+
+
+\batchinput{other.docstrip}
+%^^^^^^^^^^ meta.function.input.tex keyword.control.input.tex
+
+\let\MetaPrefix \DoubleperCent \perCent
+%   ^^^^^^^^^^^ constant.language.tex.docstrip
+%               ^^^^^^^^^^^^^^ constant.language.tex.docstrip
+%                              ^^^^^^^^ constant.language.tex.docstrip
+%   ^ punctuation.definition.backslash.tex
+%               ^ punctuation.definition.backslash.tex
+
+
+\ifToplevel{Conditional code executed}
+%^^^^^^^^^^ keyword.control.conditional.tex.docstrip
+
+\generate{\file{target.sty}{\from{source.dtx}{pattern}}}
+%^^^^^^^^ keyword.tex.docstrip
+%         ^^^^^ keyword.tex.docstrip
+%               ^^^^^^^^^^ meta.path.tex.docstrip
+%                           ^^^^^ keyword.tex.docstrip
+%                                 ^^^^^^^^^^ meta.path.tex.docstrip
+
+
+% Old but still supported syntax:
+\generateFile{README.txt}{t}{\from{test.dtx}{README}}
+%^^^^^^^^^^^^ keyword.tex.docstrip
+%             ^^^^^^^^^^ meta.path.tex.docstrip
+%                            ^^^^^ keyword.tex.docstrip
+%                                  ^^^^^^^^ meta.path.tex.docstrip
+
+\Msg{* "example" package is now generated}
+%^^^ support.function.tex.docstrip
+\endbatchfile
+%^^^^^^^^^^^^ keyword.control.tex