summaryrefslogtreecommitdiff
path: root/support/npp-for-context/README.md
blob: 46b678e7e8a89b7e4e9b03ba66dfbfb18b77f170 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
*Notepad++ for ConTeXt: Lexer and Macro Utilities for editing ConTeXt Documents 
Version 0.98*

This package includes 

I. A plugin for Notepad++ that implements, for the ConTeXt document 
processing system, 
i) a language lexer for semantic highlighting of TeX, LuaTeX, and ConTeXt commands; 
ii) autocompletion of commands with full support for calltips (set in columns); 
iii) tagging and insertion of markup and templates, with support for mnemonic keys. 

II. A color scheme and two complementary Notepad++ themes: Silver 
Twilight Hi and Silver Twilight Lo. 

Notepad++ for ConTeXt is available here: 

https://github.com/luigiScarso/context-npp 
https://github.com/luigiScarso/context-npp/blob/master/install/Npp-for-C 
onTeXt.zip 

The complete Notepad++ for ConTeXt manual and its TeX sources may be 
found in the following directory of Npp-for-ConTeXt.zip: 

/Npp-for-ConTeXt/doc/npp-context-manual.pdf 

It may also be downloaded here: 
https://github.com/luigiScarso/context-npp/tree/master/doc 

Completion of C++ plugin and lexer development was done by the current 
maintainer, Luigi Scarso (ConTeXt Development Team). Original C++ plugin 
and lexer development was done by Dr. Jason Wu (Colorado State 
University). Project vision and development planning (as well as the two 
themes and color scheme) are by Professor Idris Samawi Hamid (Colorado 
State University). 

The Notepad++ for ConTeXt lexer is strongly influence by the plugin 
WebEdit by Alexander Iljin: 
https://sourceforge.net/projects/npp-plugins/files/WebEdit/ 

This plugin aims to support the editing of ConTeXt documents in a number 
of ways. This includes some integration with the standalone distribution 
of ConTeXt. 

(For more information on ConTeXt see 

http://wiki.contextgarden.net/Main_Page 
http://www.pragma-ade.nl/index.htm .) 

This plugin includes a language lexer for semantic highlighting of 
ConTeXt commands; it also includes a system for tagging and inserting of 
markup and templates, with support for mnemonic keys. 

In its first phase of development, the plugin borrowed some ideas and 
implementations from other plugins (notably WebEdit); and, from the 
experience of Professor Hamid, several macros and customizations. In the 
second phase, a significant part of development was devoted to 
translating the xml documentation files of ConTeXt (= the English 
interface files that list and classify commands, see below) into the 
relevant xml configuration files of Notepad++, and to look for an 
efficient way to edit a document while minimizing the need to access the 
documentation. One outcome of this effort is the current autocompletion 
calltip mechanism, which provides columnar representation of the 
documentation for each autocompleted command, and equivalent to that 
provided by setup-en.pdf ("ConTeXt commands EN"). 

(In a ConTeXt distribution it lies at the end of this path: 
/tex/texmf-context/doc/context/documents/general/qrcs/setup-en.pdf) 

One of the fundamental differences between ConTeXt and traditional 
programming languages is the huge quantity of keywords (=commands, 
macros) and parameters (= command arguments) in ConTeXt. Fortunately, 
nearly all of them are described in the interface files of the 
standalone distribution, under 

tex/texmf-context/tex/context/interface/mkiv. 

Here one finds the file context-en.xml, which is constituted by the 
concatenation of all of the the other interface files. 

The build.cmd script, under the /scripts folder of Npp-for-ConTeXt.zip, 
reads context-en.xml and results in two files, i) /Program Files 
(x86)/Notepad++/plugins/Config/ConTeXt.xml, which is used by the ConTeXt 
lexer for Notepad++, and ii) /Program Files 
(x86)/Notepad++/plugins/APIs/context.xml, which is used by the 
autocompletion and calltips mechanism. The build.cmd script is a batch 
script that has to be executed outside Notepad++; under the hood it runs 
the Python2.7 script command_primitives_api.py with the correct command 
line options; if xmllint.exe is installed it checks to make sure that 
the files saved are well-formed. 

The Npp-for-ConTeXt.zip ships with versions of Config/ConTeXt.xml and 
APIs/context.xml that take as reference the official ConTeXt that is 
shipped with the TeXLive 2018 distribution (see 
https://www.tug.org/texlive/). So the build.cmd script is useful if the 
user has a different (possibly updated) standalone distribution. 

The switches at command line of command_primitives_api.py are 

usage: command_primitives_api_new.py [-h] [-m MTXCMD] [-i IFCFILE] [-u 
IFCUFILE] [-c CMDFILE] [-p PRIMFILE] [-d CHARDEF] [-r MACROCHARDEFFILE] 

optional arguments: -h, --help show this help message and exit -m 
MTXCMD, --mtxcmd MTXCMD ConTeXt mtxrun program -i IFCFILE, --ifcfile 
IFCFILE ConTeXt XML interface file -u IFCUFILE, --ifcufile IFCUFILE 
ConTeXt XML interface user file -c CMDFILE, --cmdfile CMDFILE ConTeXt 
XML command file -p PRIMFILE, --primfile PRIMFILE ConTeXt primitives.lua 
script -d CHARDEF, --chardef CHARDEF ConTeXt char-def.lua file -r 
MACROCHARDEFFILE, --macrochardeffile MACROCHARDEFFILE ConTeXt 
macro-chardef.lua script 

and the build.cmd sets the following 

-m mtxrun.exe ^ -c 
%CTXDIR%\tex\texmf-context\tex\context\base\mkiv\mult-prm.lua ^ -i 
%CTXDIR%\tex\texmf-context\tex\context\interface\mkiv\context-en.xml ^ 
-d %CTXDIR%\tex\texmf-context\tex\context\base\mkiv\char-def.lua 

The above assumes that the user sets the correct standalone in %CTXDIR%. 
It's important to note that this is the standalone also used by the 
ConTeXt plugin. Usually there is no need to pass --primfile PRIMFILE and 
--macrochardeffile MACROCHARDEFFILE, because they should be generated by 
the python script. The option --ifcufile IFCUFILE is useful if the user 
wants to add the documentation of a set of private macros: in this case 
it's necessary to know the syntax of that documentation, where the 
ConTeXt XML command files are taken as reference. 

Another component introduced in the plugin is the user's macro window, 
enabled with Ctrl+'-'. The idea is to offer to the user a way to quickly 
insert one's most used macros, set and saved under the section entitled 
[Markup] in 

/Roaming/Notepad++/plugins/config/ConTeXt.ini 

The body of the macro to insert must contain a single '|', which is a 
placeholder for the selected text; the macro can be selected with the 
mouse or by hitting the Return key. It may also be selected by typing a 
shortcut key. The Esc key closes the window. For example, if the user 
needs to insert a macro '\framed', as in 

\framed[frame=on]{...} 

(where '...' signifies some text to be operated upon by the command), 
and with a single key 'f' as shortcut, the text to set in ConTeXt.ini is 

(f)\framed[frame=on]{|} 

Note the full parenthesis that enclose the key shortcut - '(f)' in this 
case. The user's macros stored in ConTeXt.ini can be edited from 
Plugin->ConTeXt->Edit Config; once saved it has to be re-loaded with 
Plugin->ConTeXt->Load Config (no need to restart Notepad++). For the 
sake of readability, the string '%n' in the body of the text is 
translated into a newline. The shortcut can be a sequence of A-Za-z0-9 
characters, i.e. (d0) and (sst) are valid shortcuts. But for longer keys 
or keys which require pressing Shift for input, perhaps one will need to 
set a specific delay: This can be done under the [CommandsSetups] 
section of ConTeXt.ini via, e.g., 

usermacro:elapse=500 and or usermacro:elapse_shift=600 

The time is in milliseconds. 

A second mechanism (also adopted from the WebEdit plugin) are tempaltes. 
Under the section of ConTeXt.ini entitled [Templates], there is a list 
of text strings and their replacements: In the edit field of Notepad++ 
the user types <text> and Alt-'\'; <text> is replaced by <replacement>. 
The rules are the same as for those of the user's macros set under 
[Markup]. 

Finally, the standard Notepad++ right-click mechanism offers the usual 
insert text menu. Use 

Plugins - ConTeXt - Update Right-click menu 

to add one's markup macros. 

These ways of inserting markup tags are independent, so it's possible to 
have several ways to insert the same text. However, it's likely that in 
a future release this will be simplified or streamlined.