diff options
Diffstat (limited to 'Master/texmf-dist/context/data')
| -rw-r--r-- | Master/texmf-dist/context/data/scite/scite-context-readme.pdf | bin | 212111 -> 212029 bytes | |||
| -rw-r--r-- | Master/texmf-dist/context/data/scite/scite-context-readme.tex | 391 |
2 files changed, 183 insertions, 208 deletions
diff --git a/Master/texmf-dist/context/data/scite/scite-context-readme.pdf b/Master/texmf-dist/context/data/scite/scite-context-readme.pdf Binary files differindex 5e68aecc783..05473e597a0 100644 --- a/Master/texmf-dist/context/data/scite/scite-context-readme.pdf +++ b/Master/texmf-dist/context/data/scite/scite-context-readme.pdf diff --git a/Master/texmf-dist/context/data/scite/scite-context-readme.tex b/Master/texmf-dist/context/data/scite/scite-context-readme.tex index 0789401b83c..3eb7d422ab2 100644 --- a/Master/texmf-dist/context/data/scite/scite-context-readme.tex +++ b/Master/texmf-dist/context/data/scite/scite-context-readme.tex @@ -113,56 +113,50 @@ {\em This manual is under (re)construction.} -For a long time at \PRAGMA\ we used \TEXEDIT, an editor we'd -written in \MODULA. It had some project management features and -recognized the project structure in \CONTEXT\ documents. Later we -rewrote this to a platform independent reimplementation called -\TEXWORK\ written in \PERLTK\ (not to be confused with the editor -with the plural name). - -In the beginning of the century I can into \SCITE, written by Neil -Hodgson. Although the mentioned editors provide some functionality -not present in \SCITE\ we decided to use that editor because it -frees us from maintaining our own. I ported our \TEX\ and -\METAPOST\ (line based) syntax highlighting to \SCITE\ and got a -lot of others for free. - -After a while I found out that there was an extension interface -written in \LUA. I played with it and wrote a few extensions too. -This pleasant experience later triggered the \LUATEX\ project. - -A decade into the century \SCITE\ got another new feature: you can -write dynamic external lexers in \LUA\ using \LPEG. As in the -meantime \CONTEXT\ has evolved in a \TEX/\LUA\ hybrid, it made -sense to look into this. The result is a couple of lexers that -suit \TEX, \METAPOST\ and \LUA\ usage in \CONTEXT\ \MKIV. As we -also use \XML\ as input and output format a lexer for \XML\ is also -provided. And because \PDF\ is one of the backend formats lexing of -\PDF\ is also implemented. \footnote {In the process some of the -general lexing framework was adapted to suit our demands for speed. -We ship these files as well.} - -In the \CONTEXT\ (standalone) distribution you will find the -relevant files under: +For a long time at \PRAGMA\ we used \TEXEDIT, an editor we'd written in \MODULA. +It had some project management features and recognized the project structure in +\CONTEXT\ documents. Later we rewrote this to a platform independent +reimplementation called \TEXWORK\ written in \PERLTK\ (not to be confused with +the editor with the plural name). + +In the beginning of the century I can into \SCITE, written by Neil Hodgson. +Although the mentioned editors provide some functionality not present in \SCITE\ +we decided to use that editor because it frees us from maintaining our own. I +ported our \TEX\ and \METAPOST\ (line based) syntax highlighting to \SCITE\ and +got a lot of others for free. + +After a while I found out that there was an extension interface written in \LUA. +I played with it and wrote a few extensions too. This pleasant experience later +triggered the \LUATEX\ project. + +A decade into the century \SCITE\ got another new feature: you can write dynamic +external lexers in \LUA\ using \LPEG. As in the meantime \CONTEXT\ has evolved in +a \TEX/\LUA\ hybrid, it made sense to look into this. The result is a couple of +lexers that suit \TEX, \METAPOST\ and \LUA\ usage in \CONTEXT\ \MKIV. As we also +use \XML\ as input and output format a lexer for \XML\ is also provided. And +because \PDF\ is one of the backend formats lexing of \PDF\ is also implemented. +\footnote {In the process some of the general lexing framework was adapted to +suit our demands for speed. We ship these files as well.} + +In the \CONTEXT\ (standalone) distribution you will find the relevant files +under: \starttyping <texroot>/tex/texmf-context/context/data/scite \stoptyping -Normally a user will not have to dive into the implementation -details but in principle you can tweak the properties files to -suit your purpose. +Normally a user will not have to dive into the implementation details but in +principle you can tweak the properties files to suit your purpose. \subject{The look and feel} -The color scheme that we use is consistent over the lexers but we -use more colors that in the traditional lexing. For instance, -\TEX\ primitives, low level \TEX\ commands, \TEX\ constants, basic -file structure related commands, and user commands all get a -different treatment. When spell checking is turned on, we indicate -unknown words, but also words that are known but might need -checking, for instance because they have an uppercase character. -In \in {figure} [fig:colors] we some of that in practice. +The color scheme that we use is consistent over the lexers but we use more colors +that in the traditional lexing. For instance, \TEX\ primitives, low level \TEX\ +commands, \TEX\ constants, basic file structure related commands, and user +commands all get a different treatment. When spell checking is turned on, we +indicate unknown words, but also words that are known but might need checking, +for instance because they have an uppercase character. In \in {figure} +[fig:colors] we some of that in practice. \placefigure [page] @@ -177,31 +171,29 @@ In \in {figure} [fig:colors] we some of that in practice. \subject{Installing \SCITE} -Installing \SCITE\ is straightforward. We are most familiar with -\MSWINDOWS\ but for other operating systems installation is not -much different. First you need to fetch the archive from: +Installing \SCITE\ is straightforward. We are most familiar with \MSWINDOWS\ but +for other operating systems installation is not much different. First you need to +fetch the archive from: \starttyping www.scintilla.org \stoptyping -The \MSWINDOWS\ binaries are zipped in \type {wscite.zip}, and you -can unzip this in any directory you want as long as you make sure -that the binary ends up in your path or as shortcut on your -desktop. So, say that you install \SCITE\ in: +The \MSWINDOWS\ binaries are zipped in \type {wscite.zip}, and you can unzip this +in any directory you want as long as you make sure that the binary ends up in +your path or as shortcut on your desktop. So, say that you install \SCITE\ in: \starttyping c:\data\system\scite\wscite \stoptyping -You need to add this path to your local path definition. -Installing \SCITE\ to some known place has the advantage that you -can move it around. There are no special dependencies on the -operating system. +You need to add this path to your local path definition. Installing \SCITE\ to +some known place has the advantage that you can move it around. There are no +special dependencies on the operating system. -Next you need to install the lpeg lexers. \footnote {Versions -later than 2.11 will not run on \MSWINDOWS\ 2K. In that case you need -to comment the external lexer import.} These can be fetched from: +Next you need to install the lpeg lexers. \footnote {Versions later than 2.11 +will not run on \MSWINDOWS\ 2K. In that case you need to comment the external +lexer import.} These can be fetched from: \starttyping http://foicica.com/scintillua/ @@ -214,15 +206,17 @@ copy them in the same path as where the regular properties files live. \footnote \SCITE\ that influence the lexers in which case you have to wait till we have update them to suit those changes.} -For \UNIX, one can take a precompiled version as well. Here we -need to split the set of files into: +For \UNIX, one can take a precompiled version as well. Here we might need to split +the set of files into: \starttyping /usr/bin /usr/share/scite \stoptyping -The second path is hard coded in the binary. +The second path is hard coded in the binary and moving all files there probably works +okay. Beware: if you're on a 64 bit system, you need to rename the 64 bit \type {so} +library. If you want to use \CONTEXT, you need to copy the relevant files from @@ -230,21 +224,19 @@ If you want to use \CONTEXT, you need to copy the relevant files from <texroot>/tex/texmf-context/context/data/scite \stoptyping -to the path were \SCITE\ keeps its property files (\type (*.properties). - -There is a file called \type {SciteGlobal.properties}. At the end -of that file (on \MSWINDOWS\ it is in the path where the Scite binary) -you then add a line to the end: +to the path were \SCITE\ keeps its property files (\type {*.properties}). There +is a file called \type {SciteGlobal.properties}. At the end of that file (on +\MSWINDOWS\ it is in the path where the Scite binary) you then add a line to the +end: \starttyping import scite-context-user \stoptyping -You need to restart \SCITE\ in order to see if things work out as -expected. +You need to restart \SCITE\ in order to see if things work out as expected. -Disabling the external lexer in a recent \SCITE\ is somewhat -tricky. In that case the end of that file looks like: +Disabling the external lexer in a recent \SCITE\ is somewhat tricky. In that case +the end of that file looks like: \starttyping imports.exclude=scite-context-external @@ -254,8 +246,8 @@ import scite-context-user In any case you need to make sure that the user file is loaded last. -After this, things should run as expected (given that \TEX\ runs -at the console as well). +After this, things should run as expected (given that \TEX\ runs at the console +as well). % In order to run the commands needed, we assume that the following programs % are installed: @@ -270,12 +262,11 @@ at the console as well). \subject{Fonts} -The configuration file defaults to the Dejavu fonts. These free -fonts are part of the \CONTEXT\ suite (also known as the -standalone distribution). Of course you can fetch them from \type -{http://dejavu-fonts.org} as well. You have to copy them to where -your operating system expects them. In the suite they are -available in +The configuration file defaults to the Dejavu fonts. These free fonts are part of +the \CONTEXT\ suite (also known as the standalone distribution). Of course you +can fetch them from \type {http://dejavu-fonts.org} as well. You have to copy +them to where your operating system expects them. In the suite they are available +in \starttyping <contextroot>/tex/texmf/fonts/truetype/public/dejavu @@ -283,9 +274,8 @@ available in \subject{An alternative approach} -If for some reason you prefer not to mess with property files in -the main \SCITE\ path, you can follow a different route and -selectively copy files to places. +If for some reason you prefer not to mess with property files in the main \SCITE\ +path, you can follow a different route and selectively copy files to places. The following files are needed for the lpeg based lexer: @@ -308,22 +298,21 @@ lexers/context/data/scite-context-data-metafun.lua lexers/themes/scite-context-theme.lua \stoptyping -The data files are needed because we cannot access property files -from within the lexer. If we could open a file we could use the -property files instead. +The data files are needed because we cannot access property files from within the +lexer. If we could open a file we could use the property files instead. -These files go to the \type {lexers} subpath in your \SCITE\ -installation. Normally this sits in the binary path. The -following files provide some extensions. On \MSWINDOWS\ you can copy -these files to the path where the \SCITE\ binary lives. +These files go to the \type {lexers} subpath in your \SCITE\ installation. +Normally this sits in the binary path. The following files provide some +extensions. On \MSWINDOWS\ you can copy these files to the path where the \SCITE\ +binary lives. \starttyping scite-ctx.lua \stoptyping -Because property files can only be loaded from the same path -where the (user) file loads them you need to copy the following -files to the same path where the loading is defined: +Because property files can only be loaded from the same path where the (user) +file loads them you need to copy the following files to the same path where the +loading is defined: \starttyping scite-context.properties @@ -367,41 +356,37 @@ to the file: SciTEUser.properties \stoptyping -Of course the pragma import is optional. You can comment either the -internal or external variant but there is no reason not to keep them both. +Of course the pragma import is optional. You can comment either the internal or +external variant but there is no reason not to keep them both. \subject{Extensions} -Just a quick not to some extensions. If you select a part of the -text (normally you do this with the shift key pressed) and you hit -\type {Shift-F11}, you get a menu with some options. More (robust) -ones will be provided at some point. +Just a quick not to some extensions. If you select a part of the text (normally +you do this with the shift key pressed) and you hit \type {Shift-F11}, you get a +menu with some options. More (robust) ones will be provided at some point. \subject{Spell checking} -If you want to have spell checking, you need have files with -correct words on each line. The first line of a file determines -the language: +If you want to have spell checking, you need have files with correct words on +each line. The first line of a file determines the language: \starttyping % language=uk \stoptyping -When you use the external lexers, you need to provide some files. -Given that you have a text file with valid words only, you can run -the following script: +When you use the external lexers, you need to provide some files. Given that you +have a text file with valid words only, you can run the following script: \starttyping mtxrun --script scite --words nl uk \stoptyping -This will convert files with names like \type {spell-nl.txt} into -\LUA\ files that you need to copy to the \type {lexers/data} path. -Spell checking happens realtime when you have the language -directive (just add a bogus character to disable it). Wrong words -are colored red, and words that might have a case problem are -colored orange. Recognized words are greyed and words with less -than three characters are ignored. +This will convert files with names like \type {spell-nl.txt} into \LUA\ files +that you need to copy to the \type {lexers/data} path. Spell checking happens +realtime when you have the language directive (just add a bogus character to +disable it). Wrong words are colored red, and words that might have a case +problem are colored orange. Recognized words are greyed and words with less than +three characters are ignored. In the case of internal lexers, the following file is needed: @@ -409,34 +394,32 @@ In the case of internal lexers, the following file is needed: spell-uk.txt \stoptyping -If you use the traditional lexer, this file is taken from the -path determined by the environment variable: +If you use the traditional lexer, this file is taken from the path determined by +the environment variable: \starttyping CTXSPELLPATH \stoptyping -As already mentioned, the lpeg lexer expects them in the data -path. This is because the \LUA\ instance that does the lexing is -rather minimalistic and lacks some libraries as well as cannot -access the main \SCITE\ state. +As already mentioned, the lpeg lexer expects them in the data path. This is +because the \LUA\ instance that does the lexing is rather minimalistic and lacks +some libraries as well as cannot access the main \SCITE\ state. -Spell checking in \type {txt} files is enabled by adding a first -line: +Spell checking in \type {txt} files is enabled by adding a first line: \starttyping [#!-%] language=uk \stoptyping -The first character on that line is one of the four mentioned -between square brackets. So, +The first character on that line is one of the four mentioned between square +brackets. So, \starttyping # language=uk \stoptyping -should work. For \XML\ files there are two methods. You can use the -following (at the start of the file): +should work. For \XML\ files there are two methods. You can use the following (at +the start of the file): \starttyping <?xml ... language="uk" ?> @@ -459,70 +442,63 @@ In a similar fashion you can drive the interface checking: \subject{Property files} -The internal lexers are controlled by the property files while the -external ones are steered with themes. Unfortunately there is -hardly any access to properties from the external lexer code nor -can we consult the file system and/or run programs like \type -{mtxrun}. This means that we cannot use configuration files in the -\CONTEXT\ distribution directly. Hopefully this changes with -future releases. +The internal lexers are controlled by the property files while the external ones +are steered with themes. Unfortunately there is hardly any access to properties +from the external lexer code nor can we consult the file system and/or run +programs like \type {mtxrun}. This means that we cannot use configuration files +in the \CONTEXT\ distribution directly. Hopefully this changes with future +releases. \subject{The external lexers} -These are the more advanced. They provide more detail and the \CONTEXT\ -lexer also supports nested \METAPOST\ and \LUA. Currently there is no -detailed configuration but this might change once they are stable. - -The external lexers operate on documents while the internal ones -operate on lines. This can make the external lexers slow on large -documents. We've optimized the code somewhat for speed and memory -consumption but there's only so much one can do. While lexing each -change in style needs a small table but allocating and garbage -collecting many small tables comes at a price. Of course in -practice this probably gets unnoticed. \footnote {I wrote the code -in 2011 on a more than 5 years old Dell M90 laptop, so I suppose -that speed is less an issue now.} - -In principle the external lexers can be used with \type -{textadept} which also uses \type {scintilla}. Actually, support -for lpeg lexing originates in \type {textadept}. Currently \type -{textadept} lacks a couple of features I like about \SCITE\ (for -instance it has no realtime logpane) and it's also still changing. -At some point the \CONTEXT\ distribution might ship with files -for \type {textadept} as well. - -The external lpeg lexers work okay with the \MSWINDOWS\ and -\LINUX\ versions of \SCITE, but unfortunately at the time of -writing this, the \LUA\ library that is needed is not available -for the \MACOSX\ version of \SCITE. Also, due to the fact that the -lexing framework is rather isolated, there are some issues that -cannot be addressed in the properly, at least not currently. - -In addition to \CONTEXT\ and \METAFUN\ lexing a \LUA\ lexer is -also provided so that we can handle \CONTEXT\ \LUA\ Document -(\CLD) files too. There is also an \XML\ lexer. This one also -provides spell checking. The \PDF\ lexer tries to do a good job on -\PDF\ files, but it has some limitations. There is also a simple -text file lexer that does spell checking. - -Don't worry if you see an orange rectangle in your \TEX\ or \XML\ -document. This indicates that there is a special space character -there, for instance \type {0xA0}, the nonbreakable space. Of course -we assume that you use \UTF8 as input encoding. +These are the more advanced. They provide more detail and the \CONTEXT\ lexer +also supports nested \METAPOST\ and \LUA. Currently there is no detailed +configuration but this might change once they are stable. + +The external lexers operate on documents while the internal ones operate on +lines. This can make the external lexers slow on large documents. We've optimized +the code somewhat for speed and memory consumption but there's only so much one +can do. While lexing each change in style needs a small table but allocating and +garbage collecting many small tables comes at a price. Of course in practice this +probably gets unnoticed. \footnote {I wrote the code in 2011 on a more than 5 +years old Dell M90 laptop, so I suppose that speed is less an issue now.} + +In principle the external lexers can be used with \type {textadept} which also +uses \type {scintilla}. Actually, support for lpeg lexing originates in \type +{textadept}. Currently \type {textadept} lacks a couple of features I like about +\SCITE\ (for instance it has no realtime logpane) and it's also still changing. +At some point the \CONTEXT\ distribution might ship with files for \type +{textadept} as well. + +The external lpeg lexers work okay with the \MSWINDOWS\ and \LINUX\ versions of +\SCITE, but unfortunately at the time of writing this, the \LUA\ library that is +needed is not available for the \MACOSX\ version of \SCITE. Also, due to the fact +that the lexing framework is rather isolated, there are some issues that cannot +be addressed in the properly, at least not currently. + +In addition to \CONTEXT\ and \METAFUN\ lexing a \LUA\ lexer is also provided so +that we can handle \CONTEXT\ \LUA\ Document (\CLD) files too. There is also an +\XML\ lexer. This one also provides spell checking. The \PDF\ lexer tries to do a +good job on \PDF\ files, but it has some limitations. There is also a simple text +file lexer that does spell checking. + +Don't worry if you see an orange rectangle in your \TEX\ or \XML\ document. This +indicates that there is a special space character there, for instance \type +{0xA0}, the nonbreakable space. Of course we assume that you use \UTF8 as input +encoding. \subject{The internal lexers} -\SCITE\ has quite some built in lexers. A lexer is responsible for -highlighting the syntax of your document. The way a \TEX\ file is -treated is configured in the file: +\SCITE\ has quite some built in lexers. A lexer is responsible for highlighting +the syntax of your document. The way a \TEX\ file is treated is configured in the +file: \starttyping tex.properties \stoptyping -You can edit this file to your needs using the menu entry under -\type {options} in the top bar. In this file, the following -settings apply to the \TEX\ lexer: +You can edit this file to your needs using the menu entry under \type {options} +in the top bar. In this file, the following settings apply to the \TEX\ lexer: \starttyping lexer.tex.interface.default=0 @@ -531,17 +507,16 @@ lexer.tex.comment.process=0 lexer.tex.auto.if=1 \stoptyping -The option \type {lexer.tex.interface.default} determines the way -keywords are highlighted. You can control the interface from your -document as well, which makes more sense that editing the -configuration file each time. +The option \type {lexer.tex.interface.default} determines the way keywords are +highlighted. You can control the interface from your document as well, which +makes more sense that editing the configuration file each time. \starttyping % interface=all|tex|nl|en|de|cz|it|ro|latex \stoptyping -The values in the properties file and the keywords in the preamble -line have the following meaning: +The values in the properties file and the keywords in the preamble line have the +following meaning: \starttabulate[|lT|lT|p|] \NC 0 \NC all \NC all commands (preceded by a backslash) \NC \NR @@ -555,19 +530,19 @@ line have the following meaning: \NC 8 \NC latex \NC \LATEX\ (apart from packages) \NC \NR \stoptabulate -The configuration file is set up in such a way that you can easily -add more keywords to the lists. The keywords for the second and -higher interfaces are defined in their own properties files. If -you're curious about the way this is configures, you can peek into -the property files that start with \type {scite-context}. When you -have \CONTEXT\ installed you can generate configuration files with +The configuration file is set up in such a way that you can easily add more +keywords to the lists. The keywords for the second and higher interfaces are +defined in their own properties files. If you're curious about the way this is +configures, you can peek into the property files that start with \type +{scite-context}. When you have \CONTEXT\ installed you can generate configuration +files with \starttyping mtxrun --script interface --scite \stoptyping -You need to make sure that you move the result to the right place so best -not mess around with this command and use the files from the distribution. +You need to make sure that you move the result to the right place so best not +mess around with this command and use the files from the distribution. Back to the properties in \type {tex.properties}. You can disable keyword coloring alltogether with: @@ -588,8 +563,8 @@ in a uniform color. But, when set to one, you will get as much colors as a \TEX\ source. It's a matter of taste what you choose. The lexer tries to cope with the \TEX\ syntax as good as possible and takes for -instance care of the funny \type {^^} notation. A special treatment is -applied to so called \type {\if}'s: +instance care of the funny \type {^^} notation. A special treatment is applied to +so called \type {\if}'s: \starttyping lexer.tex.auto.if=1 @@ -597,15 +572,15 @@ lexer.tex.auto.if=1 This is the default setting. When set to one, all \type {\ifwhatever}'s will be seen as a command. When set to zero, only the primitive \type {\if}'s will be -treated. In order not to confuse you, when this property is set to one, the -lexer will not color an \type {\ifwhatever} that follows an \type {\newif}. +treated. In order not to confuse you, when this property is set to one, the lexer +will not color an \type {\ifwhatever} that follows an \type {\newif}. \subject{The \METAPOST\ lexer} The \METAPOST\ lexer is set up slightly different from its \TEX\ counterpart, -first of all because \METAPOST\ is more a language that \TEX. As with the -\TEX\ lexer, we can control the interpretation of identifiers. The \METAPOST\ -specific configuration file is: +first of all because \METAPOST\ is more a language that \TEX. As with the \TEX\ +lexer, we can control the interpretation of identifiers. The \METAPOST\ specific +configuration file is: \starttyping metapost.properties @@ -674,13 +649,13 @@ find \type {mtxrun} in: or in a similar path that suits the operating system that you use. -When you hit \type{CTRL-12} your document will be processed. Take a look at -the \type {Tools} menu to see what more is provided. +When you hit \type{CTRL-12} your document will be processed. Take a look at the +\type {Tools} menu to see what more is provided. \subject{Extensions (using \LUA)} -When the \LUA\ extensions are loaded, you will see a message -in the log pane that looks like: +When the \LUA\ extensions are loaded, you will see a message in the log pane that +looks like: \starttyping - see scite-ctx.properties for configuring info @@ -710,9 +685,9 @@ This message tells you what extras are available. \subject{Templates} -There is an experimental template mechanism. One option is to define -templates in a properties file. The property file \type -{scite-ctx-context} contains definitions like: +There is an experimental template mechanism. One option is to define templates in +a properties file. The property file \type {scite-ctx-context} contains +definitions like: \starttyping command.25.$(file.patterns.context)=insert_template \ @@ -757,9 +732,9 @@ ctx.template.structure.itemize.example=\ </itemize>\n \stoptyping -For larger projects it makes sense to keep templates with the -project. In one of our projects we have a directory in the -path where the project files are kept which holds template files: +For larger projects it makes sense to keep templates with the project. In one of +our projects we have a directory in the path where the project files are kept +which holds template files: \starttyping ..../ctx-templates/achtergronden.xml @@ -777,13 +752,13 @@ ctx.template.mathadore.achtergronden.file=smt-achtergronden.xml ctx.template.mathadore.bewijs.file=smt-bewijs.xml \stoptyping -However, when no such menu is defined, we will automatically scan -the directory and build the menu without user intervention. +However, when no such menu is defined, we will automatically scan the directory +and build the menu without user intervention. \subject{Using \SCITE} -The following keybindings are available in \SCITE. Most of this -list is taken from the on|-|line help pages. +The following keybindings are available in \SCITE. Most of this list is taken +from the on|-|line help pages. \startbuffer[keybindings] \starttabulate[|l|p|] |