It looks to me like you are! And each aspect of an open source project needs a champion, such as yourself.
This is a nice effort, and I think you should keep up the good work. Surely there will be other LZX user/programmers who will join in eventually. On 2011-01-13, at 10:31, Raju Bitter wrote: > Looks like no-one is interest in documenting LZX source code. Too bad... > > On Wed, Jan 12, 2011 at 4:54 PM, Raju Bitter < > [email protected]> wrote: > >> I've pushed a first version of a RingoJS JavaScript app to the Git >> repository, which will serve as a base for the LZX documentation tool, I'm >> building as part of the KamiJS project: >> https://github.com/kamiJS/lzxdoctool/blob/master/lzxdoc.js >> >> I can already parse the LZX files of the demo applications for a list of >> all LZX files which belong to the application, generating an array with path >> information for each LZX file, and a marker showing if it's an LPS component >> LZX file or a custom LZX file. >> >> Running ringo lzxdoc.js -h gives you the options: >> >>> ringo:lzxdoctool raju$ ringo lzxdoc.js -h >> >> Please specify your applications main LZX file using the -a option, e.g. >>> '-a main.lzx' >> >> Available options: >> >> -a --app lzxfile The main LZX file of the application >> >> -v --verbose Turn verbose logging on >> >> -h --help Show this help message >> >> >> Example list of files generated for LzPix: >> ringo ~/src/git/kamijs/lzxdoctool/lzxdoc.js -a app.lzx >> List of LZX files for this app: >> 1: app.lzx >> 2: views/details.lzx >> 3: classes/albumlayout.lzx >> 4: classes/pivotlayout.lzx >> 5: classes/photo.lzx >> 6: classes/photocollection.lzx >> 7: classes/clipboard.lzx >> 8: classes/favorites.lzx >> 9: classes/search.lzx >> 10: classes/photocollection.lzx >> 11: classes/draggedphotos.lzx >> 12: classes/dataman.lzx >> 13: classes/spinner.lzx >> 14: views/mybutton.lzx >> 15: classes/../views/mybutton.lzx >> 16: classes/linkbutton.lzx >> 17: resources.lzx >> 18: views/tools.lzx >> 19: views/error.lzx >> >> And the same for the calendar demo, which used some LPS components: >> ringo ~/src/git/kamijs/lzxdoctool/lzxdoc.js -a calendar.lzx >> List of LZX files for this app: >> 1: calendar.lzx >> 2: resources.lzx >> 3: cal-button.lzx >> 4: lz/scrollbar.lzx >> skipping LPS component lz/scrollbar.lzx >> 5: gridsliderlayout.lzx >> 6: basepanel.lzx >> 7: cal-data.lzx >> 8: event.lzx >> 9: day.lzx >> 10: basepanel.lzx >> 11: base/basetabslider.lzx >> skipping LPS component base/basetabslider.lzx >> 12: textbox.lzx >> 13: infopanel.lzx >> 14: simpletimelayout.lzx >> 15: dayname.lzx >> 16: selected-daylook.lzx >> 17: eventselector.lzx >> 18: loading.lzx >> >> If anyone is interested in working on the XSLT transformation with me, that >> would be cool. If not, I'll probably need 1-2 weeks to finish the tool. >> >> On Tue, Jan 11, 2011 at 12:02 PM, Raju Bitter < >> [email protected]> wrote: >> >>> I'm moving this over to the dev mailing lists, since I have a bunch of >>> questions to the dev team: >>> >>> 1) The general need for a doctool >>> It seems that there is no documentation generation tool available for LZX >>> code as part of the OpenLaszlo platform. I know Webtop has some very basic >>> documentation, which seems to be generated out of the LZX code. How does >>> that work, and will that be part of the OpenLaszlo platform? If not, do you >>> consider a platform with a custom language (LZX) complete - even if you >>> don't provide up-to-date documentation tools? Do you plan to ship up-to-date >>> documentation tools at all with a future releases? The Python script which >>> is available is really simple. It generates simple HTML docs for any LZX >>> class found in any LZX file in defined folders. And there's no official >>> support for that tool. >>> >>> 2) The OpenLaszlo platform documentation vs. documenting custom LZX code >>> Based on my research it appears that the documentation found at >>> http://svn.openlaszlo.org/openlaszlo/trunk/docs/src is currently only >>> used to document the OpenLaszlo LFC classes and component classes shipped >>> with the platform. Has that documentation process ever been used to document >>> custom LZX code, or even one of the demo apps? The stylesheet at >>> http://svn.openlaszlo.org/openlaszlo/trunk/docs/src/xsl/lzx2js2doc.xsl(transforming >>> LZX into j2sdoc format) is not fit to work with custom LZX >>> applications, for some reasons: >>> a) LZX component dependencies (<include href="lz/window.lzx" /> will >>> cause the stylesheet to look for an 'lz' folder relative to the LZX file >>> containing the include). >>> b) Inclusion of a library path (<include href="someFolder" />) will >>> cause the stylesheet to load the directory instead of the contained >>> library.lzx file, causing an exception >>> c) What if the LZX file contains a class written in JavaScript? It's not >>> going to be documented. >>> >>> The lzx2js2doc.xsl transforms LZX into the jsdoc format ( >>> http://wiki.openlaszlo.org/JS2Doc_Conversion). Does it make sense to use >>> js2doc as intermediary format? >>> >>> 3) 3rd party solutions >>> Maybe there's already an existing doctool within the community which could >>> be published as open source. Are you aware of any solutions? Is anyone from >>> the community willing to contribute code, or work on an implementation? >>> There was LazDoc in 2005, but that's totally outdated by now: >>> http://freshmeat.net/projects/lazdoc/ >>> >>> 4) What should be added to the docs? >>> a) classes, attributes, events, methods >>> b) class information (inheritance, mixins) >>> c) stylesheets (internal/external, to give an overview of the styles >>> defined for the app, and where that specific style information can be found) >>> d) resources (list of static resources) >>> >>> What's missing here? How should runtime-specific switch-blocks be handled, >>> where you have different implementations of a class depending on the >>> runtime? >>> >>> Then, it would be good to have a doctool supporting different versions of >>> LZX, since the language evolves so quickly. If you generate the docs, you >>> should have a version switch '--version 4.9'. Many of the larger projects >>> are still using older versions of OpenLaszlo. >>> >>> On Tue, Jan 11, 2011 at 10:08 AM, Raju Bitter < >>> [email protected]> wrote: >>> >>>> The Python script is just scanning through defined lzdirs, picking up any >>>> *.lzx file. I'm working on a RingoJS/Rhino based script now, source code >>>> will be available at https://github.com/kamiJS/lzxdoctool in the next >>>> days. >>>> >>>> >>>> On Fri, Jan 7, 2011 at 11:48 PM, P T Withington <[email protected]> wrote: >>>> >>>>> Pretty sure that you just give it a file and it follows the <include>s >>>>> in the file. That's how the components get documented. (And why they >>>>> fail >>>>> to show up when someone adds a component but does not add it to the >>>>> relevant >>>>> library.lzx so that the doc tool will find it.) >>>>> >>>>> Not a perfect mechanism by any means... >>>>> >>>>> On 2011-01-07, at 17:03, Raju Bitter wrote: >>>>> >>>>>> Which mechanism is used to identify all files which make up one >>>>> application? >>>>>> Does anyone know how I can point to one LZX file and generate a list >>>>> of all >>>>>> other LZX files I'd need to process? >>>>>> >>>>>> On Fri, Jan 7, 2011 at 10:39 PM, Raju Bitter < >>>>>> [email protected]> wrote: >>>>>> >>>>>>> Thanks, Tucker. That's what I guessed, that we have to use the XSLT >>>>>>> transformation. I'm currently looking at this page, let's see how far >>>>> I get >>>>>>> with that. >>>>>>> http://www.openlaszlo.org/lps4.9/docs/developers/doc-toolchain.html >>>>>>> >>>>>>> >>>>>>> On Fri, Jan 7, 2011 at 10:13 PM, P T Withington <[email protected]> >>>>> wrote: >>>>>>> >>>>>>>> Our doc tool maintainer is on sabbatical (:-0). I was able to fix a >>>>> bug >>>>>>>> in the tools by reading the doc doc. It's pretty well written. >>>>>>>> >>>>>>>> Basically OL use a bunch of XSLT to walk over the LZX and output >>>>> something >>>>>>>> that docbook understands and then use docbook to create the final >>>>> doc. >>>>>>>> >>>>>>>> I expect it would be reasonably easy to use the tools on your own >>>>> LZX. >>>>>>>> The complicated stuff is the bit that walks over the LFC JS and >>>>> outputs >>>>>>>> something that the LZX XSLT can parse... >>>>>>>> >>>>>>>> On 2011-01-07, at 16:05, Raju Bitter wrote: >>>>>>>> >>>>>>>>> Guess that means: no new tool available. Besides what's built into >>>>> the >>>>>>>> LPS >>>>>>>>> for generating the OL docs. >>>>>>>>> >>>>>>>>> On Wed, Jan 5, 2011 at 8:33 PM, Raju Bitter < >>>>>>>>> [email protected]> wrote: >>>>>>>>> >>>>>>>>>> What is the recommended tool for generating LZX documentation? The >>>>> wiki >>>>>>>>>> lists the following tools: >>>>>>>>>> http://wiki.openlaszlo.org/Development_Tools#Documentation_Tools >>>>>>>>>> >>>>>>>>>> The page on the LzxdocTool has not been updated since 2007. Does >>>>> that >>>>>>>> still >>>>>>>>>> work with the 4.8 version of OL? >>>>>>>>>> http://wiki.openlaszlo.org/LzxdocTool >>>>>>>>>> >>>>>>>>>> - Raju >>>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>> >>>>> >>>>> >>>> >>> >>
