Christian: New page: 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 na...

2008-10-26T22:19:10Z

New page: 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 na...

New page

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) --------------

<pre>
'''<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>'''

</pre>

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

<pre>
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
</pre>

Function Reference 2 - Revision history

Christian: New page: 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 na...