Function Reference 2
New function reference proposal:
Note: I've used some things from WEML, but there are so many elements which I do not understand and some missing properties, so I've decided to prepare native FR format for bluefish again.
1. ----------- General comments -----------------
For now I distinguish three type of languages in FR:
- programming (like PHP,Python etc.) - markup (HTML,XHTML) - CSS-type - I've included this because of difficulties encountered during CSS specification
Each type of language has its own elements, so the main elements of function reference are:
- functions - for programming languages - classes - for OO programming languages - tags - for markup - properties - for CSS
Along with functional elements of language we need to describe actions which can be performed when using FR in Bluefish. So far I've defined three type of actions:
- show information - show input dialog with needed parameters and insert text - insert text immediately
2. --------------- Reusable blocks ----------------
To reduce the size of FR files we need a mechanism of reusable blocks (many parameters or attributes are the same in functions or tags).
3. ---------------- Visual grouping ---------------
It has been proved (by usage) that functions or tags should be grouped when they are displayed in FR tree. It helps with searching for specific element and gives us possibility of logical element ordering.
4. ----------------- User interface --------------
Here I would like to propose: a FR tree in left panel as it is implemented now plus information window, but not that small which is in panel - rather something like output window below panel and text editing.
5. ----------------- CSS specification -----------
I need help with this. Tim tried to explain me some CSS issues, but I'm not using CSS, so please look at format proposal below and help me create entries for CSS.
6. ---------------- i18n ------------------------
It would be great to have all reference translated to many languages. We can insert translations into main reference file or prepare different files for every supported language - comments ?
6. --------------- Proposed format (revised) --------------
'''<ref name<code>\"\" description</code>\"\">''' This is reference root element
'''<note title=\"\">''' Any note you want to present for reference '''</note>'''
'''<group name=\"\">'''
'''<description ref=\"\">''' group description '''</description>'''
... elements ...
'''</group>'''
'''<element kind<code>\"function|tag|var|css''property|css''selector|snippet\" name</code>\"\">'''
'''<description ref=\"\">''' description of an element '''</description>'''
'''<note title=\"\">''' Any note you want to present for element - can be more than one '''</note>'''
'''<properties>'''
'''<proplist ref=\"\" />''' - list of previously defined properties, look at <def> description
*<property kind=\"link|example|dependency|attribute|parameter|return|parents\"
name<code>\"\" ref</code>\"\" type<code>\"\" required</code>\"\" default<code>\"\" input</code>\"\">*
''Where:''
''ref - reference to <def> tag''
''type - usable in 'return' as a function return type and parameter type''
''required - whether this property is required or not''
''default - default value''
_input - indicates type of control used in dialog, recognized values are:
\"entry\"(default),\"list\", \"list+entry\",\"colour\",\"colour+list\",\"file\" _
'''<description ref=\"\">''' Property description '''</description>'''
'''<values ref=\"\">'''
List of values for this property. You can use both 'ref' attribute and value list
inside element. Both lists will be concatenated.
'''</values>'''
'''</property>'''
'''</properties>'''
'''<insert python=\"0|1\">'''
Text to insert into editor either automatic or interactive.
If 'python' attribute is set to 1 that means, this text IS NOT something to insert into
editor but Python script to interpret instead. Default value for 'python' attribute is FALSE (0)
'''</insert>'''
'''</element>'''
*<def deftype=\"property|description|values|proplist\"
kind<code>\"link|example|dependency|attribute|parameter|return|parents\" id</code>\"\" ...>*
Reusable definition that can be used above when setting '''ref''' attribute
'''</def>'''
'''</ref>'''
Compact form ---------------------------
To decrease size of files I propose some modification. Instead of full names like \"function\" or \"element\" we can use one-char or two-char mnemonics (such form is called 'compact reference'). File is still a XML document, but is not so easy readable by user. Con of this solution is much less space used by reference. To ease conversion I prepared pyhon script.
Dictionary for compactifying: a - attribute c - class c1 - css c2 - children d - description d1 - dependency d2 - default d3 - def d4 - deftype e - element e1 - example f - function g - group i - insert i1 - id k - kind l - link n - name n1 - note p - properties p1 - property p2 - parameter p3 - parents r - ref r1 - return r2 - required s - snippet t - title t1 - tag t2 - type v - vlistonly v1 - values v2 - version x - compact