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