XSLT doc: function signatures menu
Hi, Still about the oXygen documentation system for XSLT, the generated function summary (in the left-hand side panel) looks like: http://fgeorges.org/tmp/oxygen-doc-summary.png. In order to improve its readability, I'd like to suggest two changes: 1/ put no withespace in front of a function name, but put one in front of continuation lines (if the signatures continue on several lines) and 2/ do not put the param types in the signatures (anyway there is no overload on types). So instead of (as in the screenshot): gdata:auth-sub-session-token($token as xs:string) gdata:authenticate-login($service as xs:string, $email as xs:string, $pwd as xs:string) have instead: gdata:auth-sub-session-token($token) gdata:authenticate-login($service, $email, $pwd) Regards, -- Florent Georges http://fgeorges.org/
Hello, Thank you for your suggestions. I've added them to our issue tracking tool and we'll resolve them as soon as possible. Best regards, Alex -- Alex Jitianu <oXygen/> XML Editor http://www.oxygenxml.com On 2/23/2010 4:13 AM, Florent Georges wrote:
Hi,
Still about the oXygen documentation system for XSLT, the generated function summary (in the left-hand side panel) looks like: http://fgeorges.org/tmp/oxygen-doc-summary.png.
In order to improve its readability, I'd like to suggest two changes: 1/ put no withespace in front of a function name, but put one in front of continuation lines (if the signatures continue on several lines) and 2/ do not put the param types in the signatures (anyway there is no overload on types). So instead of (as in the screenshot):
gdata:auth-sub-session-token($token as xs:string) gdata:authenticate-login($service as xs:string, $email as xs:string, $pwd as xs:string)
have instead:
gdata:auth-sub-session-token($token) gdata:authenticate-login($service, $email, $pwd)
Regards,
alex_jitianu wrote: Alex,
I've added them to our issue tracking tool and we'll resolve them as soon as possible.
Thanks for your response. As we are talking about that, I think the "Used By" function list (as shown in the following screenshot: http://fgeorges.org/tmp/oxygen-used-by.png) should also get the same changes: remove the param's type and maybe put each function on its own line. Maybe the infotip can show more infos like: {ns-uri}function($param as type) Regards, -- Florent Georges http://fgeorges.org/
Hi, Thanks for the suggestions. We will make the functions signatures more compact (by removing the param's type) in every place they are presented. And also use the infotip for more detailed information. The XSLT elements that appear in the "Used by" section are not each one on a different line in order to make the documentation more compact. For a great number of elements that use a specific elements, the "Used by" will result in a very long list. But I agree that a list makes them easier to read. Maybe we should add another option to control the way the "Used by" and other sections are generated : as lists or in a compact mode. Best regards, Alex -- Alex Jitianu <oXygen/> XML Editor http://www.oxygenxml.com On 2/23/2010 5:43 PM, Florent Georges wrote:
alex_jitianu wrote:
Alex,
I've added them to our issue tracking tool and we'll resolve them as soon as possible.
Thanks for your response. As we are talking about that, I think the "Used By" function list (as shown in the following screenshot: http://fgeorges.org/tmp/oxygen-used-by.png) should also get the same changes: remove the param's type and maybe put each function on its own line. Maybe the infotip can show more infos like:
{ns-uri}function($param as type)
Regards,
Alex Jitianu wrote: Hi,
But I agree that a list makes them easier to read. Maybe we should add another option to control the way the "Used by" and other sections are generated : as lists or in a compact mode.
Great! I know that's a hard problem. I have written years ago such a (very) simple system to document stylesheets and it was already a nightmare to satisfy my own taste for several different stylesheets, with different conventions and different shapes. About the explosion of the number of options when trying to satisfy everyone, maybe adding plain global parameters to the oXygen's stylesheets (I mean the stylesheets in the framework "stylesheet_documentation") with a paameter table in the Settings panel of the generation tool would be an easy solution. Regards, -- Florent Georges http://fgeorges.org/
Hi, On 2/23/2010 10:15 PM, Florent Georges wrote:
About the explosion of the number of options when trying to satisfy everyone, maybe adding plain global parameters to the oXygen's stylesheets (I mean the stylesheets in the framework "stylesheet_documentation") with a paameter table in the Settings panel of the generation tool would be an easy solution.
That might be the right solution for options that only take effect for a specific format. Putting such options in the Settings panel is inappropriate since they don't apply to every format. I will log this together with the other suggestions. Best regards, Alex -- Alex Jitianu <oXygen/> XML Editor http://www.oxygenxml.com
participants (3)
-
Alex Jitianu -
alex_jitianu
-
Florent Georges