kate/INDENTATION

   1 #
   2 # Indentation for Dummies
   3 #
   4
   5 This file should is aimed to describe how the KatePart in KDE 4 is designed to allow
   6 flexible indentation based on JavaScripts.
   7
   8 As references, a good read is the way VIM handles this all, Emacs is out of scope I think,
   9 as it's just to mangled together there with the mighty lisp engine.
  10
  11 VIM seems to have a fairly simple way to integrate indentation scripts, I guess a similar
  12 approach is no bad idea...
  13
  14 What tell the VIM docs about indentation?
  15 http://www.vim.org/htmldoc/indent.html
  16
  17 Some little HOWTO showing a simple Pascal indenter:
  18 http://psy.swan.ac.uk/staff/carter/unix/vim_indent.htm
  19
  20 In short, how does scripted indentation work in VIM?
  21
  22  - you must write a functions which returns for a given line the wanted indentation level.
  23  - you specify some keywords/char which trigger indentation, inserting a linebreak always triggers it
  24  - if indentation is triggered, VIM evaluates the function for the line and reindents the line to the
  25    returned level or keeps the current indentation level if -1 is returned
  26
  27 This sounds fairly simple, but seems to be enough for normal world usage, given that VIM is
  28 very popular....
  29
  30 KatePart's current indentation scripts work similar, but are triggered on each keystroke.
  31 I guess only calling them for linebreaks + special chars would increase performance already
  32 a lot. Next part is that the scripts atm indent theirself, I guess letting them just return the
  33 needed level and let the C++ code really indent the line would be faster and easier for the script
  34 writers, too.
  35
  36 One bad thing with the VIM way is that mixed indentation won't work correct, you can't return in one
  37 int that the first 4 chars can be replaced with tabs, if tab indentation is enabled but the remaining 4
  38 chars should stay single spaces, as it is useful in this example (given tabwidth is 4):
  39
  40 int test ()
  41 {
  42     if (hello ||
  43         muhh) // this line should be indented with tab + 4 spaces
  44         return 1; // this line should be indented with 2 tabs
  45
  46     return 0;
  47 }
  48
  49 I think we should have a interface in which the script indicates which normal indentation is wanted
  50 and which further amount of spaces should be inserted to align with other words/keywords whatever...
  51
  52 As it shows up, if we want to support both mixed-indentation and alignment, indent/unindent functions can't
  53 be generic, as there is no way to tell, if for example 8 spaces are actually one tab, as they are 2 indent levels
  54 or just one indent level + 4 alignment spaces. Therefor will take the vim way of things, where alignment is not
  55 possible...
  56
  57 #
  58 # Built-in indenters
  59 #
  60 Right now we removed all built-in indenters due to refactoring and new indentation system. If it turns
  61 out that js indentation for complex stuff like c/c++ is too slow, we maybe have to reintroduce the
  62 built-in indenters. Interesting reference might be in vim, see: vim/src/misc1.c, function get_c_indent.
  63
  64 #
  65 # Idea: Extending itemData (=attribute information)
  66 #
  67 Scripts would benefit if they could access highlighting information in a -reliable- way, i.e. -not-
  68 what we have now in KateNormalIndent::updateConfig().
  69
  70 Possible solution: extend itemData to have another attribute 'type'.
  71 Example: <itemData defStyleNum="dsNormal" ... type="default"/>
  72 What types do indentation scripts need? C/C++ like languages need:
  73  * default = everything that is not of the following types
  74  * comment = single and multiline comments, and #if 0ed code
  75  * string  = "..." and '...' strings
  76  * pp      = all preprocessor macros (#ifdef etc.)
  77  * symbol  = characters like: {}[](),; (and more)
  78
  79 This is actually everything we need for C like languages. Though, some further thoughts:
  80  * number  = all kind of numbers: int, double, float
  81  * keyword = keywords like: void, int, while, class
  82 Those two maybe would be a nice addon, but they are not necessarily needed for indentation.
  83
  84 Shortcomings:
  85 We need a good set of 'types', as they will be hard coded in the Kate Part.
  86 -> Todo: Think of other languages, what types do we need?
  87
  88 In what way are those types useful?
  89 Indenters (and scripts) can for example query doc.findOfType("{", "symbol");
  90 This will skip all { in comments and strings.
  91 Indenters can check 'where are we?': if (doc.typeAt(cursor) == "comment") ...
  92 -> Todo: Find good API.
  93
  94 How to make it work with our .xml files?
  95 To be backward compatible, the default type would be "default", if not defined otherwise.
  96 To make it work with our .xml files, we would need to adapt C++/Java/Php/... files to set the types
  97 correctly.
  98 Implementation: Extend KateExtendedAttribute to contain the type (besides the defaultStyle). To make
  99 it fast, use an integer (enum) just like the defaultStyles.
 100
 101 Another approach: Instead of putting a type into a KateExtendedAttribute, we also can put the type
 102 into the KTextEditor::Attribute. Then overlay highlighting like it probably will be done by KDevelop
 103 can also provide the needed type information (otherwise indentation might not work).
 104
 105 Thoughts welcome.