3,899
edits
Changes
Initial documentation page for the source browser
= Introduction =
The ConTeXt source browser at [http://source.contextgarden.net http://source.contextgarden.net] has recently been replaced by a Lua implementation that uses Hans Hagen's SciTE lexers for syntax highlighting and a search index that is built up using a Lua script.
= Browsing the installed files =
You can use the source browser to walk through the directory tree of the ConTeXt installation that is on the server. This is the same ConTeXt installation that is used for [http://live.contextgarden.net ConTeXt live], the <nowiki><context></nowiki> examples, and the <nowiki><syntax></nowiki> extension on the wiki.
This installation is not always completely in sync with the latest ConTeXt distribution, because setting up the installation on the server is quite elaborate (as various auxiliary databases need to be updated as well).
= Searching the sources =
You can use the search field to search for a particular (part of a) word in the ConTeXt distribution.
''Note:'' At the moment, you cannot do AND/OR searches or search for multiple words at the same time.
The search field uses Lua patterns by default.
Quick start: Lua patterns have roughly the same list of special characters as simple regular expressions, but they use the <code>%</code> character for escaping those. See the [https://www.lua.org/manual/5.3/manual.html#6.4.1 Patterns section] of the Lua manual for details.
There are four option checkboxes below the search input. Each of these are optional, with irrelevant values. The script only looks at the existence of the option, it never checks the actual values except for the value of the <code>search</code> parameter itself.
== ignore comments ==
Name: '''igncomments'''
Default: '''ON'''
This skips everything that is marked as 'comment' by the SciTE lexers.
== ignore doc tree ==
Name: '''igndocs'''
Default: '''ON'''
This skips all files in the <code>doc/</code> subtree.
== whole words only ==
Name: '''wholewords'''
Default: '''OFF'''
Modifies the search pattern by anchoring it to the begin and end of the search index keys, as if it was enclosed in <code>^</code>...<code>$</code>
== plain text matches ==
Name: '''p'''
Default: '''OFF'''
Treats the input as plain text instead of a lua pattern.
= Highlighting of search terms =
If you select a file that matches your search term, it will highlight the found matches with a yellow background. It also makes the page number of matching lines into a hyperlink to the next match in that file.
The highlighting is done separate from the search index, which means that it will sometimes find extra matches. For example, if you search for <code>def</code>, you would not see all the thousands of hits for <code>\def</code> in the file list on the left. But if you click on a particular file, the syntax highlighter will highlight all of the <code>def</code> substrings it finds in the entire file.
Sometime in the future, I will try to limit the highlighter to only highlight lines that are actually in the match list.
= Linking from the wiki =
From the wiki, you can use the <nowiki>{{src}}</nowiki> template to link directly to a file in the <code>tex/context/base/mkiv</code> folder. If you want to do a search as well:
<nowiki>{{src|context.mkiv}}</nowiki>
<nowiki>{{src|context.mkiv?search{{=}}lang-}}</nowiki>
<nowiki>{{src|context.mkiv?search{{=}}lang-&p{{=}}1}}</nowiki>
<nowiki>{{src|context.mkiv#l107}}</nowiki>
{{src|context.mkiv}}
{{src|context.mkiv?search{{=}}lang}}
{{src|context.mkiv?search{{=}}lang-&p{{=}}1}}
{{src|context.mkiv#l107}}
''Note that you have to write the equals sign as <nowiki>{{=}}</nowiki>.''
= A note about the search index =
The search index is generated by a Lua script that parses the output of the SciTE Lexers. This process is not always perfect due to both small errors in the SciTE Lexers and in the lua script that parses its output.
Some limitations of the search index are hardcoded, and unlikely to change:
* Only ASCII is indexed: the index is not unicode-aware. Fixing this may be doable but would be a lot of work for very little gain (the only non-ASCII in the source is in the interface translation files).
* Only included are 'words' that contain at least one ASCII letter.
* Only words longer than three letters are indexed.
* Lua language keywords and matches that occur more than 1000 times (approx.) are not indexed.
* All of the files in the <code>patterns/</code> subtree are skipped.
If you find a problem that is not caused by one of the aforementioned limitations, please report it to [[User:taco]] by sending an email to [mailto:gardeners@contextgarden.net gardeners@contextgarden.net].
The ConTeXt source browser at [http://source.contextgarden.net http://source.contextgarden.net] has recently been replaced by a Lua implementation that uses Hans Hagen's SciTE lexers for syntax highlighting and a search index that is built up using a Lua script.
= Browsing the installed files =
You can use the source browser to walk through the directory tree of the ConTeXt installation that is on the server. This is the same ConTeXt installation that is used for [http://live.contextgarden.net ConTeXt live], the <nowiki><context></nowiki> examples, and the <nowiki><syntax></nowiki> extension on the wiki.
This installation is not always completely in sync with the latest ConTeXt distribution, because setting up the installation on the server is quite elaborate (as various auxiliary databases need to be updated as well).
= Searching the sources =
You can use the search field to search for a particular (part of a) word in the ConTeXt distribution.
''Note:'' At the moment, you cannot do AND/OR searches or search for multiple words at the same time.
The search field uses Lua patterns by default.
Quick start: Lua patterns have roughly the same list of special characters as simple regular expressions, but they use the <code>%</code> character for escaping those. See the [https://www.lua.org/manual/5.3/manual.html#6.4.1 Patterns section] of the Lua manual for details.
There are four option checkboxes below the search input. Each of these are optional, with irrelevant values. The script only looks at the existence of the option, it never checks the actual values except for the value of the <code>search</code> parameter itself.
== ignore comments ==
Name: '''igncomments'''
Default: '''ON'''
This skips everything that is marked as 'comment' by the SciTE lexers.
== ignore doc tree ==
Name: '''igndocs'''
Default: '''ON'''
This skips all files in the <code>doc/</code> subtree.
== whole words only ==
Name: '''wholewords'''
Default: '''OFF'''
Modifies the search pattern by anchoring it to the begin and end of the search index keys, as if it was enclosed in <code>^</code>...<code>$</code>
== plain text matches ==
Name: '''p'''
Default: '''OFF'''
Treats the input as plain text instead of a lua pattern.
= Highlighting of search terms =
If you select a file that matches your search term, it will highlight the found matches with a yellow background. It also makes the page number of matching lines into a hyperlink to the next match in that file.
The highlighting is done separate from the search index, which means that it will sometimes find extra matches. For example, if you search for <code>def</code>, you would not see all the thousands of hits for <code>\def</code> in the file list on the left. But if you click on a particular file, the syntax highlighter will highlight all of the <code>def</code> substrings it finds in the entire file.
Sometime in the future, I will try to limit the highlighter to only highlight lines that are actually in the match list.
= Linking from the wiki =
From the wiki, you can use the <nowiki>{{src}}</nowiki> template to link directly to a file in the <code>tex/context/base/mkiv</code> folder. If you want to do a search as well:
<nowiki>{{src|context.mkiv}}</nowiki>
<nowiki>{{src|context.mkiv?search{{=}}lang-}}</nowiki>
<nowiki>{{src|context.mkiv?search{{=}}lang-&p{{=}}1}}</nowiki>
<nowiki>{{src|context.mkiv#l107}}</nowiki>
{{src|context.mkiv}}
{{src|context.mkiv?search{{=}}lang}}
{{src|context.mkiv?search{{=}}lang-&p{{=}}1}}
{{src|context.mkiv#l107}}
''Note that you have to write the equals sign as <nowiki>{{=}}</nowiki>.''
= A note about the search index =
The search index is generated by a Lua script that parses the output of the SciTE Lexers. This process is not always perfect due to both small errors in the SciTE Lexers and in the lua script that parses its output.
Some limitations of the search index are hardcoded, and unlikely to change:
* Only ASCII is indexed: the index is not unicode-aware. Fixing this may be doable but would be a lot of work for very little gain (the only non-ASCII in the source is in the interface translation files).
* Only included are 'words' that contain at least one ASCII letter.
* Only words longer than three letters are indexed.
* Lua language keywords and matches that occur more than 1000 times (approx.) are not indexed.
* All of the files in the <code>patterns/</code> subtree are skipped.
If you find a problem that is not caused by one of the aforementioned limitations, please report it to [[User:taco]] by sending an email to [mailto:gardeners@contextgarden.net gardeners@contextgarden.net].