On Tuesday 03 January 2006 16:54, John Sundman wrote: > I am willing to learn how to create the dguide(s) in Docbook markup. ( > I rather expect it's not much different from what we're using now?)
No it is not that different. Normal rules of XML apply and you will be using a different different set of XML elements. Lucky for us the DTD and XSL are well documented. I think the base resources of our reference will be: * Docbook - The Definitive Guide [http://docbook.org/tdg/en/html/docbook.html] * Docbook - The Complete Guide [http://sagehill.net/docbookxsl/index.html] Most of what we have discussed thus far is discussed in these books. In particular "The Complete Guide" which deals more with the actual publishing process. > I like Sean's comments about repurposing content. That's a problem in > the current implementation; I need to think more about what I would to > see in a solution. (See comments below about different runtimes, one > aspect of this problem.) The modular docbook offers us a solution. It is not that far away from the concept of <library> in LZW, just that it can be done using XInclude or External Entities. [http://sagehill.net/docbookxsl/ModularDoc.html] > > As Jim points out, the reference is a whole different can of worms and > has issues of its own. The Reference is somewhat fragile and is > certainly underdocumented, but when it's working it's a thing of > beauty. I am leery of makng big changes to the Reference at the same > time that we make big changes to the dguides, but perhaps we will need > to do that in order to accomodate the different runtimes. I need to look into the current process using for generating the reference. There are no source files in the reference/ which tells me to look closer to the code and see if the documentation is not auto generated using some other set of tools. It's a bit of a black box from where I am at the moment. However, I am sure there is a way for us to make the development and maintenance easier. There always is. For example, lots of the Element documentation could be derived directly from the lzx.dtd > With regard to the different runtimes, there are two obvious approaches > we to take (and perhaps a few not-so-obvious ones): > > 1 -- Have one universal documentation set for all runtimes, with > information that only pertains to particular runtimes tagged in some > way. The tags could be used to visually distinguish such chunks, and > would also be usable in non-printed (e.g. audio) versions. > > 2 -- Have different doc sets for the various rutimes, that is, have a > documentation set: "OpenLaszlo for Flash (7, 8,9)" and another for > "OpenLaszlo for AJAX", etc. > > Of the above, it's not clear to me which is to be prefered. If you're > developing for only one platform, then you don't care about things for > the others. On the other hand, if' you're aiming to be cross-platform > you would want that info all in one place. So some people will want > (1) and others will want (2). I think the delta between the versions will be large and therefore not worth the extra processing or weight. In which case #1 is the direction. Along with this also comes some common conventions so that we can manage it. Some simple things like, no capturing of desktop environment window frames whenever possible. > > But on the other other hand, if we have the markup in place, then I > suppose we could use a compile-time switch to decide which version to > build. . . Yes.... Once the markup is done, the configuration of a batch transformation to arrive at different results is possible. > > In summary: > > 1) I'm up for this. I'll get a Docbook book and start studying. > 2) I don't think it wise to aim to switching to the new tools for the > Sage release. Too much risk, and furthermore, we need to make sure we > have the right design. > 3) We need an overall plan that addresses: > -- Dguides > -- Reference > -- other stuff (Laszlo explorer sources and examples) > > The plan needs to address how we will handle issues related to the > various runtime targets. Profiling? [http://sagehill.net/docbookxsl/Profiling.html] I may stand corrected, but the reference is likely to be several processing stages and will be built from resources located in two or more sources. -- Sean Wheller Technical Author [EMAIL PROTECTED] +27-84-854-9408 http://www.inwords.co.za _______________________________________________ Laszlo-dev mailing list [email protected] http://www.openlaszlo.org/mailman/listinfo/laszlo-dev
