SourceBrowser/doc

From Wiki
Jump to navigation Jump to search

Introduction

The ConTeXt source browser at 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.

Note: for some of the really large files (for example char-def.lua), syntax highlighting is disabled.

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 ConTeXt live, the <context> examples, and the <syntax> 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).

When viewing a file, on top of the highlighted source the file name is displayed. This is also a download link. It also shows the file size and a modification time (but that is the creation time of the ConTeXt distribution, so not particularly useful).

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.

There are four option checkboxes immediately below the search input, and two separate options, to control the search. 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 search parameter itself.

Optional search index: Comments

Name: comments Default: OFF

This includes the index of everything that is marked as 'comment' by the SciTE lexers.

Optional search index: Docs

Name: docs Default: OFF

This includes the index of all files in the doc/ subtree.

Optional search index: MkII

Name: mkii Default: OFF

This includes the index of MkII files.

Optional search index: Data

Name: data Default: OFF

This includes the index of Data files (data/ subtree, interface/ subtree, scripts/ subtree, sample files, test files, et cetera).

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 ^...$

Lua string pattern matches

Name: pat Default: OFF

Treats the input as a lua string pattern instead of plain text.

Quick start: Lua patterns have roughly the same list of special characters as simple regular expressions, but they use the % character for escaping those. See the Patterns section of the Lua manual for details.

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 def, you would not see all the thousands of hits for \def in the file list on the left. But if you click on a particular file, the syntax highlighter will highlight all of the def substrings it finds on any matching line.

Linking from the wiki

From the wiki, you can use the {{src}} template to link directly to a file in the tex/context/base/mkiv folder.

 {{src|context.mkiv}}

context.mkiv


If you want to do a search as well, or link to a line number:

 {{src|context.mkiv?search{{=}}lang-}}
 {{src|context.mkiv?search{{=}}lang-&pat{{=}}1}}
 {{src|context.mkiv#l107}}

context.mkiv?search=lang-

context.mkiv?search=lang-&pat=1

context.mkiv#l107

Note that you have to write the equals sign as {{=}} inside wiki templates.

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 patterns/ subtree and the top-level fonts/ tree 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 gardeners@contextgarden.net.