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?)
Schedule wise, I think it makes most sense for me to do my work in
January on the "Sage" (3.2) release using the current methodology as we
work towards the new Docbook-based methodology for 3.3. This would
give us time to do the implementation with proper deliberation, and
would also allow me to learn and test the new markup. The new tools
work should be done in a separate branch set up for that purpose.
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.)
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. Perhaps
Oliver has more to say about this?
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).
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. . .
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.
jrs
On Dec 31, 2005, at 2:12 PM, Sean Wheller wrote:
On Saturday 31 December 2005 20:07, Jim Grandy wrote:
With respect to schedule, the roadmap page on the wiki is up-to-date
(http://wiki.openlaszlo.org/Platform_Roadmap), but doesn't actually
commit to timeframes. My expectation is that we will ship Sage as 3.2
at the end of January, then Ginger as 3.3 some time in Q2 of 2006. We
would absolutely be interested in doc tools changes for either Sage
or Ginger.
Assuming we have myself and some bandwidth distributed across a few
devs at LZ
the January target is doable. If it is just John and I then Ginger is
more
realistic. But we can give it a push and see how we go. Start on a
small, but
complex document.
If you think the changes are likely to be disruptive, we can always
create a branch on svn for the work and integrate back when the
changes have stabilized and we're getting close to a release.
Assuming that John is able to take on the learning curve associated
with the
Docbook DTD and is willing to author directly in Docbook XML.
If John is OK, then the changes are pretty intrusive and we are liable
to
break the build in a few places. I like to commit often, keeps it open
for
comment and on course, then branching for this would be a good idea.
Even if
the timeline is not a problem.
Which brings me to the requirements we need to take into consideration.
I work on Linux (SuSE). I assume that we have people working on all
platforms.
Correct?
If yes, then portability between the platforms for build is important.
What is
your preferred toolchain for processing?
Assuming we want all free, (* preferred)
Ant or GNU Make
Apache Xerces-J 2.7.1
Apache Xalan Java 2.7.0
*SAXON_6 6.5.5
*Apache FOP 0.20.5
OASIS DocBook XML DTD 4.4
DocBook XSL 1.69.1a
There are also (at least) two other changes we have on the roadmap
for doc tools. They are to support the class and type declaration
notations that are in the ECMAScript Release 4 draft spec and in the
ActionScript 3.0 preliminary documentation.
Oh, and we need a way of
marking documentation that is runtime-specific (say for SWF6-8, or
SWF9, or DHTML).
Not sure of the requirement.
a) You want to produce documents for each runtime?
b) Or you want to annotate texts and keep them in the same document?
In the first case, we can do this with docbook profiles. We should be
able to
profile nodes using an attributes such as @condition
At time of processing it is then possible to apply
profile.confition="foo" to
output. But having duplicate copies of docs matching runtimes will be
excessive.
In the second case, more realistic, it would be a simple case of
inserting a
small image or we add a custom layer to the docbook xsl and define
output
results again based on attributes.
Either way we can find a solution ;-)
I assume you have svn setup with the normal tags/ branches/ trunk/
If true, then can I also suggest that documentation for past releases
be
preserved in the tag/
I find that it is always helpful to preserve and make available
documentation
for previous releases as not everyone upgrades to the lastest release
immediately.
Having a rationalized/simplified set of doc tools should make it much
easier to do relatively small tasks like these, so I'm willing to
wait on them until we've emerged out the other side.
Agreed.
Thanks for your response.
--
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
