OFBiz
  1. OFBiz
  2. OFBIZ-569 Improve/reorganize the project's website
  3. OFBIZ-571

Move the various documentation pages to the OFBTECH space on docs.ofbiz.org

    Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: Release Branch 4.0, SVN trunk
    • Component/s: site
    • Labels:
      None

      Description

      Move the various documentation pages and even the main Docs & Books page to the OFBTECH space on docs.ofbiz.org

      1. AScreenCopy.PNG
        9 kB
        Jacques Le Roux
      2. mini-ss.jpg
        119 kB
        Scott Gray
      3. simple-methods.html
        127 kB
        Jacques Le Roux
      4. simple-methods.xsd.patch
        73 kB
        Jacques Le Roux
      5. simple-methods.xsl
        6 kB
        Jacques Le Roux
      6. simple-methods.xsl
        4 kB
        Scott Gray
      7. XSL Output.html
        38 kB
        Scott Gray

        Activity

        Hide
        Jacques Le Roux added a comment -

        Can I close this issue ?

        Show
        Jacques Le Roux added a comment - Can I close this issue ?
        Hide
        Jacques Le Roux added a comment -

        Some work to be done on service*.xsd also, I will take care of it ... later ... Of course everybody is welcome on these tasks. I'm sure it will accelerate OFBiz best practices adoptions and by chance new valuable contributors...

        Show
        Jacques Le Roux added a comment - Some work to be done on service*.xsd also, I will take care of it ... later ... Of course everybody is welcome on these tasks. I'm sure it will accelerate OFBiz best practices adoptions and by chance new valuable contributors...
        Hide
        Jacques Le Roux added a comment -

        I have slightly modified the simple-methods.xsl file Scott provided, in order to improve readeability of the resulting htlm file (formatting indentation, adding title, <hr>, <br>, etc.). There is still some structural work to do on it (elements are not taken in account, etc.).
        I guess a re-organisation of simple-methods.xsd, in order to render a better doc file (tags ordering, anchors, etc.), is also needed. BTW I suggest to name this latest simple-methods.html. I will continue to work on this issue. In the meantime, we may use was is already generated in http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide+%28work+in+progress...%29, what do you think folks ?

        After I hope to do the same work on widget-*.xsd files.

        Show
        Jacques Le Roux added a comment - I have slightly modified the simple-methods.xsl file Scott provided, in order to improve readeability of the resulting htlm file (formatting indentation, adding title, <hr>, <br>, etc.). There is still some structural work to do on it (elements are not taken in account, etc.). I guess a re-organisation of simple-methods.xsd, in order to render a better doc file (tags ordering, anchors, etc.), is also needed. BTW I suggest to name this latest simple-methods.html. I will continue to work on this issue. In the meantime, we may use was is already generated in http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide+%28work+in+progress...%29 , what do you think folks ? After I hope to do the same work on widget-*.xsd files.
        Hide
        David E. Jones added a comment -

        Thanks Jacques, the simple-methods.xsd.patch file is now in place.

        I did a bit of random checking throughout the changes and what I saw looks just fine. The commit is in SVN rev 524533.

        Show
        David E. Jones added a comment - Thanks Jacques, the simple-methods.xsd.patch file is now in place. I did a bit of random checking throughout the changes and what I saw looks just fine. The commit is in SVN rev 524533.
        Hide
        Jacques Le Roux added a comment -

        David,

        Just a reminder, as you were the most involved in this previously. Don't you think this should be commited before the next release (not forgetting the transform part to allow generating doc in the fly) ?

        Do you see any issue in this work ? I may help then of course...

        Show
        Jacques Le Roux added a comment - David, Just a reminder, as you were the most involved in this previously. Don't you think this should be commited before the next release (not forgetting the transform part to allow generating doc in the fly) ? Do you see any issue in this work ? I may help then of course...
        Hide
        Jacques Le Roux added a comment -

        Last review, this is the patch to use.

        BTW I found the tags "Env-name" and "Get-long-only" in Adv. Training Framework that are not in simple-methods.xsd. Not sure what to do about that. Here is the snippet from Adv. Training Framework where I found those informations :

        Env-name is the name of the variable in the environment
        or the context where it will put the sequenced Id.
        By default it puts a string value there.
        Get-long-only will get a numerical long value and put it
        there, so it does not do that by default. By default getlong-
        only is false. If you want it to just get a long number
        then you can set that to true. That's in there for
        supporting lower level functionality, but that's not the
        typical pattern used in OFBiz as we do use strings for
        sequencing.

        Show
        Jacques Le Roux added a comment - Last review, this is the patch to use. BTW I found the tags "Env-name" and "Get-long-only" in Adv. Training Framework that are not in simple-methods.xsd. Not sure what to do about that. Here is the snippet from Adv. Training Framework where I found those informations : Env-name is the name of the variable in the environment or the context where it will put the sequenced Id. By default it puts a string value there. Get-long-only will get a numerical long value and put it there, so it does not do that by default. By default getlong- only is false. If you want it to just get a long number then you can set that to true. That's in there for supporting lower level functionality, but that's not the typical pattern used in OFBiz as we do use strings for sequencing.
        Hide
        Jacques Le Roux added a comment -

        This is the last patch closing simple-methods.xsd documentation effort. I hope nothing is missing, unclear or even false. Anyway its usage is, I suppose, the best to verify it.

        Show
        Jacques Le Roux added a comment - This is the last patch closing simple-methods.xsd documentation effort. I hope nothing is missing, unclear or even false. Anyway its usage is, I suppose, the best to verify it.
        Hide
        Jacques Le Roux added a comment -

        There is a drawback of migrating all operators documentaion in XSD file : the contextuel annotation/documentation mechanism is character limited. Actually this is not really a problem if we use and XSLT (or FTL) transformation to render all documentation included. This means also that we should not restrict ourselves by the number of characters the annotation/documentation mechanism limits to.

        Show
        Jacques Le Roux added a comment - There is a drawback of migrating all operators documentaion in XSD file : the contextuel annotation/documentation mechanism is character limited. Actually this is not really a problem if we use and XSLT (or FTL) transformation to render all documentation included. This means also that we should not restrict ourselves by the number of characters the annotation/documentation mechanism limits to.
        Hide
        David E. Jones added a comment -

        Jacques: the simple-method.xsd.patch file is now in SVN.

        Show
        David E. Jones added a comment - Jacques: the simple-method.xsd.patch file is now in SVN.
        Hide
        Jacques Le Roux added a comment -

        Forgot to put a comment : simple-method.xsd.path... work in progress...

        Show
        Jacques Le Roux added a comment - Forgot to put a comment : simple-method.xsd.path... work in progress...
        Hide
        Jacques Le Roux added a comment -

        Mmm Scott don't panic ;o) I spoke to fast : there is still a bit to go (that I just discovered) ...

        Show
        Jacques Le Roux added a comment - Mmm Scott don't panic ;o) I spoke to fast : there is still a bit to go (that I just discovered) ...
        Hide
        Scott Gray added a comment -

        Here you go Jacques, I haven't looked at this for a while now but hopefully its not too amatuerish

        Show
        Scott Gray added a comment - Here you go Jacques, I haven't looked at this for a while now but hopefully its not too amatuerish
        Hide
        Jacques Le Roux added a comment -

        Scott,

        My work on simple-method.xsd and minilang-guide is almost finished. Would you mind attach your XSLT work ? Because I can't see any effort for the moment in direction of FTL transform.

        Thanks

        Show
        Jacques Le Roux added a comment - Scott, My work on simple-method.xsd and minilang-guide is almost finished. Would you mind attach your XSLT work ? Because I can't see any effort for the moment in direction of FTL transform. Thanks
        Hide
        Jacques Le Roux added a comment -

        I agree, and this could be a good example of doing FTL transform ...

        Show
        Jacques Le Roux added a comment - I agree, and this could be a good example of doing FTL transform ...
        Hide
        Andrew Sykes added a comment -

        Hi,

        This may already have been thought of, but why has no one suggested tying this into webtools and using ftl to do the transformation? Wouldn't that be a more OFBizy way to do things?

        • Andrew
        Show
        Andrew Sykes added a comment - Hi, This may already have been thought of, but why has no one suggested tying this into webtools and using ftl to do the transformation? Wouldn't that be a more OFBizy way to do things? Andrew
        Hide
        Chris Howe added a comment -

        Jacques,

        The eclipse bundle that I downloaded is here:
        http://www-128.ibm.com/developerworks/eclipse/downloads/
        (i did the Enterprise project bundle)

        in case the community wants to endorse one for new comers.

        Show
        Chris Howe added a comment - Jacques, The eclipse bundle that I downloaded is here: http://www-128.ibm.com/developerworks/eclipse/downloads/ (i did the Enterprise project bundle) in case the community wants to endorse one for new comers.
        Hide
        Chris Howe added a comment -

        Thanks Scott,

        Mine is working too. I had been testing it with the <simple-method> tag and nothing comes up for it. But the documentation does pop up for the <if> tag as well as many others. Seems a bit strange.

        Show
        Chris Howe added a comment - Thanks Scott, Mine is working too. I had been testing it with the <simple-method> tag and nothing comes up for it. But the documentation does pop up for the <if> tag as well as many others. Seems a bit strange.
        Hide
        Chris Howe added a comment -

        Scott,

        Could you take a screen shot of it working? I just reinstalled Eclipse with WTP and on my mouse overs of elements that should be getting descriptions, I'm only getting Elements and Content Models.

        Show
        Chris Howe added a comment - Scott, Could you take a screen shot of it working? I just reinstalled Eclipse with WTP and on my mouse overs of elements that should be getting descriptions, I'm only getting Elements and Content Models.
        Hide
        Scott Gray added a comment -

        Hi Jacques

        It's working for me, I'm using Eclipse 3.2 and it started working after I removed XMLBuddy.

        Show
        Scott Gray added a comment - Hi Jacques It's working for me, I'm using Eclipse 3.2 and it started working after I removed XMLBuddy.
        Hide
        Jacques Le Roux added a comment -

        Did someone else than Anil was able to use WTP editor in Eclipse and view documentation ?

        Thanks

        Show
        Jacques Le Roux added a comment - Did someone else than Anil was able to use WTP editor in Eclipse and view documentation ? Thanks
        Hide
        Jacques Le Roux added a comment -

        Yes pretty cool for a start indeed !

        Show
        Jacques Le Roux added a comment - Yes pretty cool for a start indeed !
        Hide
        Jacopo Cappellato added a comment -

        Great work, Scott!!!

        Show
        Jacopo Cappellato added a comment - Great work, Scott!!!
        Hide
        Chris Howe added a comment -

        Very nice start. Could you attach the XSLT? I think the XSLT should be included rather quickly. What do you think? That way more people can add one-on patches as necessary to style it.

        Show
        Chris Howe added a comment - Very nice start. Could you attach the XSLT? I think the XSLT should be included rather quickly. What do you think? That way more people can add one-on patches as necessary to style it.
        Hide
        Scott Gray added a comment -

        Just a quick note to say I'm having great fun with XLST and I've attached where I'm at so far, it's pretty messy but not bad for a first effort me thinks

        Show
        Scott Gray added a comment - Just a quick note to say I'm having great fun with XLST and I've attached where I'm at so far, it's pretty messy but not bad for a first effort me thinks
        Hide
        Jacques Le Roux added a comment -

        Sorry typo: "our part" in place of "one part" above.

        Show
        Jacques Le Roux added a comment - Sorry typo: "our part" in place of "one part" above.
        Hide
        Jacques Le Roux added a comment -

        Anil is using WTP in Eclipse and see documentations. This should solve our part of the problem. Will only remains the need for a tool to format XSD with XSLT/Transform in browsers.

        I asked Anil to post a topic about WTP. I hope he will soon.

        Show
        Jacques Le Roux added a comment - Anil is using WTP in Eclipse and see documentations. This should solve our part of the problem. Will only remains the need for a tool to format XSD with XSLT/Transform in browsers. I asked Anil to post a topic about WTP. I hope he will soon.
        Hide
        Jacques Le Roux added a comment -

        Si,

        I foresee a problem with http://www.opensourcestrategies.com/ofbiz/ofbiz_eclipse.php in your recommendation to use f XMLbuddy as this plugin is not able to deal with XSD annotations/documentation. AFAIK only Oygen is able for the moment.

        BTW this is always a pb for us as Oxygen is not free after 30 days of evaluation

        Thanks

        Show
        Jacques Le Roux added a comment - Si, I foresee a problem with http://www.opensourcestrategies.com/ofbiz/ofbiz_eclipse.php in your recommendation to use f XMLbuddy as this plugin is not able to deal with XSD annotations/documentation. AFAIK only Oygen is able for the moment. BTW this is always a pb for us as Oxygen is not free after 30 days of evaluation Thanks
        Hide
        Jacques Le Roux added a comment -

        I continue my work on XSD annotations takeen from minilang guide (ie delete them in Confluence minilang guide). Of course I will appreciate reviews of this work as it's an important piece of the documentation.

        Thanks

        Show
        Jacques Le Roux added a comment - I continue my work on XSD annotations takeen from minilang guide (ie delete them in Confluence minilang guide). Of course I will appreciate reviews of this work as it's an important piece of the documentation. Thanks
        Hide
        Jacques Le Roux added a comment -

        Yes, XSLT solution seems the smarter indeed. I will continue to update both XSD and HTML (meaning also delete some part of HTML as suggested by David) and I agree with David about not totally eliminate the MiniLang guide because we can't put all stuffes from there in the XSD.

        Show
        Jacques Le Roux added a comment - Yes, XSLT solution seems the smarter indeed. I will continue to update both XSD and HTML (meaning also delete some part of HTML as suggested by David) and I agree with David about not totally eliminate the MiniLang guide because we can't put all stuffes from there in the XSD.
        Hide
        David E. Jones added a comment -

        I think we should continue on the path of an XSLT file to help generate a reference, but in response to Scott's question we still shouldn't totally eliminate the MiniLang guide. It should just be reduced to introductory and overview text, and examples and such. It is only the reference material that should go into the XSD file.

        Show
        David E. Jones added a comment - I think we should continue on the path of an XSLT file to help generate a reference, but in response to Scott's question we still shouldn't totally eliminate the MiniLang guide. It should just be reduced to introductory and overview text, and examples and such. It is only the reference material that should go into the XSD file.
        Hide
        Chris Howe added a comment -

        I don't have time at the moment to work on an xslt for xsd. I know there are some out there, I didn't see one on an initial search that was that great (and even ones that looked promising, licensing wasn't mentioned). It seems the better ones use a generator similar to javadocs to actually produce an html page along with javascript ( xsddoc - http://xframe.sourceforge.net/xsddoc/index.html and another is xs3p - the link is currently dead http://titanium.dstc.edu.au/xml/xs3p/) Both the generators do some pretty work, but fall to the same problem javadoc does in that they actually have to be generated (this is a good solution if someone can keep up with it). Because they're generated there is a possibility for them to be stale. As opposed to a pure xslt stylesheet approach that is just applying a template to a file and will apply no matter how often you change the source.

        For those that would like to play with xslt this extremely brief example should let you get a feeling of how to get started.

        xslt file:

        <?xml version="1.0"?>
        <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"
        exclude-result-prefixes="xs">

        <xsl:output method="html"/>

        <xsl:template match="xs:element[@name]">
        <table border="1" width="100%">
        <tr>
        <td width="25%">
        <xsl:value-of select="@name"/>
        </td>
        <td width="75%">
        <xsl:apply-templates select="xs:annotation"/>
        </td>
        </tr>
        </table>
        </xsl:template>

        </xsl:transform>

        This will do a simple two column table. The first one giving the name of the element, the second one printing out all of the annotations (in most of ofbiz's xsd files this will only be the documentation text). This example does fail slightly as it will print the doucumentation for xs:choices when available, but because xs:choices is not xs:element nothing will print in the first column for that row.

        In your xsd file simply place at the top:

        <?xml version="1.0" encoding="UTF-8"?>
        <?xml-stylesheet type="text/xml" href="available_path_to_your_xslt_file"?>

        I'd be more than happy to help with questions as they come up, but I will not be able to work on a complete solution. I have next to zero artistic ability and too much OCD for any amount of styling to be a small task

        Show
        Chris Howe added a comment - I don't have time at the moment to work on an xslt for xsd. I know there are some out there, I didn't see one on an initial search that was that great (and even ones that looked promising, licensing wasn't mentioned). It seems the better ones use a generator similar to javadocs to actually produce an html page along with javascript ( xsddoc - http://xframe.sourceforge.net/xsddoc/index.html and another is xs3p - the link is currently dead http://titanium.dstc.edu.au/xml/xs3p/ ) Both the generators do some pretty work, but fall to the same problem javadoc does in that they actually have to be generated (this is a good solution if someone can keep up with it). Because they're generated there is a possibility for them to be stale. As opposed to a pure xslt stylesheet approach that is just applying a template to a file and will apply no matter how often you change the source. For those that would like to play with xslt this extremely brief example should let you get a feeling of how to get started. xslt file: <?xml version="1.0"?> <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="xs"> <xsl:output method="html"/> <xsl:template match="xs:element [@name] "> <table border="1" width="100%"> <tr> <td width="25%"> <xsl:value-of select="@name"/> </td> <td width="75%"> <xsl:apply-templates select="xs:annotation"/> </td> </tr> </table> </xsl:template> </xsl:transform> This will do a simple two column table. The first one giving the name of the element, the second one printing out all of the annotations (in most of ofbiz's xsd files this will only be the documentation text). This example does fail slightly as it will print the doucumentation for xs:choices when available, but because xs:choices is not xs:element nothing will print in the first column for that row. In your xsd file simply place at the top: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xml" href="available_path_to_your_xslt_file"?> I'd be more than happy to help with questions as they come up, but I will not be able to work on a complete solution. I have next to zero artistic ability and too much OCD for any amount of styling to be a small task
        Hide
        Scott Gray added a comment -

        Hi Jacques

        I like Chris and David's ideas about using XSLT, so do you think we should discard this page?

        Show
        Scott Gray added a comment - Hi Jacques I like Chris and David's ideas about using XSLT, so do you think we should discard this page?
        Hide
        Jacques Le Roux added a comment -

        Scott,

        I made some modifications in http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide, still a work in progress...

        Show
        Jacques Le Roux added a comment - Scott, I made some modifications in http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide , still a work in progress...
        Hide
        Jacques Le Roux added a comment -

        I have commited in revision 491819 a 1st step to let know that I take care of documentation in simple-method.xsd. I tested locally, seems fine.

        BTW this thread http://www.nabble.com/Re%3A-svn-commit%3A-r491626---in--ofbiz-site%3A-documents.html-dtds--tf2905413.html#a8117889 seems to have closed the discussion above about how to deal with documentations such as minlang doc (best viewed chronogically)

        Thanks to all

        Show
        Jacques Le Roux added a comment - I have commited in revision 491819 a 1st step to let know that I take care of documentation in simple-method.xsd. I tested locally, seems fine. BTW this thread http://www.nabble.com/Re%3A-svn-commit%3A-r491626---in--ofbiz-site%3A-documents.html-dtds--tf2905413.html#a8117889 seems to have closed the discussion above about how to deal with documentations such as minlang doc (best viewed chronogically) Thanks to all
        Hide
        Jacques Le Roux added a comment -

        Great Scott,

        Our posts did cross. I already subscribed to viewVC users ML, I will sure unsubscribe, already enough mails ;o)

        Thanks for your help.

        Show
        Jacques Le Roux added a comment - Great Scott, Our posts did cross. I already subscribed to viewVC users ML, I will sure unsubscribe, already enough mails ;o) Thanks for your help.
        Hide
        Jacopo Cappellato added a comment -

        Jacques,

        I think that Scott's suggestion will do the trick for now (i.e. using the http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=HEAD link).

        Thanks to both of you for your help, I've committed the modified links in rev. 491626

        Show
        Jacopo Cappellato added a comment - Jacques, I think that Scott's suggestion will do the trick for now (i.e. using the http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=HEAD link). Thanks to both of you for your help, I've committed the modified links in rev. 491626
        Hide
        Jacques Le Roux added a comment -

        Jacopo,

        I will ask viewVC users ML if there is solution to view last version (and not a number) and if not ask for enhancement... will see...

        Show
        Jacques Le Roux added a comment - Jacopo, I will ask viewVC users ML if there is solution to view last version (and not a number) and if not ask for enhancement... will see...
        Hide
        Jacques Le Roux added a comment -

        Scott,

        I saw your work, quite impressive. Of course if we keep it there we will have to update it. For instance
        . there is no more an ofbiz/core/docs/xmldefs/ofbiz/simple-methods.dtd file (hence my comment just above).
        . env-to-field
        field-to-env
        string-to-field
        field-to-field
        env-to-env are deprecated and no more used in OFBiz (see my comment above)

        I thought a bit about that. IMHO it's better to have only one source of information (more reliable, because things change) and I finally agree with the ones that think that this source should be in XSD files. But for that we have to find an universal tool usable by everyone. Even if we don't use it because we prefer our proper tool (Oxygen being a good but not free candidate here). If we can't find and recommend a tool like this it will be difficult for newbies to apprehend the minlang and such specif using XSD documentations.

        My 2 cents ;o)

        Show
        Jacques Le Roux added a comment - Scott, I saw your work, quite impressive. Of course if we keep it there we will have to update it. For instance . there is no more an ofbiz/core/docs/xmldefs/ofbiz/simple-methods.dtd file (hence my comment just above). . env-to-field field-to-env string-to-field field-to-field env-to-env are deprecated and no more used in OFBiz (see my comment above) I thought a bit about that. IMHO it's better to have only one source of information (more reliable, because things change) and I finally agree with the ones that think that this source should be in XSD files. But for that we have to find an universal tool usable by everyone. Even if we don't use it because we prefer our proper tool (Oxygen being a good but not free candidate here). If we can't find and recommend a tool like this it will be difficult for newbies to apprehend the minlang and such specif using XSD documentations. My 2 cents ;o)
        Hide
        Scott Gray added a comment -

        Hi Jacques

        You can just use revision=HEAD like:
        http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=HEAD
        to keep up to date.

        Show
        Scott Gray added a comment - Hi Jacques You can just use revision=HEAD like: http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=HEAD to keep up to date.
        Hide
        Jacques Le Roux added a comment -

        Jacopo,

        To refer to XSD files we may use something like this

        http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=490457

        But we will have to update the link when the file change

        Show
        Jacques Le Roux added a comment - Jacopo, To refer to XSD files we may use something like this http://svn.apache.org/viewvc/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd?revision=490457 But we will have to update the link when the file change
        Hide
        Scott Gray added a comment -

        Hi Jacques, David

        The work I have begun is here: http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide

        But personally I would prefer to have the guide remain in the docs, even if I have to maintain it in the wiki section. Jacques, if you want to take the introduction from this page that's fine but please create a new page rather than deleting the work I have done on the rest of the guide.

        Also if you guys decide to keep the full guide in OFBTECH then please don't move it until I have finished tidying it up.

        Thanks
        Scott

        Show
        Scott Gray added a comment - Hi Jacques, David The work I have begun is here: http://docs.ofbiz.org/display/OFBIZ/Mini-Language+Guide But personally I would prefer to have the guide remain in the docs, even if I have to maintain it in the wiki section. Jacques, if you want to take the introduction from this page that's fine but please create a new page rather than deleting the work I have done on the rest of the guide. Also if you guys decide to keep the full guide in OFBTECH then please don't move it until I have finished tidying it up. Thanks Scott
        Hide
        Jacques Le Roux added a comment -

        I put here the same comment than in http://issues.apache.org/jira/browse/OFBIZ-402#action_12461623 to keep things clear :

        I just checked before moving annotations
        from
        http://incubator.apache.org/ofbiz/docs/minilang.html
        to
        http://svn.apache.org/repos/asf/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd

        There are no more any
        env-to-field
        field-to-env
        string-to-field
        field-to-field
        env-to-env
        used in *.xml files of OFBiz but some commented snippets that seems unused and should be perhaps removed.

        Scott, Im' ready to help on this topic (ie moving annotations to simple-methods.xsd). Please let me know what you have already done, thanks.
        If you have not already began I propose that you move only the introductory part as usggested by David https://issues.apache.org/jira/browse/OFBIZ-571#action_12461449 and I will take of the annotations. Thanks to let me know.

        Show
        Jacques Le Roux added a comment - I put here the same comment than in http://issues.apache.org/jira/browse/OFBIZ-402#action_12461623 to keep things clear : I just checked before moving annotations from http://incubator.apache.org/ofbiz/docs/minilang.html to http://svn.apache.org/repos/asf/ofbiz/trunk/framework/minilang/dtd/simple-methods.xsd There are no more any env-to-field field-to-env string-to-field field-to-field env-to-env used in *.xml files of OFBiz but some commented snippets that seems unused and should be perhaps removed. Scott, Im' ready to help on this topic (ie moving annotations to simple-methods.xsd). Please let me know what you have already done, thanks. If you have not already began I propose that you move only the introductory part as usggested by David https://issues.apache.org/jira/browse/OFBIZ-571#action_12461449 and I will take of the annotations. Thanks to let me know.
        Hide
        Chris Howe added a comment -

        By reading this bug report, it should be in WTP:

        https://bugs.eclipse.org/bugs/show_bug.cgi?id=118425

        I have yet been able get it to work though. I'm using 2.0 M3 and the bug report alludes that a certain part of it was fixed in 1.5. I will play some more and report back if it ends up working

        Show
        Chris Howe added a comment - By reading this bug report, it should be in WTP: https://bugs.eclipse.org/bugs/show_bug.cgi?id=118425 I have yet been able get it to work though. I'm using 2.0 M3 and the bug report alludes that a certain part of it was fixed in 1.5. I will play some more and report back if it ends up working
        Hide
        Jacques Le Roux added a comment -

        I found this old issue by chance OFBIZ-90. In 1st comment I was talking about semantic missing in "Oxygen popup annotations". But now that I have reloaded (with another email ;o) Oxygen I can see the documentation associated with the tokens and it fills the gap. But really I find their professionnal licence expansive (US$ 225).

        Show
        Jacques Le Roux added a comment - I found this old issue by chance OFBIZ-90 . In 1st comment I was talking about semantic missing in "Oxygen popup annotations". But now that I have reloaded (with another email ;o) Oxygen I can see the documentation associated with the tokens and it fills the gap. But really I find their professionnal licence expansive (US$ 225).
        Hide
        Jacques Le Roux added a comment -

        Chris,

        After your comment I dowloaded WTP. I had already WTP in (actually saying "WST XML UI" in Manage Configuration) but was unable to use it (XML editor hangs). Also have a message saying "XML editor (locked by content type)" in the editor associations preferences. So Googled for it and find something explaining that I have to dowload all the stuff (argh 210 Mo...).
        So I will not use it, though perhaps I will try, I'm too curious

        Thanks for your suggestion but it's too complicated so I tried with simple-method token which have a documentation (and actually my concern here is more for simple-methods.xsd) . I'm now sure that IntelliJ is not working properly with XML documentation during completion : same message than above while there is a documentation for this token in simple-methods.xsd.

        Conclusion of my searches about IDE or IDE/plugins couples aware of documentation during XML completion :

        Eclipse 3.2/plugins
        XMLBuddy : not
        WTP : not
        Oxygen : yes

        Netbeans 5.5 : not (but I'm not a specialist, perhaps there are plugins ?)

        IntelliJ 6.02 : not (but I'm not a specialist, perhaps there are plugins ?)

        So it seems that for now we must only relay on Eclipse 3.2/Oxygen for functionnality. Moreover it cost at least US$ 64(temporary promo to US$ 48 apart).

        So what people think about all that ? Are we sure that we must constraint people to use this tools (Eclipse/Oxygen) ?
        Of course if in the future maybe some enhancement will be found for this in IDE or plugins but today that's the situation. I will be happy to be corrected of course...

        I thing that this is really important, please give your opinions or advices.

        Thanks

        Show
        Jacques Le Roux added a comment - Chris, After your comment I dowloaded WTP. I had already WTP in (actually saying "WST XML UI" in Manage Configuration) but was unable to use it (XML editor hangs). Also have a message saying "XML editor (locked by content type)" in the editor associations preferences. So Googled for it and find something explaining that I have to dowload all the stuff (argh 210 Mo...). So I will not use it, though perhaps I will try, I'm too curious Thanks for your suggestion but it's too complicated so I tried with simple-method token which have a documentation (and actually my concern here is more for simple-methods.xsd) . I'm now sure that IntelliJ is not working properly with XML documentation during completion : same message than above while there is a documentation for this token in simple-methods.xsd. Conclusion of my searches about IDE or IDE/plugins couples aware of documentation during XML completion : Eclipse 3.2/plugins XMLBuddy : not WTP : not Oxygen : yes Netbeans 5.5 : not (but I'm not a specialist, perhaps there are plugins ?) IntelliJ 6.02 : not (but I'm not a specialist, perhaps there are plugins ?) So it seems that for now we must only relay on Eclipse 3.2/Oxygen for functionnality. Moreover it cost at least US$ 64(temporary promo to US$ 48 apart). So what people think about all that ? Are we sure that we must constraint people to use this tools (Eclipse/Oxygen) ? Of course if in the future maybe some enhancement will be found for this in IDE or plugins but today that's the situation. I will be happy to be corrected of course... I thing that this is really important, please give your opinions or advices. Thanks
        Hide
        Chris Howe added a comment -

        make that the list-name attribute <form list-name="">. For the type the annotation is on the constraint and not on the attribute

        Show
        Chris Howe added a comment - make that the list-name attribute <form list-name="">. For the type the annotation is on the constraint and not on the attribute
        Hide
        Chris Howe added a comment -

        After seeing your screenshot, WTP either doesn't support annotations or I don't have it configured properly. It does show the content model though. However, you may try your screenshot for an element that has an annotation. "actions" in the form widget doesn't have any documentation for it to find. You may want to try the type attribute from the form element (ie <form type="single">) to see if your editor supports it.

        Show
        Chris Howe added a comment - After seeing your screenshot, WTP either doesn't support annotations or I don't have it configured properly. It does show the content model though. However, you may try your screenshot for an element that has an annotation. "actions" in the form widget doesn't have any documentation for it to find. You may want to try the type attribute from the form element (ie <form type="single">) to see if your editor supports it.
        Hide
        Jacques Le Roux added a comment -

        Thanks Chris I will try !

        A little bit disapointed with IntelliJ because does not seem to support annotations. The most I achieved may be seen in attached screencopy.

        Show
        Jacques Le Roux added a comment - Thanks Chris I will try ! A little bit disapointed with IntelliJ because does not seem to support annotations. The most I achieved may be seen in attached screencopy.
        Hide
        Chris Howe added a comment -

        There is a free editor available for eclipse that does offer annotations. I believe I'm using the WTP (Web Tools Platform) XML Editor, but I cannot be certain since it only lists itself as "XML Editor". It was bundled with one of the Callisto custom distributions.

        Show
        Chris Howe added a comment - There is a free editor available for eclipse that does offer annotations. I believe I'm using the WTP (Web Tools Platform) XML Editor, but I cannot be certain since it only lists itself as "XML Editor". It was bundled with one of the Callisto custom distributions.
        Hide
        Jacques Le Roux added a comment -

        OK, I see now that I was no the 1st to ask this question (http://lists.ofbiz.org/pipermail/users/2006-January/009966.html) and that there is already a response. Perhaps we may promote Oxygen as a 1st step. IntelliJ seems to deal with annotations, don't know for other environnements (mostly NetBeans I guess). It's only US$ 64(48 with promotion theses days) for personnal use and is not too expansive for a professionnal.

        WDYT ?

        Show
        Jacques Le Roux added a comment - OK, I see now that I was no the 1st to ask this question ( http://lists.ofbiz.org/pipermail/users/2006-January/009966.html ) and that there is already a response. Perhaps we may promote Oxygen as a 1st step. IntelliJ seems to deal with annotations, don't know for other environnements (mostly NetBeans I guess). It's only US$ 64(48 with promotion theses days) for personnal use and is not too expansive for a professionnal. WDYT ?
        Hide
        Jacques Le Roux added a comment -

        Comment about https://issues.apache.org/jira/browse/OFBIZ-571#action_12461462

        David,

        I see know how Oxygen is showing annotations (I'm looking at the advanced framework at end of widget fields) and this is surely great (and I hope/suppose that it's the same with a tool like IntelliJ) but for a newbie who will surely use a free tool (ie here mostly XMLBuddy in Eclipse for instance) there are no annotations poping up. I tried also in NetBeans 5.5 and it seems that there also a plugin is needed (got "no suggestions" by default). I don't know what to think now... But I'm sure that's this is something important !

        Show
        Jacques Le Roux added a comment - Comment about https://issues.apache.org/jira/browse/OFBIZ-571#action_12461462 David, I see know how Oxygen is showing annotations (I'm looking at the advanced framework at end of widget fields) and this is surely great (and I hope/suppose that it's the same with a tool like IntelliJ) but for a newbie who will surely use a free tool (ie here mostly XMLBuddy in Eclipse for instance) there are no annotations poping up. I tried also in NetBeans 5.5 and it seems that there also a plugin is needed (got "no suggestions" by default). I don't know what to think now... But I'm sure that's this is something important !
        Hide
        Jacques Le Roux added a comment -

        Jacopo,

        Yes I agree a reference should be sufficient if we can find/create a tool that we may recommend to newbies for them experiencing the documentation in XSD format ... I look forward for a such tool :o)

        What adavantages do you see for documentation users by keeping the doc in XSD ? Of course here I do not consider advantages for documentation authors, IMHO this is secondary ;o)

        For a tool to be used/spread I believe that it have to have a real good documentation even if I agree with you that in the case of OFBiz it's simply just not enough !

        If we can keep the way to have a functionnal and a technic documentation this will also ease newbies experience with OFBiz (I know what I'm talking about ;o)

        Show
        Jacques Le Roux added a comment - Jacopo, Yes I agree a reference should be sufficient if we can find/create a tool that we may recommend to newbies for them experiencing the documentation in XSD format ... I look forward for a such tool :o) What adavantages do you see for documentation users by keeping the doc in XSD ? Of course here I do not consider advantages for documentation authors, IMHO this is secondary ;o) For a tool to be used/spread I believe that it have to have a real good documentation even if I agree with you that in the case of OFBiz it's simply just not enough ! If we can keep the way to have a functionnal and a technic documentation this will also ease newbies experience with OFBiz (I know what I'm talking about ;o)
        Hide
        Jacopo Cappellato added a comment -

        Jacques,

        I see what you mean.
        In my opinion keeping the documentation inside the xsd definition has many advantages, but I agree with you that right now it is not very user friendly.
        I think that someone with good scripting skills (perl?) could easily write some scripts to extract the information from xsd and format it in a more human readable way.
        What do you think?

        However, what I was suggesting is that, instead of keeping a copy of the *.xsd under the site directory, it would be easier to reference it directly to the svn site...

        Show
        Jacopo Cappellato added a comment - Jacques, I see what you mean. In my opinion keeping the documentation inside the xsd definition has many advantages, but I agree with you that right now it is not very user friendly. I think that someone with good scripting skills (perl?) could easily write some scripts to extract the information from xsd and format it in a more human readable way. What do you think? However, what I was suggesting is that, instead of keeping a copy of the *.xsd under the site directory, it would be easier to reference it directly to the svn site...
        Hide
        Jacques Le Roux added a comment -

        Jacopo,

        I tried with Opera and IE 6. Opera does the same than Firefox. IE 6 open the file in a flat view form. But I can't see the point here, my question was about how to render the informations for a newbie. I'm sure you agree that an XSD file is not the top for that ? Except of course if you find a (free ;o) tool that facilitates the vision.

        BTW I have used Visual Studio 2003 .NET last year hence it's the default viewer for XSD files on my machine. So I tried to watch was it's capable of. But even with a "sophisticated" viewer like that (yes Microsoft have some, they even claim to have invented XML ;o) it's really not easy to find/use the documentation inside. I also tried their updated XML Notepad, but I has not notably changed since 1997 (implemented in C# with pretty colors but not much more).

        From my POV it should be better to have all the doc in a more standard form than XSD. And even better to have the doc in a sole format. Confluence seems good to me in this aspect.

        WDYT ?

        Show
        Jacques Le Roux added a comment - Jacopo, I tried with Opera and IE 6. Opera does the same than Firefox. IE 6 open the file in a flat view form. But I can't see the point here, my question was about how to render the informations for a newbie. I'm sure you agree that an XSD file is not the top for that ? Except of course if you find a (free ;o) tool that facilitates the vision. BTW I have used Visual Studio 2003 .NET last year hence it's the default viewer for XSD files on my machine. So I tried to watch was it's capable of. But even with a "sophisticated" viewer like that (yes Microsoft have some, they even claim to have invented XML ;o) it's really not easy to find/use the documentation inside. I also tried their updated XML Notepad, but I has not notably changed since 1997 (implemented in C# with pretty colors but not much more). From my POV it should be better to have all the doc in a more standard form than XSD. And even better to have the doc in a sole format. Confluence seems good to me in this aspect. WDYT ?
        Hide
        Jacopo Cappellato added a comment -

        One idea about the links to the xsd files that are in the documents.html page: what about using direct links to the svn server like this one

        http://svn.apache.org/repos/asf/ofbiz/trunk/framework/base/dtd/ofbiz-containers.xsd

        ?

        The only small issue I see is that my browser (Firefox) asks me to download the file instead of showing it on screen... but maybe we can find a workaround for this.

        Show
        Jacopo Cappellato added a comment - One idea about the links to the xsd files that are in the documents.html page: what about using direct links to the svn server like this one http://svn.apache.org/repos/asf/ofbiz/trunk/framework/base/dtd/ofbiz-containers.xsd ? The only small issue I see is that my browser (Firefox) asks me to download the file instead of showing it on screen... but maybe we can find a workaround for this.
        Hide
        Jacques Le Roux added a comment -

        David,

        I will take some time to look and think about this because even if I agree that annotations should be placed in an unique place I'm not sure that the right place for this is ans XSD file. Perhaps I'm missing something here but it seems to me that it's really easier to look at a doc like the old one for a newbie (and generaly docs are for newbies ;o) than to search annotations in an XSD file. What I'm missing is only perhaps a way of using XML editor because completion is not doing it there, am'I wrong ? At least XML Buddy is not helping me a lot here, maybe Oxygen or IntelliJ(plugin?) are ?

        Thanks for comment !

        Show
        Jacques Le Roux added a comment - David, I will take some time to look and think about this because even if I agree that annotations should be placed in an unique place I'm not sure that the right place for this is ans XSD file. Perhaps I'm missing something here but it seems to me that it's really easier to look at a doc like the old one for a newbie (and generaly docs are for newbies ;o) than to search annotations in an XSD file. What I'm missing is only perhaps a way of using XML editor because completion is not doing it there, am'I wrong ? At least XML Buddy is not helping me a lot here, maybe Oxygen or IntelliJ(plugin?) are ? Thanks for comment !
        Hide
        David E. Jones added a comment -

        Just an FYI: MiniLang Guide final resting place has been discussed a number of times but only very little progress has been made toward the decided end. The introductory parts of it should be moved to the Confluence server, but ALL of the reference bits for the various operations and such should be moved to annotations in the simple-methods.xsd file. The newer items have been added there (the XSD file) instead of in the MiniLang Guide, and it would be nice to get it all moved over so it's in one place again, and in a place that's natural to use in an XML editor.

        Show
        David E. Jones added a comment - Just an FYI: MiniLang Guide final resting place has been discussed a number of times but only very little progress has been made toward the decided end. The introductory parts of it should be moved to the Confluence server, but ALL of the reference bits for the various operations and such should be moved to annotations in the simple-methods.xsd file. The newer items have been added there (the XSD file) instead of in the MiniLang Guide, and it would be nice to get it all moved over so it's in one place again, and in a place that's natural to use in an XML editor.
        Hide
        Jacques Le Roux added a comment -

        Scott,

        I forgot to mention that I will take the relay. So please let me know when you have finished this task

        Thanks

        Show
        Jacques Le Roux added a comment - Scott, I forgot to mention that I will take the relay. So please let me know when you have finished this task Thanks
        Hide
        Jacques Le Roux added a comment -

        OK, thanks

        Show
        Jacques Le Roux added a comment - OK, thanks
        Hide
        Scott Gray added a comment -

        While that certainly needs to be done, I'm not familiar enough with minilang to do it. At this stage I'll just get the doc migrated then someone who knows more about it can update the page

        Show
        Scott Gray added a comment - While that certainly needs to be done, I'm not familiar enough with minilang to do it. At this stage I'll just get the doc migrated then someone who knows more about it can update the page
        Hide
        Jacques Le Roux added a comment -

        Scott,

        Have you thought about notifying deprecated ops ("env-..." for instance) and adding new ones ("set" for instance) ?

        Thanks

        Show
        Jacques Le Roux added a comment - Scott, Have you thought about notifying deprecated ops ("env-..." for instance) and adding new ones ("set" for instance) ? Thanks
        Hide
        Scott Gray added a comment -

        Hi Jacopo

        I'm working on moving the minilang guide at the moment, I'll let you know when I'm done.

        Regards
        Scott

        Show
        Scott Gray added a comment - Hi Jacopo I'm working on moving the minilang guide at the moment, I'll let you know when I'm done. Regards Scott

          People

          • Assignee:
            Jacques Le Roux
            Reporter:
            Jacopo Cappellato
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development