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