You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Michael Schmalle <ap...@teotigraphix.com> on 2012/09/13 20:32:38 UTC
Falcon :: ASDoc porting or re-explore
This question is probably for Gordon but, if I was to start coding
asdoc implementation, where would I start?
I understand what is going on but this is a huge step for me and I
don't want to waste any time working on something that was
ridiculously in the wrong direction.
So, when the wiki says work on asdoc impl, are we talking about
porting the old asdoc algorithms to work with the new AST model or if
there are better ways to implement asdoc explore them?
I'm new to this whole get a major feature started but, any "mentor"
advice would be greatly appreciated.
Mike
--
Michael Schmalle - Teoti Graphix, LLC
http://www.teotigraphix.com
http://blog.teotigraphix.com
RE: Falcon :: ASDoc porting or re-explore
Posted by Michael Schmalle <ap...@teotigraphix.com>.
Basically, what I had created was a renderer abstractly that used
factories to create various render formats.
All I used was the AST produced by the parser, classes that managed
access into the code model and then a rendering layer that output html
using Velocity templates and java class builders.
For instance a Java class was made like ClassList extends ASDocTemplateBase.
There was a renderer with public api like returnLink()
returnEventTable() etc. The concrete implementation of these classes
were based on "what" they rendered. So you could have one render model
that could produce HTML, PDF or any other type of output you wanted.
All you would need to do is reimplement the renderer and converter API
for a new output.
I might actually just move along with this idea since it could totally
exist outside the framework that would make it point specific. If
Adobe decides to donate, fine if not I won't have wasted any time,
since I will have an application that uses the compiler as a module.
Anyway, I'm going to think about this more.
Mike
Quoting Gordon Smith <go...@adobe.com>:
> Recently the Flash Builder team has decided to add ASDoc support to
> the new compiler. I'll find out whether Adobe is willing to donate
> this work when it is complete. (In general, Adobe is NOT committed
> to donating future work on the compiler.) If so, it might not make
> sense for us to do it. They will be producing the DITA XML format
> that goes into SWCs. How that gets would turned into HTML might be
> up to us.
>
> - Gordon
>
>
> -----Original Message-----
> From: Michael Schmalle [mailto:apache@teotigraphix.com]
> Sent: Thursday, September 13, 2012 11:33 AM
> To: flex-dev@incubator.apache.org
> Subject: Falcon :: ASDoc porting or re-explore
>
> This question is probably for Gordon but, if I was to start coding
> asdoc implementation, where would I start?
>
> I understand what is going on but this is a huge step for me and I
> don't want to waste any time working on something that was
> ridiculously in the wrong direction.
>
> So, when the wiki says work on asdoc impl, are we talking about
> porting the old asdoc algorithms to work with the new AST model or
> if there are better ways to implement asdoc explore them?
>
> I'm new to this whole get a major feature started but, any "mentor"
> advice would be greatly appreciated.
>
> Mike
>
> --
> Michael Schmalle - Teoti Graphix, LLC
> http://www.teotigraphix.com
> http://blog.teotigraphix.com
>
>
--
Michael Schmalle - Teoti Graphix, LLC
http://www.teotigraphix.com
http://blog.teotigraphix.com
RE: Falcon :: ASDoc porting or re-explore
Posted by Gordon Smith <go...@adobe.com>.
Recently the Flash Builder team has decided to add ASDoc support to the new compiler. I'll find out whether Adobe is willing to donate this work when it is complete. (In general, Adobe is NOT committed to donating future work on the compiler.) If so, it might not make sense for us to do it. They will be producing the DITA XML format that goes into SWCs. How that gets would turned into HTML might be up to us.
- Gordon
-----Original Message-----
From: Michael Schmalle [mailto:apache@teotigraphix.com]
Sent: Thursday, September 13, 2012 11:33 AM
To: flex-dev@incubator.apache.org
Subject: Falcon :: ASDoc porting or re-explore
This question is probably for Gordon but, if I was to start coding asdoc implementation, where would I start?
I understand what is going on but this is a huge step for me and I don't want to waste any time working on something that was ridiculously in the wrong direction.
So, when the wiki says work on asdoc impl, are we talking about porting the old asdoc algorithms to work with the new AST model or if there are better ways to implement asdoc explore them?
I'm new to this whole get a major feature started but, any "mentor"
advice would be greatly appreciated.
Mike
--
Michael Schmalle - Teoti Graphix, LLC
http://www.teotigraphix.com
http://blog.teotigraphix.com
Re: Falcon :: ASDoc porting or re-explore
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
Also something to note that in the current generation of the ASDocs some of the HTML is modified via Java so it's not a pure XSLT solution.
Justin
Re: Falcon :: ASDoc porting or re-explore
Posted by Justin Mclean <ju...@classsoftware.com>.
HI,
> I am not sure how fast XSLT is
It's slow, very slow. I made a few changed to ASDoc to document private methods, properties and mark new Apache Flex methods and properties with a little Apache Flex logo. It takes about an hour to produce all the docs.
>>> I am sure this community has folks who can handle XSLT?
In the above process I had to make quite a few changes to the XSLT templates, they are not easy or pleasant to work with.
The current ASDoc compiler can generate the docs in XML format (obviously) and that reasonably fast. It shouldn't be too hard to take something that can use that XML and formatting it that simpler than the existing XSLT templates.
Anyone have experience with Apache Cocoon?
Thanks,
Justin
Re: Falcon :: ASDoc porting or re-explore
Posted by Om <bi...@gmail.com>.
On Thu, Sep 13, 2012 at 12:42 PM, Alex Harui <ah...@adobe.com> wrote:
>
> On 9/13/12 12:27 PM, "Om" <bi...@gmail.com> wrote:
>
>
> >>
> > I believe that making an AIR app for this would cause problems with
> > continuous integration or build bots. XSLT can be invoked via ant and
> can
> > be run anywhere.
> I've used AIR apps in shell scripts. I haven't tried it in Ant, but I
> don't
> know why it wouldn't work. I'd be ok with writing an ASDoc generator in
> Java as well.
>
That would tie the ASDoc generator to Windows and Macs. I dont think
Falcon has (yet) this restriction. I would rather that we dont add this
requirement now. Unless we can restrict the generator to use just AIR 2
features.
>
> > Moreover, I am not sure if we do, but if we are handling large amounts
> of
> > text/strings, we should probably avoid AIR.
> Is XSLT that much faster? IIRC, the ASDoc build takes a while.
> >
>
I am not sure how fast XSLT is, but string manipulation sucks up a lot of
memory in AIR/Flash Player. Which in turns drags down performance.
> > I am sure this community has folks who can handle XSLT?
> I'm sure it does, and I'm sure I could eventually figure it out, but it
> would allow for wider participation.
> >
>
I agree. It makes sense to do it in a language that most people are
familiar with here. But my above points about AIR still holds good.
> > Thanks,
> > Om
>
> --
> Alex Harui
> Flex SDK Team
> Adobe Systems, Inc.
> http://blogs.adobe.com/aharui
>
>
Re: Falcon :: ASDoc porting or re-explore
Posted by Alex Harui <ah...@adobe.com>.
On 9/13/12 12:27 PM, "Om" <bi...@gmail.com> wrote:
>>
> I believe that making an AIR app for this would cause problems with
> continuous integration or build bots. XSLT can be invoked via ant and can
> be run anywhere.
I've used AIR apps in shell scripts. I haven't tried it in Ant, but I don't
know why it wouldn't work. I'd be ok with writing an ASDoc generator in
Java as well.
>
> Moreover, I am not sure if we do, but if we are handling large amounts of
> text/strings, we should probably avoid AIR.
Is XSLT that much faster? IIRC, the ASDoc build takes a while.
>
> I am sure this community has folks who can handle XSLT?
I'm sure it does, and I'm sure I could eventually figure it out, but it
would allow for wider participation.
>
> Thanks,
> Om
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui
Re: Falcon :: ASDoc porting or re-explore
Posted by Om <bi...@gmail.com>.
On Thu, Sep 13, 2012 at 12:19 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
>
> On 9/13/12 11:32 AM, "Michael Schmalle" <ap...@teotigraphix.com> wrote:
>
>
> >
> > So, when the wiki says work on asdoc impl, are we talking about
> > porting the old asdoc algorithms to work with the new AST model or if
> > there are better ways to implement asdoc explore them?
> >
> Just my opinion, but what I don't like about the current ASDoc
> implementation is that it relies on XSLT. It seems like we could write an
> AIR app to assemble the doc. Then it would be maintainable and upgradeable
> by many more folks in this community.
>
> --
> Alex Harui
> Flex SDK Team
> Adobe Systems, Inc.
> http://blogs.adobe.com/aharui
>
>
I believe that making an AIR app for this would cause problems with
continuous integration or build bots. XSLT can be invoked via ant and can
be run anywhere.
Moreover, I am not sure if we do, but if we are handling large amounts of
text/strings, we should probably avoid AIR.
I am sure this community has folks who can handle XSLT?
Thanks,
Om
Re: Falcon :: ASDoc porting or re-explore
Posted by Michael Schmalle <ap...@teotigraphix.com>.
Hmm, interesting idea I wonder how the "assemble" part works. :)
From my past dealings with AS3 and AST I have a pretty well 3/4 or
more functioning asdoc builder/renderer created in java using Velocity
templates and model classes that complement them (this was from my
earlier ventures in writing as3/mxml parser/dom).
I really don't care for XLST being pushed down a simple users throat
just to change a documents look either. I think this is the main
reason you see the same old stale asdocs just as they were in 2005.
The way I created the templates closely resembles how a Drupal php
template looks. I created very modular pieces that were constructed by
a builder class during the render phase.
Maybe I should just experiment with that approach to see If I could
offer "another" alternative to the XLST templates. EG Velocity
templates.
For now I just have to figure out how to build this compiler and turn the key!
Mike
Quoting Alex Harui <ah...@adobe.com>:
>
>
>
> On 9/13/12 11:32 AM, "Michael Schmalle" <ap...@teotigraphix.com> wrote:
>
>
>>
>> So, when the wiki says work on asdoc impl, are we talking about
>> porting the old asdoc algorithms to work with the new AST model or if
>> there are better ways to implement asdoc explore them?
>>
> Just my opinion, but what I don't like about the current ASDoc
> implementation is that it relies on XSLT. It seems like we could write an
> AIR app to assemble the doc. Then it would be maintainable and upgradeable
> by many more folks in this community.
>
> --
> Alex Harui
> Flex SDK Team
> Adobe Systems, Inc.
> http://blogs.adobe.com/aharui
>
>
--
Michael Schmalle - Teoti Graphix, LLC
http://www.teotigraphix.com
http://blog.teotigraphix.com
Re: Falcon :: ASDoc porting or re-explore
Posted by Alex Harui <ah...@adobe.com>.
On 9/13/12 11:32 AM, "Michael Schmalle" <ap...@teotigraphix.com> wrote:
>
> So, when the wiki says work on asdoc impl, are we talking about
> porting the old asdoc algorithms to work with the new AST model or if
> there are better ways to implement asdoc explore them?
>
Just my opinion, but what I don't like about the current ASDoc
implementation is that it relies on XSLT. It seems like we could write an
AIR app to assemble the doc. Then it would be maintainable and upgradeable
by many more folks in this community.
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui