You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Alex Harui <ah...@adobe.com> on 2016/12/14 17:38:11 UTC
[FLEXJS] ASDoc App
Hi,
Today I finally got enough of a FlexJS ASDoc app running to mention it on
the list, in hope that other folks can pitch in to help us finish it and
help prove that FlexJS can help folks do something useful, as well as make
it easier for folks to write code with FlexJS.
Normally, our ASDoc is published as a pile of HTML files. The regular
Flex MXMLC compiler has code that generates a pile of XML files and then
MXMLC calls into the Saxon library to apply XSLT to generate the HTML.
The Falcon codebase didn't have any of this code, but instead of copying
in the code and the Saxon dependency from flex-sdk, I chose to take a
completely different approach because I think that ASDoc for FlexJS may
need to be more interactive. There are so many more classes that have
different categorizations and different usage contexts that I want to
provide more sophisticated filtering, so users can filter down to, for
instance, "top-level components", or "view beads", etc. This is certainly
possible to do with a pile of HTML, but that would require that I and
anyone else who wants to help to learn or know XSLT. It makes more sense
to me to use ActionScript and MXML instead since everyone in this
community knows that. And turning this into a production-quality app
would force us to develop some new code that other folks will probably
want.
The source code is checked into the flex-asjs repo under
examples\flexjs\ASDoc. The apacheflexbuild CI server will re-build the
ASDoc app on any change to the flex-asjs repo, so you can see your results
here [1][2]. If you run it now, you'll see its pretty ugly. All I wanted
to get working was the ability to parse the underlying JSON files, which I
think is mostly working. It would be great to see folks pitch in to:
-make it look better
-use links for the base classes
-provide an "All classes" and "index"
-provide filters
-localization?
-maven build
-deep linking
-search engine support
And tons of other improvements. Just compare it to the current ASDoc to
see what is missing. My vision for filtering would be to allow folks to
check off a list of attributes that correlate to asdoc tags. We could
annotate all top-level components with @toplevel, and beads with @bead
and/or @viewbead and the app would offer the list of known tags and you
could check which ones you want to see or hide. I'll probably implement
the beginnings of that after I catch up on some other issues, but you
don't have to wait for me.
Hope you can find time to help,
-Alex
[1] SWF version:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
[2] JS Debug:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
Note, the js-release version may not run since the code is currently using
lots of plain objects.
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 1:14 PM, "Justin Mclean" <ju...@classsoftware.com> wrote:
>HI,
>
>> OK, but you have said elsewhere you have little time to contribute.
>
>I actually said that the amount of time I have to contribute to this
>project varies over time. It's currently summer and Xmas holidays here in
>the southern hemisphere from now until mid January. People get a minimum
>of 4 weeks holidays a year here in Australia. [1] Some companies it’s
>more and 10+ days public holidays. I’m also coming up to 4 months long
>service leave.
>
>> What happens if you and Chris are busy or no longer around?
>
>That is the same for anyone working on this project, both Chis and I have
>been working on this project regularly for around 5 years so the risk is
>low. There should also be other people who know some XSLT, it been around
>a while (1999+) [2] and is well supported, for instance all modern
>browsers support XSLT.
Others who know XSLT and can help support its use for ASDoc, please speak
up now. If we don't get more names, then it effectively makes you two
gatekeepers of an important feature, which is, IMO, not a good idea for
any Apache project. People should be able to contribute code and not need
someone else to have it properly documented.
>
>> Let's first discuss this one point: Should FlexJS ASDoc be static HTML
>>or
>> a Rich Internet Application?
>
>Why not both? One use case is will the documentation be available as a
>download and work offline? Another is can I turn it into other formats
>i.e. convert to PDF or to have as a reference on my ebook reader?
>
>> Maybe there is some advantage to static HTML that I don't understand.
>
>Offline viewing, format portability, SEO and search-ability (google
>ranking favours static fast sites and can’t index some dynamic content),
>higher scalability (but that’s a nice problem to have), and usually less
>bandwidth and faster on mobile. But that not to say dynamic sites don’t
>have different advantages.
Aren't all of these issues things that all RIAs need to handle? Or has
static site generation gotten so easy that folks are moving away from
RIAs? An AIR/PhoneGap version of the ASDoc app should handle off-line
viewing. At least with FlexJS each page appears in the browser and many
PDF converters work right from the browser. I thought RIAs were supposed
to result in lower bandwidth.
Thanks,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Justin Mclean <ju...@classsoftware.com>.
HI,
> OK, but you have said elsewhere you have little time to contribute.
I actually said that the amount of time I have to contribute to this project varies over time. It's currently summer and Xmas holidays here in the southern hemisphere from now until mid January. People get a minimum of 4 weeks holidays a year here in Australia. [1] Some companies it’s more and 10+ days public holidays. I’m also coming up to 4 months long service leave.
> What happens if you and Chris are busy or no longer around?
That is the same for anyone working on this project, both Chis and I have been working on this project regularly for around 5 years so the risk is low. There should also be other people who know some XSLT, it been around a while (1999+) [2] and is well supported, for instance all modern browsers support XSLT.
> Let's first discuss this one point: Should FlexJS ASDoc be static HTML or
> a Rich Internet Application?
Why not both? One use case is will the documentation be available as a download and work offline? Another is can I turn it into other formats i.e. convert to PDF or to have as a reference on my ebook reader?
> Maybe there is some advantage to static HTML that I don't understand.
Offline viewing, format portability, SEO and search-ability (google ranking favours static fast sites and can’t index some dynamic content), higher scalability (but that’s a nice problem to have), and usually less bandwidth and faster on mobile. But that not to say dynamic sites don’t have different advantages.
Thanks,
Justin
1. https://en.wikipedia.org/wiki/List_of_minimum_annual_leave_by_country
2. https://www.w3.org/TR/xslt
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 2:06 AM, "Justin Mclean" <ju...@classsoftware.com> wrote:
>Hi,
>
>> I have the beginnings of a DITA emitter, but it needs finishing. You
>>are
>> welcome to finish it. IMO, the project is better off not having new
>> dependencies on XSLT. It is great that you are an expert at it, but it
>>is
>> more important that we have redundancy in the community
>
>I also know XSLT so there is redundancy. Basic XSLT stuff is easy enough
>to pick up if you have ever used a tempting system (or MXML binding
>thinking about it) and know XML which I think would be most people.
OK, but you have said elsewhere you have little time to contribute. The
fewer things folks have to know to contribute the better. Honestly, I've
always wanted to replace the XSLT in the regular Flex ASDoc. We know
folks have to know AS to participate. What happens if you and Chris are
busy or no longer around?
Let's first discuss this one point: Should FlexJS ASDoc be static HTML or
a Rich Internet Application? Maybe there is some advantage to static HTML
that I don't understand. This is definitely not my area of expertise. I
just know that when I compare Apache Flex ASDoc [1] to Adobe's ASDoc [2],
the first thing I notice is the filtering. I think FlexJS is really going
to need good filtering because it is going to have lots more classes that
should only be used in certain contexts. To me, that's an application.
Yes, maybe all other languages currently publish doc as HTML pages, but
isn't one of our goals to have folks start replacing their static sites
with RIAs?
I'm certainly not going to stop anyone from going down the XSLT path, but
would think it would serve the project better if we concentrated our
energy on making ASDoc one of our flagship applications and "eat our dog
food". And if the XSLT version of the doc gets stale or gets complaints
and those who know XSLT can't keep up and it becomes easier to just
unpublished the XSLT pages, that might have to happen.
[1] http://flex.apache.org/asdoc/
[2]
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/index.ht
ml
Re: [FLEXJS] ASDoc App
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> I have the beginnings of a DITA emitter, but it needs finishing. You are
> welcome to finish it. IMO, the project is better off not having new
> dependencies on XSLT. It is great that you are an expert at it, but it is
> more important that we have redundancy in the community
I also know XSLT so there is redundancy. Basic XSLT stuff is easy enough to pick up if you have ever used a tempting system (or MXML binding thinking about it) and know XML which I think would be most people.
Thanks,
Justin
Re: [FLEXJS] ASDoc App
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> Is this true? The article Om posted seems to disagree.
While Google can index content from JS apps [4] they may not index all content or may not give it equal weight / ranking to other static content. It’s complicated, for instance see [1][2] (answered by a Google employee). And exactly what google does has and will change over time [3][5].
Thanks,
Justin
1. http://stackoverflow.com/questions/31521462/search-engine-indexing-of-single-page-applications/31535615#31535615
2. http://stackoverflow.com/questions/31637880/are-search-engines-going-to-see-my-dynamically-created-content-in-bootstrap-tabs/31638926%2331638926
3. https://webmasters.googleblog.com/2015/10/deprecating-our-ajax-crawling-scheme.html
4. https://webmasters.googleblog.com/2014/05/understanding-web-pages-better.html
5. https://webmasters.googleblog.com/2016/11/building-indexable-progressive-web-apps.html
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/18/16, 5:27 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
>Google doesn’t index JS applications
Is this true? The article Om posted seems to disagree.
>I think HTML is best for that usecase.
>Displaying help in IDEs ususally works by looking for a file with the
>same name and relative path as the class being displayed (but replacing
>the file ending with html). These IDEs will not be able to display our
>API documentation without updating the IDE. And for one of our major
>IDEs, I deffinitely know that hell will freeze first before they come
>with an update.
This may be true for Java, but for Flex, it appears that both FDT and FB
work from the DITA xml files, not from HTML.
>You (Alex) have stated several times, that you will favour new Features
>over stability and other things. That’s a valid way to see things, but I
>have been working for enterprizses fort he last ... gee 17 years and I
>know that they like features, but even more they like stability,
>reliability, standards etc. That’s why I’m constantly pulling to get/keep
>a bit of these ideas in FlexJS.
Really what I am saying is that to get to 1.0 fastest, we need a critical
mass of features that enables someone to produce a production application,
and figure out the usability/approachable of our APIs. So
backward-compatibility with last week's APIs is not important and
regression testing isn't important until we understand what it takes to
make someone(s) successful. I will be much more serious about stability
and backward-compatibility after we hit 1.0.
-Alex
Re: [FLEXJS] ASDoc App
Posted by Christofer Dutz <ch...@c-ware.de>.
To add my oppinion to this topic:
I too think it’s a great idea to have some cool FlexJS tool to display our documentation. No doubt about that.
But on the other side I think there are well established standards and there is great benefit in supporting these too.
Google doesn’t index JS applications, how would Google pick up our documentation? I think HTML is best for that usecase.
Displaying help in IDEs ususally works by looking for a file with the same name and relative path as the class being displayed (but replacing the file ending with html). These IDEs will not be able to display our API documentation without updating the IDE. And for one of our major IDEs, I deffinitely know that hell will freeze first before they come with an update.
One company that usually tends to say „fu** standards, we’ll just do it differently, because we can and people will still buy our stuff because we’re so toally awesome“ is deffinitely Apple and that’s what I hate Apple for. Well at least with the new MBP they finally managed to push this a little too far. I’m really hoping that the market will take care of them paying for that ;-)
I’m not suggesting to not do the APP version, I’m talking about having both. And I’m gonna do the static path. And I deffinitely don’t think this is a „waste of time“. You (Alex) have stated several times, that you will favour new Features over stability and other things. That’s a valid way to see things, but I have been working for enterprizses fort he last ... gee 17 years and I know that they like features, but even more they like stability, reliability, standards etc. That’s why I’m constantly pulling to get/keep a bit of these ideas in FlexJS. Without us paying attention to these aspects of software development, FlexJS will probably only become the new cool tool for code-hipsters, but will never do the jump into the large enterprizes, which I am hoping on being able to do Flex stuff for in the future. I want FlexJS to be a serious alternative.
Chris
Am 18.12.16, 09:44 schrieb "omuppi1@gmail.com im Auftrag von OmPrakash Muppirala" <omuppi1@gmail.com im Auftrag von bigosmallm@gmail.com>:
On Sat, Dec 17, 2016 at 11:41 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 11:28 PM, "omuppi1@gmail.com on behalf of OmPrakash
> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >On Fri, Dec 16, 2016 at 9:45 PM, Alex Harui <ah...@adobe.com> wrote:
> >
> >>
> >>
> >> On 12/16/16, 7:05 PM, "omuppi1@gmail.com on behalf of OmPrakash
> >>Muppirala"
> >> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
> >>
> >> >On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
> >> >
> >> >Or could our framework dump out the resulting DOM and generate the
> >>static
> >> >HTML that way?
> >> >
> >> >
> >> >You are probably the only person who could build and maintain this :-)
> >> >I would say, XSLT sounds easier than this.
> >> >
> >>
> >> Maybe I'm not understanding something, but IMO, XSLT is an alternative
> >>for
> >> ASDoc, but isn't an alternative for all other FlexJS applications.
> >
> >
> >XSLT is a tool/language to modify the generated AsDoc into HTML. As I
> >said
> >earlier, we could also build the docs as an interactive web app. One does
> >not have to necessarily replace another.
> >
>
> Maybe I'm too idealistic, but IMO, since we are project for RIAs, it bugs
> me every time our web presence displays data without using Flex or FlexJS.
>
I think static sites have their place. As much as I love to build RIAs, I
feel that there are times when static sites simply work better. I think
documentation is one such case.
> That's why Peter is trying to build out the team page as a FlexJS app.
>
This is a great usecase for a RIA, no doubt.
> So my line of thinking is: folks have limited time to contribute, so
> spending that limited resource on static site generation of data is a bit
> contradictory.
Don't we already generate HTML from asdocs? What more do you think we need
to do on this. Other than maintenance? How often did the code for
building HTML ASDocs for the Flex project change?
> We should spend that limited time on making sure that
> FlexJS apps don't have limitations that make even us choose not to use our
> own product.
>
You lost me there. The limitation you are talking about is not with
FlexJS. Apps built with Angular, React, JQuery, all have the same
limitation. I don't anyone is going to not chose FlexJS because of this.
>
>
> >
> >> Is the
> >> only way FlexJS apps can work with search engines going to be to use
> >> PhantomJS or can we and should make something better?
> >>
> >> Thinking about static generation from a FlexJS app, it seems to be there
> >> are several pieces:
> >> 1) when is all data loaded and JS run so we can start the dump?
> >> 2) the dump is a simple DOM tree walk
> >> 3) how do we save the dump?
> >>
> >
> >I don't understand your proposal. We have javascript, css and json as
> >separate entities. You need to have a (headless) browser running the code
> >and consuming the json to generate the HTML. Are you proposing that a DOM
> >is created without a browser?
>
> Sort of. This is a totally new idea to me, so I haven't spent too much
> time thinking about it, but last night I had the idea of using AIR. Maybe
> we can build an AIR app that loads the output from FlexJS, and basically
> crawls it, but saves out the DOM tree as HTML. Of course, I could just be
> dreaming...
>
You described the easy part. IMO the harder questions are:
1. How do we serve the HTML to search engines?
2. Do we generate it on someone's local machine and upload to a
webserver? Or do we do it as a cron job on some server?
3. If it is a cron job, we need to do it on a windows machine (much like
our Mustella server) In that case, how often do we generate the HTML
files? What about the CPU, bandwidth utilizations?
4. Or do we run a parallel server that loads the content on demand (like
phantom.js)
5. Is our solution going to be turnkey? i.e. can a user reuse our
solution to their web application? Would that mean forcing AIR on them?
That would be a hard sell, especially since it cannot be run on a
non-Windows server.
6. Very few people use Windows servers to serve web content. Most of them
are variations of Linux. There is no way any AIR app can run reliably on a
given variation of Linux.
Thinking more about this problem if anything I would say lets make FlexJS
work seamlessly with phantom.js as others are already using it. This makes
switching frameworks easier. Just my 2 cents.
PS: My goal for FlexJS is to make it more acceptable to for the Javascript
community, not necessarily just catering to the existing Flex community.
That means that bringing FlexJS to npm, implementing MDL, integration with
phantom.js, etc.
JS developers are already looking at Typescript and Coffeescript.
ActionScript is not too different from all this. Adding MXML to the mix, I
think FlexJS is leaps and bounds ahead of existing JS frameworks.
Thanks,
Om
> Thoughts?
> -Alex
>
>
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Dec 18, 2016 7:32 AM, "Alex Harui" <ah...@adobe.com> wrote:
>
>
>> So my line of thinking is: folks have limited time to contribute, so
>> spending that limited resource on static site generation of data is a
>>bit
>> contradictory.
>
>
>Don't we already generate HTML from asdocs? What more do you think we
>need
>to do on this. Other than maintenance? How often did the code for
>building HTML ASDocs for the Flex project change?
>
Currently, we use the flex-sdk's MXMLC to generate the HTML. No
third-party can take the FlexJS SDK, build a custom library and generate
the ASDocs for it without also getting the regular Flex SDK. I have
already written enough code in Falcon and FlexJS to produce this ASDoc
app. Next step would be DITA files to do ASDoc in code hinting for FB and
FDT and maybe other IDEs.
Up above you mentioned that IDEs need DITA xml. So we definitely need this
part, right?
Last is a way to convert DITA to HTML via XSLT.
Which I don't know how to do.
This is the part that Chris, Justin and I can help with. In fact, there
are enough tooling out there to make this easier. You won't have to do
much here.
For me, it would be faster to modify the
ASDoc app to generate the HTML. Then more folks could modify it since
more folks know AS.
You are welcome to do this. As long as we don't stop generating the DITA
xml to favor this approach.
IMO, it doesn't matter how often the regular Flex ASDoc changed. I think
we need a more sophisticated ASDoc for FlexJS because we have lots more
classes that only can be used in certain contexts. Better filtering is
needed. That smells like a RIA to me. Sure you can put a pile of HTML
somewhere, but it won't be nearly as usable as a RIA with filtering.
My point was more about not requiring a lot of upkeep or maintenence.
>>
>> Sort of. This is a totally new idea to me, so I haven't spent too much
>> time thinking about it, but last night I had the idea of using AIR.
>>Maybe
>> we can build an AIR app that loads the output from FlexJS, and basically
>> crawls it, but saves out the DOM tree as HTML. Of course, I could just
>>be
>> dreaming...
>>
>
>You described the easy part. IMO the harder questions are:
>
>1. How do we serve the HTML to search engines?
>2. Do we generate it on someone's local machine and upload to a
>webserver? Or do we do it as a cron job on some server?
>3. If it is a cron job, we need to do it on a windows machine (much like
>our Mustella server) In that case, how often do we generate the HTML
>files? What about the CPU, bandwidth utilizations?
>4. Or do we run a parallel server that loads the content on demand (like
>phantom.js)
>5. Is our solution going to be turnkey? i.e. can a user reuse our
>solution to their web application? Would that mean forcing AIR on them?
>That would be a hard sell, especially since it cannot be run on a
>non-Windows server.
>6. Very few people use Windows servers to serve web content. Most of
>them
>are variations of Linux. There is no way any AIR app can run reliably on
>a
>given variation of Linux.
No servers needed. We have a tool chain. You write code, then run a set
of tools on it. Most of our developers are using Windows or Mac for
development already. AIR runs there as well. So a tool runs post-compile
that generates HTML. You decide in your build script how often to run it.
The result is a pile of HTML to deploy with your app. You would serve it
maybe via the port redirect discussed in the Angular SEO article.
Not so straightforward. I want my SEO to keep working long after I finish
development on my machine. Also, the data can be changing every hour or
every minute. As a developer, I can't afford to run these kind of cron
jobs on my machine. This is exactly why solutions like Jenkins and
Phantom.js etc were created.
The solution might be pretty close to turnkey. I think it would be
enabled by adding beads. Those beads could include hints to the HTML
export tool.
>
>Thinking more about this problem if anything I would say lets make FlexJS
>work seamlessly with phantom.js as others are already using it. This
>makes
>switching frameworks easier. Just my 2 cents.
Sounds good as well. What do we have to do to enable that?
I don't think we have to do much. As long as we are not compiling code in
runtime and are just serving up html and js, phantom.js can handle it. The
tricky part is the setup and maintenance of the server itself.
Best would be to have a jenkins job spin up a phantom.js server and we load
the flexjs app and ensure that all pages are loaded and the resultant html
saved somewhere.
We could also just throw up the flexjs app on a public site and see how
well Google is able to index it. And then fine tune it from there.
Thanks,
Om
-Alex
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
>
>
>> So my line of thinking is: folks have limited time to contribute, so
>> spending that limited resource on static site generation of data is a
>>bit
>> contradictory.
>
>
>Don't we already generate HTML from asdocs? What more do you think we
>need
>to do on this. Other than maintenance? How often did the code for
>building HTML ASDocs for the Flex project change?
>
Currently, we use the flex-sdk's MXMLC to generate the HTML. No
third-party can take the FlexJS SDK, build a custom library and generate
the ASDocs for it without also getting the regular Flex SDK. I have
already written enough code in Falcon and FlexJS to produce this ASDoc
app. Next step would be DITA files to do ASDoc in code hinting for FB and
FDT and maybe other IDEs. Last is a way to convert DITA to HTML via XSLT.
Which I don't know how to do. For me, it would be faster to modify the
ASDoc app to generate the HTML. Then more folks could modify it since
more folks know AS.
IMO, it doesn't matter how often the regular Flex ASDoc changed. I think
we need a more sophisticated ASDoc for FlexJS because we have lots more
classes that only can be used in certain contexts. Better filtering is
needed. That smells like a RIA to me. Sure you can put a pile of HTML
somewhere, but it won't be nearly as usable as a RIA with filtering.
>>
>> Sort of. This is a totally new idea to me, so I haven't spent too much
>> time thinking about it, but last night I had the idea of using AIR.
>>Maybe
>> we can build an AIR app that loads the output from FlexJS, and basically
>> crawls it, but saves out the DOM tree as HTML. Of course, I could just
>>be
>> dreaming...
>>
>
>You described the easy part. IMO the harder questions are:
>
>1. How do we serve the HTML to search engines?
>2. Do we generate it on someone's local machine and upload to a
>webserver? Or do we do it as a cron job on some server?
>3. If it is a cron job, we need to do it on a windows machine (much like
>our Mustella server) In that case, how often do we generate the HTML
>files? What about the CPU, bandwidth utilizations?
>4. Or do we run a parallel server that loads the content on demand (like
>phantom.js)
>5. Is our solution going to be turnkey? i.e. can a user reuse our
>solution to their web application? Would that mean forcing AIR on them?
>That would be a hard sell, especially since it cannot be run on a
>non-Windows server.
>6. Very few people use Windows servers to serve web content. Most of
>them
>are variations of Linux. There is no way any AIR app can run reliably on
>a
>given variation of Linux.
No servers needed. We have a tool chain. You write code, then run a set
of tools on it. Most of our developers are using Windows or Mac for
development already. AIR runs there as well. So a tool runs post-compile
that generates HTML. You decide in your build script how often to run it.
The result is a pile of HTML to deploy with your app. You would serve it
maybe via the port redirect discussed in the Angular SEO article.
The solution might be pretty close to turnkey. I think it would be
enabled by adding beads. Those beads could include hints to the HTML
export tool.
>
>Thinking more about this problem if anything I would say lets make FlexJS
>work seamlessly with phantom.js as others are already using it. This
>makes
>switching frameworks easier. Just my 2 cents.
Sounds good as well. What do we have to do to enable that?
-Alex
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Sat, Dec 17, 2016 at 11:41 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 11:28 PM, "omuppi1@gmail.com on behalf of OmPrakash
> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >On Fri, Dec 16, 2016 at 9:45 PM, Alex Harui <ah...@adobe.com> wrote:
> >
> >>
> >>
> >> On 12/16/16, 7:05 PM, "omuppi1@gmail.com on behalf of OmPrakash
> >>Muppirala"
> >> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
> >>
> >> >On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
> >> >
> >> >Or could our framework dump out the resulting DOM and generate the
> >>static
> >> >HTML that way?
> >> >
> >> >
> >> >You are probably the only person who could build and maintain this :-)
> >> >I would say, XSLT sounds easier than this.
> >> >
> >>
> >> Maybe I'm not understanding something, but IMO, XSLT is an alternative
> >>for
> >> ASDoc, but isn't an alternative for all other FlexJS applications.
> >
> >
> >XSLT is a tool/language to modify the generated AsDoc into HTML. As I
> >said
> >earlier, we could also build the docs as an interactive web app. One does
> >not have to necessarily replace another.
> >
>
> Maybe I'm too idealistic, but IMO, since we are project for RIAs, it bugs
> me every time our web presence displays data without using Flex or FlexJS.
>
I think static sites have their place. As much as I love to build RIAs, I
feel that there are times when static sites simply work better. I think
documentation is one such case.
> That's why Peter is trying to build out the team page as a FlexJS app.
>
This is a great usecase for a RIA, no doubt.
> So my line of thinking is: folks have limited time to contribute, so
> spending that limited resource on static site generation of data is a bit
> contradictory.
Don't we already generate HTML from asdocs? What more do you think we need
to do on this. Other than maintenance? How often did the code for
building HTML ASDocs for the Flex project change?
> We should spend that limited time on making sure that
> FlexJS apps don't have limitations that make even us choose not to use our
> own product.
>
You lost me there. The limitation you are talking about is not with
FlexJS. Apps built with Angular, React, JQuery, all have the same
limitation. I don't anyone is going to not chose FlexJS because of this.
>
>
> >
> >> Is the
> >> only way FlexJS apps can work with search engines going to be to use
> >> PhantomJS or can we and should make something better?
> >>
> >> Thinking about static generation from a FlexJS app, it seems to be there
> >> are several pieces:
> >> 1) when is all data loaded and JS run so we can start the dump?
> >> 2) the dump is a simple DOM tree walk
> >> 3) how do we save the dump?
> >>
> >
> >I don't understand your proposal. We have javascript, css and json as
> >separate entities. You need to have a (headless) browser running the code
> >and consuming the json to generate the HTML. Are you proposing that a DOM
> >is created without a browser?
>
> Sort of. This is a totally new idea to me, so I haven't spent too much
> time thinking about it, but last night I had the idea of using AIR. Maybe
> we can build an AIR app that loads the output from FlexJS, and basically
> crawls it, but saves out the DOM tree as HTML. Of course, I could just be
> dreaming...
>
You described the easy part. IMO the harder questions are:
1. How do we serve the HTML to search engines?
2. Do we generate it on someone's local machine and upload to a
webserver? Or do we do it as a cron job on some server?
3. If it is a cron job, we need to do it on a windows machine (much like
our Mustella server) In that case, how often do we generate the HTML
files? What about the CPU, bandwidth utilizations?
4. Or do we run a parallel server that loads the content on demand (like
phantom.js)
5. Is our solution going to be turnkey? i.e. can a user reuse our
solution to their web application? Would that mean forcing AIR on them?
That would be a hard sell, especially since it cannot be run on a
non-Windows server.
6. Very few people use Windows servers to serve web content. Most of them
are variations of Linux. There is no way any AIR app can run reliably on a
given variation of Linux.
Thinking more about this problem if anything I would say lets make FlexJS
work seamlessly with phantom.js as others are already using it. This makes
switching frameworks easier. Just my 2 cents.
PS: My goal for FlexJS is to make it more acceptable to for the Javascript
community, not necessarily just catering to the existing Flex community.
That means that bringing FlexJS to npm, implementing MDL, integration with
phantom.js, etc.
JS developers are already looking at Typescript and Coffeescript.
ActionScript is not too different from all this. Adding MXML to the mix, I
think FlexJS is leaps and bounds ahead of existing JS frameworks.
Thanks,
Om
> Thoughts?
> -Alex
>
>
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 11:28 PM, "omuppi1@gmail.com on behalf of OmPrakash
Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>On Fri, Dec 16, 2016 at 9:45 PM, Alex Harui <ah...@adobe.com> wrote:
>
>>
>>
>> On 12/16/16, 7:05 PM, "omuppi1@gmail.com on behalf of OmPrakash
>>Muppirala"
>> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>>
>> >On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
>> >
>> >Or could our framework dump out the resulting DOM and generate the
>>static
>> >HTML that way?
>> >
>> >
>> >You are probably the only person who could build and maintain this :-)
>> >I would say, XSLT sounds easier than this.
>> >
>>
>> Maybe I'm not understanding something, but IMO, XSLT is an alternative
>>for
>> ASDoc, but isn't an alternative for all other FlexJS applications.
>
>
>XSLT is a tool/language to modify the generated AsDoc into HTML. As I
>said
>earlier, we could also build the docs as an interactive web app. One does
>not have to necessarily replace another.
>
Maybe I'm too idealistic, but IMO, since we are project for RIAs, it bugs
me every time our web presence displays data without using Flex or FlexJS.
That's why Peter is trying to build out the team page as a FlexJS app.
So my line of thinking is: folks have limited time to contribute, so
spending that limited resource on static site generation of data is a bit
contradictory. We should spend that limited time on making sure that
FlexJS apps don't have limitations that make even us choose not to use our
own product.
>
>> Is the
>> only way FlexJS apps can work with search engines going to be to use
>> PhantomJS or can we and should make something better?
>>
>> Thinking about static generation from a FlexJS app, it seems to be there
>> are several pieces:
>> 1) when is all data loaded and JS run so we can start the dump?
>> 2) the dump is a simple DOM tree walk
>> 3) how do we save the dump?
>>
>
>I don't understand your proposal. We have javascript, css and json as
>separate entities. You need to have a (headless) browser running the code
>and consuming the json to generate the HTML. Are you proposing that a DOM
>is created without a browser?
Sort of. This is a totally new idea to me, so I haven't spent too much
time thinking about it, but last night I had the idea of using AIR. Maybe
we can build an AIR app that loads the output from FlexJS, and basically
crawls it, but saves out the DOM tree as HTML. Of course, I could just be
dreaming...
Thoughts?
-Alex
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Fri, Dec 16, 2016 at 9:45 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 7:05 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
> >
> >Or could our framework dump out the resulting DOM and generate the static
> >HTML that way?
> >
> >
> >You are probably the only person who could build and maintain this :-)
> >I would say, XSLT sounds easier than this.
> >
>
> Maybe I'm not understanding something, but IMO, XSLT is an alternative for
> ASDoc, but isn't an alternative for all other FlexJS applications.
XSLT is a tool/language to modify the generated AsDoc into HTML. As I said
earlier, we could also build the docs as an interactive web app. One does
not have to necessarily replace another.
> Is the
> only way FlexJS apps can work with search engines going to be to use
> PhantomJS or can we and should make something better?
>
> Thinking about static generation from a FlexJS app, it seems to be there
> are several pieces:
> 1) when is all data loaded and JS run so we can start the dump?
> 2) the dump is a simple DOM tree walk
> 3) how do we save the dump?
>
I don't understand your proposal. We have javascript, css and json as
separate entities. You need to have a (headless) browser running the code
and consuming the json to generate the HTML. Are you proposing that a DOM
is created without a browser?
Phantom.js uses webkit as the rendering engine [1], much like an AIR app.
We could theoretically write an AIR app that does a similar thing (although
making it run in a X11-less server is almost impossible and AFAIK is
probably against Adobe's EULA for AIR)
Google probably has a phantom.js like setup which simply consumes the web
application like a normal user and then indexes the generate HTML files
locally.
[1] http://phantomjs.org/supported-web-standards.html
>
> I haven't looked yet, but aren't these solved problems?
>
> -Alex
>
>
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 7:05 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
<omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
>
>Or could our framework dump out the resulting DOM and generate the static
>HTML that way?
>
>
>You are probably the only person who could build and maintain this :-)
>I would say, XSLT sounds easier than this.
>
Maybe I'm not understanding something, but IMO, XSLT is an alternative for
ASDoc, but isn't an alternative for all other FlexJS applications. Is the
only way FlexJS apps can work with search engines going to be to use
PhantomJS or can we and should make something better?
Thinking about static generation from a FlexJS app, it seems to be there
are several pieces:
1) when is all data loaded and JS run so we can start the dump?
2) the dump is a simple DOM tree walk
3) how do we save the dump?
I haven't looked yet, but aren't these solved problems?
-Alex
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Dec 16, 2016 3:15 PM, "Alex Harui" <ah...@adobe.com> wrote:
On 12/16/16, 3:06 PM, "Alex Harui" <ah...@adobe.com> wrote:
>I am surprised by the complexity of [1]. But because we have a tool
>chain, I wonder if the tool chain should somehow help. Should we have a
>tool that calls PhantomJS or some equivalent?
Or could our framework dump out the resulting DOM and generate the static
HTML that way?
You are probably the only person who could build and maintain this :-)
I would say, XSLT sounds easier than this.
-Alex
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 3:06 PM, "Alex Harui" <ah...@adobe.com> wrote:
>I am surprised by the complexity of [1]. But because we have a tool
>chain, I wonder if the tool chain should somehow help. Should we have a
>tool that calls PhantomJS or some equivalent?
Or could our framework dump out the resulting DOM and generate the static
HTML that way?
-Alex
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 1:36 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
<omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
>IMO, this problem
>> needs to be made easy for all FlexJS applications and that's one reason
>>to
>> make ASDoc a RIA. So we can show folks how to do it. Are there really
>> static pages behind Home Depot and Amazon's stores?
>>
>
>
>But then you need something like phantom.js that runs our SPA, renders the
>html and stores/serves it on demand. When a search bot hits the server,
>we
>need to figure that out and redirect it to the phantom.js server instead
>of
>serving up the JS and CSS filese required to render the web application.
>Here is an overview of one way of adding search engine optimization for a
>single page app [1]
>
>My point is: it is quite a bit of unnecessary work when you can simply
>generate html from asdocs using XSLT.
My point is, that most RIAs may not easily translate to html using XSLT.
We need to provide the reference for how to make a FlexJS RIA available to
search engines. If you have an hour to contribute to FlexJS, I would much
rather have you work on that than on XSLT. But of course, you are free to
do what you want.
I am surprised by the complexity of [1]. But because we have a tool
chain, I wonder if the tool chain should somehow help. Should we have a
tool that calls PhantomJS or some equivalent?
Thoughts?
-Alex
>
>Google can probably just handle a SPA without any special work needed from
>us [1], but not sure about other search engines.
>
>[1]
>https://lawsonry.com/2014/05/diy-angularjs-seo-with-phantomjs-the-easy-way
>/
>[2]
>https://webmasters.googleblog.com/2014/05/understanding-web-pages-better.h
>tml
>
>
>
>
>>
>> -Alex
>>
>>
>>
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Fri, Dec 16, 2016 at 12:13 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 11:58 AM, "omuppi1@gmail.com on behalf of OmPrakash
> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >On Fri, Dec 16, 2016 at 11:54 AM, Alex Harui <ah...@adobe.com> wrote:
> >
> >>
> >>
> >> On 12/16/16, 11:42 AM, "omuppi1@gmail.com on behalf of OmPrakash
> >> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
> >>
> >> >I think we don't need to decide one way or the other right now. We
> >>need
> >> >simple html docs for sure.
> >>
> >> I'm not sure what you mean by this. What does "simple html" mean and
> >>why
> >> do we need it?
> >>
> >
> >I could be wrong, but I assume IDE's need HTML formatted docs to show
> >hover
> >over API documentation? We cant expect a JS engine being available
> >everywhere.
>
> If you are referring to Flash Builder, I don't know for sure, but there is
> some indication that it just needs the DITA.xml file and not html. I
> don't know about other IDEs. Josh, have you thought about this for VSCode?
>
> >
> >Also, for SEO we need pre-formatted HTML whichever way you decide to do
> >it.
>
> Are you sure about this? I was under the impression that all RIAs,
> whether written in Flex or not, had to simply return HTML for some URL.
The file didn't actually have to exist statically.
IMO, this problem
> needs to be made easy for all FlexJS applications and that's one reason to
> make ASDoc a RIA. So we can show folks how to do it. Are there really
> static pages behind Home Depot and Amazon's stores?
>
But then you need something like phantom.js that runs our SPA, renders the
html and stores/serves it on demand. When a search bot hits the server, we
need to figure that out and redirect it to the phantom.js server instead of
serving up the JS and CSS filese required to render the web application.
Here is an overview of one way of adding search engine optimization for a
single page app [1]
My point is: it is quite a bit of unnecessary work when you can simply
generate html from asdocs using XSLT.
Google can probably just handle a SPA without any special work needed from
us [1], but not sure about other search engines.
[1]
https://lawsonry.com/2014/05/diy-angularjs-seo-with-phantomjs-the-easy-way/
[2]
https://webmasters.googleblog.com/2014/05/understanding-web-pages-better.html
>
> -Alex
>
>
>
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 11:58 AM, "omuppi1@gmail.com on behalf of OmPrakash
Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>On Fri, Dec 16, 2016 at 11:54 AM, Alex Harui <ah...@adobe.com> wrote:
>
>>
>>
>> On 12/16/16, 11:42 AM, "omuppi1@gmail.com on behalf of OmPrakash
>> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>>
>> >I think we don't need to decide one way or the other right now. We
>>need
>> >simple html docs for sure.
>>
>> I'm not sure what you mean by this. What does "simple html" mean and
>>why
>> do we need it?
>>
>
>I could be wrong, but I assume IDE's need HTML formatted docs to show
>hover
>over API documentation? We cant expect a JS engine being available
>everywhere.
If you are referring to Flash Builder, I don't know for sure, but there is
some indication that it just needs the DITA.xml file and not html. I
don't know about other IDEs. Josh, have you thought about this for VSCode?
>
>Also, for SEO we need pre-formatted HTML whichever way you decide to do
>it.
Are you sure about this? I was under the impression that all RIAs,
whether written in Flex or not, had to simply return HTML for some URL.
The file didn't actually have to exist statically. IMO, this problem
needs to be made easy for all FlexJS applications and that's one reason to
make ASDoc a RIA. So we can show folks how to do it. Are there really
static pages behind Home Depot and Amazon's stores?
-Alex
Re: [FLEXJS] ASDoc App
Posted by Josh Tynjala <jo...@gmail.com>.
If IDEs show docs on hover or in completion while you're coding, it's
usually from parsing the original ASDoc or some intermediate format (I
think SWCs can include that DITA format that Alex was talking about).
- Josh
On Fri, Dec 16, 2016 at 11:58 AM, OmPrakash Muppirala <bi...@gmail.com>
wrote:
> On Fri, Dec 16, 2016 at 11:54 AM, Alex Harui <ah...@adobe.com> wrote:
>
> >
> >
> > On 12/16/16, 11:42 AM, "omuppi1@gmail.com on behalf of OmPrakash
> > Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
> >
> > >I think we don't need to decide one way or the other right now. We need
> > >simple html docs for sure.
> >
> > I'm not sure what you mean by this. What does "simple html" mean and why
> > do we need it?
> >
>
> I could be wrong, but I assume IDE's need HTML formatted docs to show hover
> over API documentation? We cant expect a JS engine being available
> everywhere.
>
> Also, for SEO we need pre-formatted HTML whichever way you decide to do it.
>
> Thanks,
> Om
>
>
> >
> > -Alex
> >
> >
>
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Fri, Dec 16, 2016 at 11:54 AM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 11:42 AM, "omuppi1@gmail.com on behalf of OmPrakash
> Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >I think we don't need to decide one way or the other right now. We need
> >simple html docs for sure.
>
> I'm not sure what you mean by this. What does "simple html" mean and why
> do we need it?
>
I could be wrong, but I assume IDE's need HTML formatted docs to show hover
over API documentation? We cant expect a JS engine being available
everywhere.
Also, for SEO we need pre-formatted HTML whichever way you decide to do it.
Thanks,
Om
>
> -Alex
>
>
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 11:42 AM, "omuppi1@gmail.com on behalf of OmPrakash
Muppirala" <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>I think we don't need to decide one way or the other right now. We need
>simple html docs for sure.
I'm not sure what you mean by this. What does "simple html" mean and why
do we need it?
-Alex
Re: [FLEXJS] ASDoc App
Posted by Josh Tynjala <jo...@gmail.com>.
The Angular docs actually aren't static HTML. It looks like an Angular app!
https://docs.angularjs.org/api/ng/function/angular.forEach
If you view source on the page above, you can see that there's a Loading...
placeholder and the real content is loaded dynamically.
- Josh
On Fri, Dec 16, 2016 at 11:42 AM, OmPrakash Muppirala <bi...@gmail.com>
wrote:
> I think we don't need to decide one way or the other right now. We need
> simple html docs for sure. I think having the docs as an RIA as pretty
> cool as well.
>
> For example, AngularJS docs is available as mostly static content here:
> https://docs.angularjs.org/api
> For this kind of doc, we just need simple XSLT on the generated asdocs.
>
> Although, there is a nice integration for runtime errors. When you run
> into framework exceptions, AngularJS throws this kind of line in the
> console with an url: https://s.apache.org/angular_error (shortened it,
> because this is a big error)
>
> When you actually go to the link, the error is explained and possible fixes
> are provided. That is a pretty cool feature. I dont think we can do this
> kind of stuff with simple static HTML docs.
>
> Thanks,
> Om
>
> On Fri, Dec 16, 2016 at 10:22 AM, Alex Harui <ah...@adobe.com> wrote:
>
> >
> >
> > On 12/16/16, 1:51 AM, "Christofer Dutz" <ch...@c-ware.de>
> wrote:
> > >
> > >What do I have to do to get the XML files? I’ll have a look at what I
> > >find.
> >
> > In flex-falcon/compiler-jx there is a
> > org.apache.flex.compiler.clients.ASDOCJSC.java
> > It works just like MXMLC and COMPC. If you specify
> > -js-output-type=FLEXJS_DITA you will get XML, but I'm sure it is buggy
> and
> > not complete.
> >
> > I'm not an expert on this stuff at all, but apparently, DITA is some sort
> > of known pattern of use for XML, and at least Flash Builder and maybe
> > other IDEs understand it, and if you pack DITA files in a SWC, Flash
> > Builder will show it in code assist somehow. I haven't tried it, but
> that
> > was the only reason I even started on xml output.
> >
> > However, if you look at the DITA files generated by the regular Flex SDK,
> > you'll see there is one per package. Right now I think ASDOCJSC is
> > outputting one per class since that was easiest given that each class is
> > compiled in its own thread.
> >
> > I'm not sure when I'd get back to working on the DITA files so someone
> > else is definitely welcome to push this forward.
> >
> > HTH,
> > -Alex
> >
> >
>
Re: [FLEXJS] ASDoc App
Posted by OmPrakash Muppirala <bi...@gmail.com>.
I think we don't need to decide one way or the other right now. We need
simple html docs for sure. I think having the docs as an RIA as pretty
cool as well.
For example, AngularJS docs is available as mostly static content here:
https://docs.angularjs.org/api
For this kind of doc, we just need simple XSLT on the generated asdocs.
Although, there is a nice integration for runtime errors. When you run
into framework exceptions, AngularJS throws this kind of line in the
console with an url: https://s.apache.org/angular_error (shortened it,
because this is a big error)
When you actually go to the link, the error is explained and possible fixes
are provided. That is a pretty cool feature. I dont think we can do this
kind of stuff with simple static HTML docs.
Thanks,
Om
On Fri, Dec 16, 2016 at 10:22 AM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 12/16/16, 1:51 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
> >
> >What do I have to do to get the XML files? I’ll have a look at what I
> >find.
>
> In flex-falcon/compiler-jx there is a
> org.apache.flex.compiler.clients.ASDOCJSC.java
> It works just like MXMLC and COMPC. If you specify
> -js-output-type=FLEXJS_DITA you will get XML, but I'm sure it is buggy and
> not complete.
>
> I'm not an expert on this stuff at all, but apparently, DITA is some sort
> of known pattern of use for XML, and at least Flash Builder and maybe
> other IDEs understand it, and if you pack DITA files in a SWC, Flash
> Builder will show it in code assist somehow. I haven't tried it, but that
> was the only reason I even started on xml output.
>
> However, if you look at the DITA files generated by the regular Flex SDK,
> you'll see there is one per package. Right now I think ASDOCJSC is
> outputting one per class since that was easiest given that each class is
> compiled in its own thread.
>
> I'm not sure when I'd get back to working on the DITA files so someone
> else is definitely welcome to push this forward.
>
> HTH,
> -Alex
>
>
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/16/16, 1:51 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
>
>What do I have to do to get the XML files? I’ll have a look at what I
>find.
In flex-falcon/compiler-jx there is a
org.apache.flex.compiler.clients.ASDOCJSC.java
It works just like MXMLC and COMPC. If you specify
-js-output-type=FLEXJS_DITA you will get XML, but I'm sure it is buggy and
not complete.
I'm not an expert on this stuff at all, but apparently, DITA is some sort
of known pattern of use for XML, and at least Flash Builder and maybe
other IDEs understand it, and if you pack DITA files in a SWC, Flash
Builder will show it in code assist somehow. I haven't tried it, but that
was the only reason I even started on xml output.
However, if you look at the DITA files generated by the regular Flex SDK,
you'll see there is one per package. Right now I think ASDOCJSC is
outputting one per class since that was easiest given that each class is
compiled in its own thread.
I'm not sure when I'd get back to working on the DITA files so someone
else is definitely welcome to push this forward.
HTH,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Christofer Dutz <ch...@c-ware.de>.
I’m talking about using XSLT in the Maven plugin to convert the XML to HTML.
You don’t even need a dependency to anything, because XSLT is so standard, that it’s part oft he JDK.
XML, XSL and HTML are everything but rocket-science ... you can do some crazy stuff with XSL, but that’s not what I’ll try to do. My plans are keeping things as simple as possible.
And it’s still not me taking down FlexJS a path that no other language is going down. I don’t recall any of the other main languages out there not providing HTML API Docs.
What do I have to do to get the XML files? I’ll have a look at what I find.
And regarding the empty compiler jars ... they don’t contain anything but a MANIFEST.MF (I generate them where I generatet he distribution).
Chris
Am 15.12.16, 18:47 schrieb "Alex Harui" <ah...@adobe.com>:
On 12/15/16, 2:59 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
>Hi Alex,
>
>great to hear that ... being someone who still thinks the static API
>documentation is important, I would like to work on a maven site mojo to
>generate that static stuff. I am very experienced with XSLT, so that
>shouldn’t be a problem. You mentioned, that the Falcon compiler outputs
>XML ... where is that output to and what do I need to do to make him
>generate that?
I have the beginnings of a DITA emitter, but it needs finishing. You are
welcome to finish it. IMO, the project is better off not having new
dependencies on XSLT. It is great that you are an expert at it, but it is
more important that we have redundancy in the community, so relying on
languages most of us know is better. If you want to modify the ASDoc app
to generate HTML pages that's great as well, but I don't understand why
static pages are better than dynamic pages. If your concern is search
engines, that is a problem we need to solve for every FlexJS app and the
answer hopefully isn't to generate a pile of HTML from your app.
My 2 cents,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/15/16, 2:59 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
>Hi Alex,
>
>great to hear that ... being someone who still thinks the static API
>documentation is important, I would like to work on a maven site mojo to
>generate that static stuff. I am very experienced with XSLT, so that
>shouldn’t be a problem. You mentioned, that the Falcon compiler outputs
>XML ... where is that output to and what do I need to do to make him
>generate that?
I have the beginnings of a DITA emitter, but it needs finishing. You are
welcome to finish it. IMO, the project is better off not having new
dependencies on XSLT. It is great that you are an expert at it, but it is
more important that we have redundancy in the community, so relying on
languages most of us know is better. If you want to modify the ASDoc app
to generate HTML pages that's great as well, but I don't understand why
static pages are better than dynamic pages. If your concern is search
engines, that is a problem we need to solve for every FlexJS app and the
answer hopefully isn't to generate a pile of HTML from your app.
My 2 cents,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Christofer Dutz <ch...@c-ware.de>.
Hi Alex,
great to hear that ... being someone who still thinks the static API documentation is important, I would like to work on a maven site mojo to generate that static stuff. I am very experienced with XSLT, so that shouldn’t be a problem. You mentioned, that the Falcon compiler outputs XML ... where is that output to and what do I need to do to make him generate that?
Chris
Am 14.12.16, 18:38 schrieb "Alex Harui" <ah...@adobe.com>:
Hi,
Today I finally got enough of a FlexJS ASDoc app running to mention it on
the list, in hope that other folks can pitch in to help us finish it and
help prove that FlexJS can help folks do something useful, as well as make
it easier for folks to write code with FlexJS.
Normally, our ASDoc is published as a pile of HTML files. The regular
Flex MXMLC compiler has code that generates a pile of XML files and then
MXMLC calls into the Saxon library to apply XSLT to generate the HTML.
The Falcon codebase didn't have any of this code, but instead of copying
in the code and the Saxon dependency from flex-sdk, I chose to take a
completely different approach because I think that ASDoc for FlexJS may
need to be more interactive. There are so many more classes that have
different categorizations and different usage contexts that I want to
provide more sophisticated filtering, so users can filter down to, for
instance, "top-level components", or "view beads", etc. This is certainly
possible to do with a pile of HTML, but that would require that I and
anyone else who wants to help to learn or know XSLT. It makes more sense
to me to use ActionScript and MXML instead since everyone in this
community knows that. And turning this into a production-quality app
would force us to develop some new code that other folks will probably
want.
The source code is checked into the flex-asjs repo under
examples\flexjs\ASDoc. The apacheflexbuild CI server will re-build the
ASDoc app on any change to the flex-asjs repo, so you can see your results
here [1][2]. If you run it now, you'll see its pretty ugly. All I wanted
to get working was the ability to parse the underlying JSON files, which I
think is mostly working. It would be great to see folks pitch in to:
-make it look better
-use links for the base classes
-provide an "All classes" and "index"
-provide filters
-localization?
-maven build
-deep linking
-search engine support
And tons of other improvements. Just compare it to the current ASDoc to
see what is missing. My vision for filtering would be to allow folks to
check off a list of attributes that correlate to asdoc tags. We could
annotate all top-level components with @toplevel, and beads with @bead
and/or @viewbead and the app would offer the list of known tags and you
could check which ones you want to see or hide. I'll probably implement
the beginnings of that after I catch up on some other issues, but you
don't have to wait for me.
Hope you can find time to help,
-Alex
[1] SWF version:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
[2] JS Debug:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
Note, the js-release version may not run since the code is currently using
lots of plain objects.
Re: [FLEXJS] ASDoc App
Posted by yishayw <yi...@hotmail.com>.
One of the reasons I like this idea is that it gives a chance to easily see
bugs in FlexJS.
Two things that popped up:
1) Scrolling in SWF version is slow to the point of not working.
2) Loading HTML version in Edge takes forever.
I think we should leverage this and add it as a component on which Jira
issues can be filed. It's nice to have simple code that demonstrates the
problem in a self-contained app, but a lot of people will find it easier to
just reference the docs app.
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FLEXJS-ASDoc-App-tp57249p57255.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FLEXJS] ASDoc App
Posted by yishayw <yi...@hotmail.com>.
This is a great idea. Here are thr proper links (not broken by newlines)
[1] SWF version:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastSuccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
[2] JS version:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastSuccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
--
View this message in context: http://apache-flex-development.2333347.n4.nabble.com/FLEXJS-ASDoc-App-tp57249p57252.html
Sent from the Apache Flex Development mailing list archive at Nabble.com.
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/15/16, 3:02 AM, "Christofer Dutz" <ch...@c-ware.de> wrote:
>If there now is a „asdoc.jar“ created by the ant build, the proper way to
>do this in Maven would be to create a „asdoc“ module. Creating multiple
>jars from one codebase is usually an indicator for the need to refactor.
Well, you are welcome to propose another refactor. In Ant, we still
output an mxmlc.jar and compc.jar. These client jars are empty and just
have different entry points to the client classes in jsc.jar. The ASDoc
JSON output is generated via a different emitter in compiler-jx.
-Alex
Re: [FLEXJS] ASDoc App
Posted by Christofer Dutz <ch...@c-ware.de>.
If there now is a „asdoc.jar“ created by the ant build, the proper way to do this in Maven would be to create a „asdoc“ module. Creating multiple jars from one codebase is usually an indicator for the need to refactor.
Chris
Am 14.12.16, 19:10 schrieb "Alex Harui" <ah...@adobe.com>:
On 12/14/16, 10:00 AM, "carlos.rovira@gmail.com on behalf of Carlos
Rovira" <carlos.rovira@gmail.com on behalf of
carlos.rovira@codeoscopic.com> wrote:
>Hi Alex,
>
>great work! :)
>
>I updated the pom.xml and uploaded, but doesn't has any content yet at the
>momento (but compilation is working in js) :)
Yeah, the simple part of adding the pom to compile the sources I know how
to do. There are two pieces that I would rather someone else do:
1) There is now an asdoc.jar from flex-falcon/compiler-jx. This needs to
be integrated into the Maven build for flex-falcon and the jar deployed as
a Maven artifact
2) The Ant script not only build the ASDoc app, it then calls the
asdoc.jar to generate a pile of JSON files from the flex-asjs sources. I
have no idea how to do that in Maven. I think that might require another
mojo.
Thanks,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
On 12/14/16, 10:00 AM, "carlos.rovira@gmail.com on behalf of Carlos
Rovira" <carlos.rovira@gmail.com on behalf of
carlos.rovira@codeoscopic.com> wrote:
>Hi Alex,
>
>great work! :)
>
>I updated the pom.xml and uploaded, but doesn't has any content yet at the
>momento (but compilation is working in js) :)
Yeah, the simple part of adding the pom to compile the sources I know how
to do. There are two pieces that I would rather someone else do:
1) There is now an asdoc.jar from flex-falcon/compiler-jx. This needs to
be integrated into the Maven build for flex-falcon and the jar deployed as
a Maven artifact
2) The Ant script not only build the ASDoc app, it then calls the
asdoc.jar to generate a pile of JSON files from the flex-asjs sources. I
have no idea how to do that in Maven. I think that might require another
mojo.
Thanks,
-Alex
Re: [FLEXJS] ASDoc App
Posted by Carlos Rovira <ca...@codeoscopic.com>.
Hi Alex,
great work! :)
I updated the pom.xml and uploaded, but doesn't has any content yet at the
momento (but compilation is working in js) :)
2016-12-14 18:38 GMT+01:00 Alex Harui <ah...@adobe.com>:
> Hi,
>
> Today I finally got enough of a FlexJS ASDoc app running to mention it on
> the list, in hope that other folks can pitch in to help us finish it and
> help prove that FlexJS can help folks do something useful, as well as make
> it easier for folks to write code with FlexJS.
>
> Normally, our ASDoc is published as a pile of HTML files. The regular
> Flex MXMLC compiler has code that generates a pile of XML files and then
> MXMLC calls into the Saxon library to apply XSLT to generate the HTML.
> The Falcon codebase didn't have any of this code, but instead of copying
> in the code and the Saxon dependency from flex-sdk, I chose to take a
> completely different approach because I think that ASDoc for FlexJS may
> need to be more interactive. There are so many more classes that have
> different categorizations and different usage contexts that I want to
> provide more sophisticated filtering, so users can filter down to, for
> instance, "top-level components", or "view beads", etc. This is certainly
> possible to do with a pile of HTML, but that would require that I and
> anyone else who wants to help to learn or know XSLT. It makes more sense
> to me to use ActionScript and MXML instead since everyone in this
> community knows that. And turning this into a production-quality app
> would force us to develop some new code that other folks will probably
> want.
>
> The source code is checked into the flex-asjs repo under
> examples\flexjs\ASDoc. The apacheflexbuild CI server will re-build the
> ASDoc app on any change to the flex-asjs repo, so you can see your results
> here [1][2]. If you run it now, you'll see its pretty ugly. All I wanted
> to get working was the ability to parse the underlying JSON files, which I
> think is mostly working. It would be great to see folks pitch in to:
> -make it look better
> -use links for the base classes
> -provide an "All classes" and "index"
> -provide filters
> -localization?
> -maven build
> -deep linking
> -search engine support
>
> And tons of other improvements. Just compare it to the current ASDoc to
> see what is missing. My vision for filtering would be to allow folks to
> check off a list of attributes that correlate to asdoc tags. We could
> annotate all top-level components with @toplevel, and beads with @bead
> and/or @viewbead and the app would offer the list of known tags and you
> could check which ones you want to see or hide. I'll probably implement
> the beginnings of that after I catch up on some other issues, but you
> don't have to wait for me.
>
> Hope you can find time to help,
> -Alex
>
> [1] SWF version:
> http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%
> 20ASDoc%20Example/lastS
> uccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
> [2] JS Debug:
> http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%
> 20ASDoc%20Example/lastS
> uccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
>
> Note, the js-release version may not run since the code is currently using
> lots of plain objects.
>
>
>
>
--
Carlos Rovira
Director General
M: +34 607 22 60 05
http://www.codeoscopic.com
http://www.avant2.es
Este mensaje se dirige exclusivamente a su destinatario y puede contener
información privilegiada o confidencial. Si ha recibido este mensaje por
error, le rogamos que nos lo comunique inmediatamente por esta misma vía y
proceda a su destrucción.
De la vigente Ley Orgánica de Protección de Datos (15/1999), le comunicamos
que sus datos forman parte de un fichero cuyo responsable es CODEOSCOPIC
S.A. La finalidad de dicho tratamiento es facilitar la prestación del
servicio o información solicitados, teniendo usted derecho de acceso,
rectificación, cancelación y oposición de sus datos dirigiéndose a nuestras
oficinas c/ Paseo de la Habana 9-11, 28036, Madrid con la documentación
necesaria.
Re: [FLEXJS] ASDoc App
Posted by Alex Harui <ah...@adobe.com>.
I added two checkboxes to filter for just top-level components, or just
view beads. A better filtering UI is needed for filtering on dozens of
keyword, not two. Suggestions are welcome.
But I think it shows that filtering may really help customers wade through
the tons of FlexJS classes.
Thanks,
-Alex
On 12/14/16, 9:38 AM, "Alex Harui" <ah...@adobe.com> wrote:
>Hi,
>
>Today I finally got enough of a FlexJS ASDoc app running to mention it on
>the list, in hope that other folks can pitch in to help us finish it and
>help prove that FlexJS can help folks do something useful, as well as make
>it easier for folks to write code with FlexJS.
>
>Normally, our ASDoc is published as a pile of HTML files. The regular
>Flex MXMLC compiler has code that generates a pile of XML files and then
>MXMLC calls into the Saxon library to apply XSLT to generate the HTML.
>The Falcon codebase didn't have any of this code, but instead of copying
>in the code and the Saxon dependency from flex-sdk, I chose to take a
>completely different approach because I think that ASDoc for FlexJS may
>need to be more interactive. There are so many more classes that have
>different categorizations and different usage contexts that I want to
>provide more sophisticated filtering, so users can filter down to, for
>instance, "top-level components", or "view beads", etc. This is certainly
>possible to do with a pile of HTML, but that would require that I and
>anyone else who wants to help to learn or know XSLT. It makes more sense
>to me to use ActionScript and MXML instead since everyone in this
>community knows that. And turning this into a production-quality app
>would force us to develop some new code that other folks will probably
>want.
>
>The source code is checked into the flex-asjs repo under
>examples\flexjs\ASDoc. The apacheflexbuild CI server will re-build the
>ASDoc app on any change to the flex-asjs repo, so you can see your results
>here [1][2]. If you run it now, you'll see its pretty ugly. All I wanted
>to get working was the ability to parse the underlying JSON files, which I
>think is mostly working. It would be great to see folks pitch in to:
>-make it look better
>-use links for the base classes
>-provide an "All classes" and "index"
>-provide filters
>-localization?
>-maven build
>-deep linking
>-search engine support
>
>And tons of other improvements. Just compare it to the current ASDoc to
>see what is missing. My vision for filtering would be to allow folks to
>check off a list of attributes that correlate to asdoc tags. We could
>annotate all top-level components with @toplevel, and beads with @bead
>and/or @viewbead and the app would offer the list of known tags and you
>could check which ones you want to see or hide. I'll probably implement
>the beginnings of that after I catch up on some other issues, but you
>don't have to wait for me.
>
>Hope you can find time to help,
>-Alex
>
>[1] SWF version:
>http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/last
>S
>uccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
>[2] JS Debug:
>http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/last
>S
>uccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
>
>Note, the js-release version may not run since the code is currently using
>lots of plain objects.
>
>
>