#summary Kandil is the magic oil-lamp that manifests your dreams about documentation.

= Kandil =
Kandil is an XHTML and !JavaScript browser application for documentation
generated by DIL.

[http://www.digitalmars.com/d/ddoc.html Ddoc] is used as the underlying system to generate the documentation.
DIL improves upon Ddoc with unique features and introduces small differences:

== Features ==
  * The XHTML and !JavaScript code are developed for the latest W3C-standards compliant browsers. Internet Explorer is not supported.<br>It's not my intention to exclude IE users, but the fact of the matter is that it costs a lot of energy and nerves to code for Microsoft's browsers.<br>Even coding only for the "good" browsers is sometimes difficult enough.<br>So, no support for IE, until it gets its act together.<br><u>Browsers that have been tested</u>: Opera 10.50, Firefox 3.6, Google Chrome 5.0.307.11 (Linux beta), Safari 4.0.4 (531.21.10) and Konqueror 4.3.4
  * Known browser issues:
    * Some browsers don't support loading files using XMLHttpRequest on _localhost_.<br>Because of this, features like showing the code of a symbol and viewing a tree of all symbols in the Symbols tab will not work.
  * Kandil tries to make use of the latest HTML5 features if available:
    * [http://dev.w3.org/html5/webstorage/ Web Storage] is used to store settings and to cache generated lists. Caching speeds up load times.
    * The [http://dev.w3.org/html5/spec/history.html History] object allows you to create a new history entry and also alter the URL in the address bar. This avoids loading the navigation bar again, when browsing a project's documentation.
  * Display the source code of a symbol when clicked.
  * The symbol and module list in the navigation bar can be filtered.
  * Every symbol in the document is targetable using a URL fragment.<br>E.g.: [http://dil.googlecode.com/svn/doc/dil/dil.doc.Macro.html#Macro.this url/dil.doc.Macro.html#Macro.this]
  * Superfluous indentation is removed from code embedded in comments.
  * Every symbol can be linked to its source location (a repository or a local HTML file.)
  * Protection, linkage and storage class attributes are shown in brackets.
  * Report warnings for undefined macros and unterminated macros (missing closing ')'.)
  * Every token in a code section is highlighted (customizable via kandil/style.css and data/html_map.d.)
  * Tokens in parameter lists and return types are highlighted (e.g. `void f(ref p, char[] q = "str"`).
  * Undocumented symbols can be included in the documentation using the '-i'-switch.
  * Unicode alphas are supported in macro, section and parameter names.
  * Not strictly a feature of kandil, but html2pdf.py can generate PDF documents using [http://princexml.com PrinceXML].

== FAQ ==
||How can I link to other symbols?||

Use the macros SYMLINK and SYMLINK2. E.g.:
 # `$(SYMLINK Macro.this, Macro Constructor)` would link to the symbol Macro.this in the current module.
 # `$(SYMLINK2 dil.doc.Macro, Macro.this, see how to construct a macro)` would link to Macro.this in the module dil.doc.Macro.

== Filtering ==
There are three ways you can filter for specific symbols:

=== Plain text ===
Enter letters or words as usual, and a list of symbols that match will be shown. For example, "Expr" will match "Expression", "!AndExpression", "!OrExpression" etc.<br>
You can also put a wildcard between two strings, e.g. "parse*ion" will match "parseExpression".

=== FQN filtering ===
Use a dot to separate words in order to search for symbols by matching against their fully qualified names (FQN.) For example, "tango.math" will match any symbol that is located in the math package. Or ".math." will show all math packages - if there are more than one - and the contained modules.

=== Attribute filtering ===
Strings that start with a colon, ":", will search for symbols by matching against their attributes. Attributes can be symbol kinds (e.g. "variable", "function"...) and storage classes (e.g. "extern", "protected"...). For example, the strings ":pub", ":publ", ":public" will search for symbols that have the public protection attribute. You don't have to type out the complete name of the attribute.

== Macros ==
This is a list of macros which are only defined by DIL.
  * DIL_SYMBOL (replaces DDOC_PSYMBOL)<br>Five Parameters:
      # Symbol name (e.g. "this")
      # Fully qualified name excluding the module's FQN (e.g. "Macro.this", MODFQN = "dil.doc.Macro")
      # Symbol kind (e.g. "ctor")<br>Values: `template, class, interface, struct, union, alias, typedef, enum, enummem, function, variable, invariant, new, delete, unittest, ctor, dtor, sctor, sdtor`
      # Begin line number in the code (e.g. 19)
      # End line number in the code (e.g. 23)
  * DIL_MODFQN      (e.g. "dil.doc.Macro")
  * DIL_MODPATH     (e.g. "dil/doc/Macro.d")
  * DIL_DOCFILENAME (e.g. "dil.doc.Macro.html")
  * DIL_KW<br>The keyword of a D declaration (e.g. `class`, `alias`, `auto` etc.)
  * DIL_ATTRIBUTES
  * DIL_PROT
  * DIL_STC
  * DIL_LINKAGE
  * DIL_PARAMS
  * DIL_TEMPLATE_PARAMS
  * DIL_BASECLASS
  * DIL_BASECLASSES
  * DDOC_AUTHOR (singular of existing DDOC_AUTHORS)
  * DIL_SC: a semicolon after a declaration.

== Shortcomings ==
In contrast to dmd, DIL doesn't highlight some keywords (e.g. null) and it
doesn't emphasize symbols found in the comment text. In my experience, this
is more trouble than desirable; to require explicit marking would have been better.
Nevertheless, this might be implemented using !JavaScript.

Sometimes it is apparent that semantic information is lacking. Furthermore, `static if`-statements are not evaluated (the if-branch is always chosen by default,) since SA in DIL is not advanced enough, even for evaluating simple expressions.
