You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Left Right <ol...@gmail.com> on 2012/03/20 22:59:31 UTC
Language Reference Online Materials
I was wondering, how much and if at all, and if not this list, then who is
responsible for the documentation pages.
I find some recent additions to the documentation (like this one for
example:
http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/WindowedApplication.html#!JSON.htmlwhich
I know is related to the player, not the SDK) to be of shamelessly
low quality (see the examples section; I gave someone a link at
stackoverflow.com to this page and regretted it, I'd rather write an
example then tell a newbe to learn from that page).
So, my questions are:
- if I find documentation related bugs, who do I tell about it? What's the
process / who's responsible for putting stuff online / is Adobe going to
provide aggregated documentation on projects it donated?
- What is the status of all the AIR classes, that extend framework classes?
This is not strictly speaking a documentation issue, but, considering that
WindowedApplication depends on mx.core.Application, which is under control
of Apache (now / soon), how is that going to be resolved? I'm wondering in
particular about documentation, but, obviously, there are other aspects of
it too.
- I'm not in favor of doing changes, if it's not absolutely needed, but
ASDoc is a... *sigh* well, it's easier to throw away, then to fix it,
really... I mean, of course it kind of works, but the HTML output it
generates is of so very low quality, you want to cry, and fixing it is not
particularly easy...
- There was that AIR program used for aggregated documentation of all Adobe
products. It used to include Flex framework classes. What happens to it?
This program was / is quite *controversial* one - in a sense, no one seemed
to like her, and as Adobe would explain, it was a result of budget cuts -
so that documentation could be rolled out for everyone together, rather
then every project handling it's own documentation separately. So will this
group be responsible for integrating with that application? IIRC a lot of
people were in favor of Eclipse integrated help. Some were making cfh
compiles for Windows etc. because that AIR application wasn't really
usable. So, is this group bound by any promises to keep that thing alive?
- Finally, there were online resources such as Flex Developer Manual, Flex
User Manual. They were sided in a sense they discussed framework in
connection to Flash Builder, but they are not making too many
cross-references. Anyway, is Adobe going to keep that alive too, or is it
under Apache jurisdiction now / soon?
- Just to elaborate on this, beside the manuals themselves, there exists a
kind of forum / user provided feedback feature with community help etc.
It's not particularly lively forum, yet there's daily activity of about 10
messages a day. I'm not sure about what happens to this project, who's
taking over it etc. Any thoughts?
- Are there any ideas about what / what kind of documentation / user
interaction is Apache going to provide to the users? Is it going to
leverage user manuals?
Best.
Oleg
Re: Language Reference Online Materials
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
The Spoon project is looking into doing some work around documentation but in general we all are responsible for the documentation.
> - if I find documentation related bugs, who do I tell about it?
Tell the list and/or raise a JIRA issue and if you can provide a patch.
Most of the documentation is generated from ASDoc from source code. While the asdocs hasn't been donated yet is should be soon and I see no reason why we can commit (to the patches branch) changes to comments in code.
> - What is the status of all the AIR classes, that extend framework classes?
I believe these have already been donated take a look at the airframwork directory in frameworks/projects.
> This is not strictly speaking a documentation issue, but, considering that
> WindowedApplication depends on mx.core.Application, which is under control
> of Apache (now / soon), how is that going to be resolved?
WindowedApplication.as has been donated and can be found at /src/mx/core in the above project
> - I'm not in favor of doing changes, if it's not absolutely needed, but
> ASDoc is a... *sigh* well, it's easier to throw away, then to fix it
ASdocs is currently useful so until something better comes along I don't think it should be thrown away. The compiler can output XML version of the docs which may be useful. This is how the FAT swf that Flash Builder uses for documentation are created.
> really... I mean, of course it kind of works, but the HTML output it
> generates is of so very low quality,
If you referring to the templates, navigation etc once the asdoc directory is donated I'm sure we can do some work on that. You might want to take a look at the asdoc/templates directory in the open source version of the SDK . It generates the HTML from XSLT templates.
> - There was that AIR program used for aggregated documentation of all Adobe
> products.
I have no idea if this will be donated, not sure if it's even on the "list".
> - Are there any ideas about what / what kind of documentation / user
> interaction is Apache going to provide to the users? Is it going to
> leverage user manuals?
I think someone involved with Spoon project might be able answer that in a bit more detail as I think they have some ideas about that going forward.
Thanks,
Justin
Re: Language Reference Online Materials
Posted by Abdul Sattar <sa...@gmail.com>.
Thanks for clarifications.
Regards,
--
Abdul Sattar
(Director IT & Operations)
0321-6433805
www.powersoft.com.pk
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
Sorry for double post. Just to better illustrate the case, there's this
famous story about Churchill:
During the Second World War, Winston Churchill’s finance minister said
Britain should cut arts funding to support the war effort. Churchill’s
response: “Then what are we fighting for?”
Same with running programs in Wine: well, maybe it is possible, but it
ultimately defies the reason of running the said programs on Linux. Same
well you could say that programs written for KDE are crossplatform because
it is possible to install KDE on most major operating systems...
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
Abdul, you probably didn't understand my comment. AIR developers are people
developing AIR runtime, not people using it (developing for AIR).
In other words: there is zero gain for me (as someone who would want to
develop for AIR for Linux), because it doesn't run there, unless Linux
mimics Windows - which is something I'm trying to avoid. And there is
nothing to make it better for people who develop AIR runtime, because they
still develop for Windows. This is a typical example of Hobson's choice:
either get something you don't need, or get nothing at all.
It's not because Wine is bad or anything - it's because it is on purpose
made to prevent me from using what I want/need to use. Simple example: I
want to assume in my applications that colon is an allowed character in a
file name - because I'm allowed to do so by Unix standards, more over, I
need this assumption because my program is trying to identify threats /
spoofs coming from uploaded files. When using Wine I'm not allowed to make
such assumption, because Wine purposely behaves like Windows, where colons
aren't allowed in file names. This is not the only example - just something
I could think at the moment.
This comment didn't include you in either category... just saying it, if
it's still not clear for w/e reason.
Best.
Oleg
Re: Language Reference Online Materials
Posted by Abdul Sattar <sa...@gmail.com>.
Yes. It is not perfect but it is good to have something than nothing. I
hope some day, Adobe will reconsider their decision.
> This is kind of Hobson's choice... I don't see how it makes it better,
> neither for me,* nor for the AIR developers...*
> Best.
> Oleg
Please just speak for yourself, do not include others in your opinions.
Regards,
--
Abdul Sattar
(Director IT & Operations)
0321-6433805
www.powersoft.com.pk
Re: Language Reference Online Materials
Posted by aYo ~ <ay...@binitie.com>.
On 22 March 2012 20:42, Left Right <ol...@gmail.com> wrote:
> > Adobe AIR 3 apps on linux run pretty good under Wine 1.4. :)
> >
> > This is kind of Hobson's choice... I don't see how it makes it better,
> neither for me, nor for the AIR developers...
>
> Its nice to know - but I have to agree with Oleg - never really been fond
of using Wine
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
> Adobe AIR 3 apps on linux run pretty good under Wine 1.4. :)
>
> This is kind of Hobson's choice... I don't see how it makes it better,
neither for me, nor for the AIR developers...
Best.
Oleg
Re: Language Reference Online Materials
Posted by Abdul Sattar <sa...@gmail.com>.
Adobe AIR 3 apps on linux run pretty good under Wine 1.4. :)
--
Abdul Sattar
(Director IT & Operations)
0321-6433805
www.powersoft.com.pk
Re: Language Reference Online Materials
Posted by Alex Harui <ah...@adobe.com>.
On 3/21/12 11:24 AM, "olegsivokon@gmail.com" <ol...@gmail.com> wrote:
> I'm with Spolsky on this one: I.e. I think it's too tedious to re-read the
> entire conversation preceding this message in every message, but I didn't
> know there are such rules. I'm sorry if I violated them.
You are a smart enough guy to identify patterns. See how I removed
everything you wrote except the fewest sentences possible? Apache agrees
with Spolsky. That's the protocol. Try to avoid top-posting and completely
copying the old message.
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
I'm with Spolsky on this one: I.e. I think it's too tedious to re-read the
entire conversation preceding this message in every message, but I didn't
know there are such rules. I'm sorry if I violated them.
AIR on Linux is no longer supported, but it has never existed for amd64
architecture. The only variant there was for i386. If you wanted to use it
on amd64, you'd need to hack your system to install 32-bit compatibility
libraries with analogous of their 64-bit counterparts. This had a tendency
of breaking other things... There has never been an official Linux package
for AIR for any kind of Linux. The thing that existed was a collection of
several binaries and a long list of DIY instructions for installing it.
The "tested" versions of AIR target Linux releases which are no longer
supported, for instance, the version targeting Ubuntu is for Ubuntu 9.04
(current version is 11.10, but 12.04 is also available). The 10.04 will no
longer be maintained in about a year from now and 9.04 is not maintained
for about two years already. So finding the corresponding libnss and other
SSL-related libraries of the proper version is increasingly difficult.
Given you have no source code, the program is practically dead today.
Finally, I don't know what version is required for CHC to run because the
AIR web installer simply won't launch for me, and there's no other way to
get it.
Best.
Oleg
On Wed, Mar 21, 2012 at 1:44 PM, Alex Harui <ah...@adobe.com> wrote:
> Oleg, you have a reputation for writing verbosely and writing often.
> Please
> respect the Apache protocol of leaving snippets of what you are replying
> to.
>
>
> On 3/21/12 10:15 AM, "olegsivokon@gmail.com" <ol...@gmail.com>
> wrote:
>
> > I didn't like it - that's true, besides, I can't even use it, since
> there's
> > no AIR for Linux,
> By "no AIR for Linux", are you implying that app required Air 2.7 or 3 or
> whatever?
>
> > Imagine, once we have Flex
> > documentation under control and decide to remove some functions this
> > application depends on - what happens then? Will angry Adobe community
> > stalk us and demand that we put it back? Or will Adobe just put up with
> the
> > changes / have their own version?
> The Adobe community will continue to use the one they have. If Apache Flex
> is missing something I expect the community to tell us and others in the
> community to respond if they can. Popular requests will likely get served.
>
> --
> Alex Harui
> Flex SDK Team
> Adobe Systems, Inc.
> http://blogs.adobe.com/aharui
>
>
Re: Language Reference Online Materials
Posted by Alex Harui <ah...@adobe.com>.
Oleg, you have a reputation for writing verbosely and writing often. Please
respect the Apache protocol of leaving snippets of what you are replying to.
On 3/21/12 10:15 AM, "olegsivokon@gmail.com" <ol...@gmail.com> wrote:
> I didn't like it - that's true, besides, I can't even use it, since there's
> no AIR for Linux,
By "no AIR for Linux", are you implying that app required Air 2.7 or 3 or
whatever?
> Imagine, once we have Flex
> documentation under control and decide to remove some functions this
> application depends on - what happens then? Will angry Adobe community
> stalk us and demand that we put it back? Or will Adobe just put up with the
> changes / have their own version?
The Adobe community will continue to use the one they have. If Apache Flex
is missing something I expect the community to tell us and others in the
community to respond if they can. Popular requests will likely get served.
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
I didn't like it - that's true, besides, I can't even use it, since there's
no AIR for Linux, so, even if it got improved, I won't probably discover
that... :) However, it depends on the help materials to be generated in a
certain way, so that's a dependency. Imagine, once we have Flex
documentation under control and decide to remove some functions this
application depends on - what happens then? Will angry Adobe community
stalk us and demand that we put it back? Or will Adobe just put up with the
changes / have their own version?
Best.
Oleg
Re: Language Reference Online Materials
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> No-no, you misunderstood me re' MXML language reference. This is what I
> meant: http://opensource.adobe.com/wiki/display/flexsdk/MXML+2009.
I'm sure we can ask for this to be donated and then update/modify as required. Adobe have stated support Flex for a minimum of 5 years so these pages are unlikely to go away overnight.
Thanks,
Justin
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
No-no, you misunderstood me re' MXML language reference. This is what I
meant: http://opensource.adobe.com/wiki/display/flexsdk/MXML+2009 . I.e. a
document that explains hot to use two-way bindings, how to embed localized
resources in an MXML document, how to document MXML code and so on. The
document that explains how to use MXML, not how to use components in MXML
template.
But, OK, I see that there's nothing certain yet, so I'll probably have to
wait until it all will find its master.
Best.
Oleg
Re: Language Reference Online Materials
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> Well, the docs are not distributed as binaries, you need to compile them
And currently neither are the framework swcs you have to compile them yourself as well. I'm sure first off people will host them somewhere and in the future Apache will host them. As I said it's early days and the infrastructure isn't set up yet but that doesn't mean it wont happen.
> There are also other documentation parts which are *stuck* in between - all
> the command line help for SDK utilities such as mxmlc, compc, asdoc, adt,
> adl, swfdump, fdb
As they not donated yet it's a little hard to say what will happen there. We'll have to see what comes with the donated code and then work out what needs to be done.
> I'm not aware of any MXML language reference, except the online page I've
> posted here before.
The asdocs build script generates these.
Thanks,
Justin
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
Well, the docs are not distributed as binaries, you need to compile them
(not every one who can read the documentation necessarily knows how to
compile it). You may only want to install (download) documentation, w/o the
entire SDK to things like kindle for example etc.
There are also other documentation parts which are *stuck* in between - all
the command line help for SDK utilities such as mxmlc, compc, asdoc, adt,
adl, swfdump, fdb - they are *kind of* documented, but the documentation is
scattered over Flex Developer Manual and other similar documents. It's
common to expect man/info documentation from a program such as a compiler
for example... but I don't think such thing ever existed.
I'm not aware of any MXML language reference, except the online page I've
posted here before. Same for other smaller language/template extensions -
the format of the services-config XML, the format of the AIR manifest XML
etc. These all aren't covered by AS3 language reference, but would need a
separate body of documentation... well, I guess
Best.
Oleg
Re: Language Reference Online Materials
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> Finally, no help is distributed with SDK today. I mean, of course there is
> documentation in the source code and it is available as code hinting by
> using "fat swcs", but there's no separate body of documentation (although,
> there is ASDocs target in the framework builds).
The ASdoc directory builds a set of documentation in HTML from the source code (look at it's build.xml). The "fat swcs" are generated from the normal framework SDK build process.
The generated HTML docs are comprehensive and more than helpful. I'm really not sure what the issue is here.
> Is Apache Flex going to provide Flex language reference as a separate download
As far as it being a separate download from Apache I'd assume that is possible in the future (as well as compiled builds), currently it's early days and the infrastructure hasn't been set up yet (and we're waiting on donating of the asdoc directory).
If there's an issue with the current documentation please contribute something. If you have any questions or need help in doing so just ask I'm sure there's people (including myself) willing to help. It wouldn't be too hard to take what we currently have and produce it in another format pdf, epub book, android app etc etc
Thanks,
Justin
Re: Language Reference Online Materials
Posted by Alex Harui <ah...@adobe.com>.
On 3/21/12 1:09 AM, "olegsivokon@gmail.com" <ol...@gmail.com> wrote:
> When I was talking about an "AIR help application" I meant this:
> http://www.adobe.com/support/chc/ (CHC). I didn't mean it may be donated
> because it is more of the Creative Suite thing then anything specific to
> Flex.
>
That is not on the list to be donated. Plus, IIRC, you didn't like it :-)
If we hear a lot of cries for it, we can look into it.
The Adobe community there will not be tied to Apache and vice versa. I hope
all the people from there who care about Flex will also join us at Apache.
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui
Re: Language Reference Online Materials
Posted by Left Right <ol...@gmail.com>.
When I was talking about an "AIR help application" I meant this:
http://www.adobe.com/support/chc/ (CHC). I didn't mean it may be donated
because it is more of the Creative Suite thing then anything specific to
Flex.
I was asking these questions rather because: Flex help is used by other
applications (like CHC, but not only), and those applications aren't under
Apache control. These applications may expect certain format, or maybe even
certain process of documentation generation. If we are going to make
changes to ASDocs templates, for example, should we consider other use
cases, which aren't part of the SDK project? What if in the future plan we
would like to [this is theoretical, but again, not impossible] move to
using NaturalDocs instead of ASCocs, will it be OK, given and it's
technically possible for the existing SDK code. What if we saw HaXe port as
a viable alternative - patching ASDocs to work with HaXe may be in fact
more time consuming than generating documentation using other tools...
Finally, no help is distributed with SDK today. I mean, of course there is
documentation in the source code and it is available as code hinting by
using "fat swcs", but there's no separate body of documentation (although,
there is ASDocs target in the framework builds). So, what will be the
destiny of the ASDocs target? Is Apache Flex going to provide Flex language
reference as a separate download?
Best.
Oleg
Re: Language Reference Online Materials
Posted by Alex Harui <ah...@adobe.com>.
On 3/20/12 2:59 PM, "olegsivokon@gmail.com" <ol...@gmail.com> wrote:
> I was wondering, how much and if at all, and if not this list, then who is
> responsible for the documentation pages.
Apache Flex is only responsible for documentation of classes in its
repository. If you want to offer to maintain a documentation project for
the Adobe classes, I don't think anyone will stop you.
>
> So, my questions are:
> - if I find documentation related bugs, who do I tell about it? What's the
> process / who's responsible for putting stuff online / is Adobe going to
> provide aggregated documentation on projects it donated?
Adobe is responsible for classes it ships. Same for Apache Flex.
> - What is the status of all the AIR classes, that extend framework classes?
> This is not strictly speaking a documentation issue, but, considering that
> WindowedApplication depends on mx.core.Application, which is under control
> of Apache (now / soon), how is that going to be resolved? I'm wondering in
> particular about documentation, but, obviously, there are other aspects of
> it too.
WindowedApplication is in the Apache SVN. It was part of the initial
framework donation.
> - I'm not in favor of doing changes, if it's not absolutely needed, but
> ASDoc is a... *sigh* well, it's easier to throw away, then to fix it,
> really... I mean, of course it kind of works, but the HTML output it
> generates is of so very low quality, you want to cry, and fixing it is not
> particularly easy...
Apache is about doing. If you don't like it, provide a new documentation
engine and convince folks to use it.
> - There was that AIR program used for aggregated documentation of all Adobe
> products. It used to include Flex framework classes. What happens to it?
> This program was / is quite *controversial* one - in a sense, no one seemed
> to like her, and as Adobe would explain, it was a result of budget cuts -
> so that documentation could be rolled out for everyone together, rather
> then every project handling it's own documentation separately. So will this
> group be responsible for integrating with that application? IIRC a lot of
> people were in favor of Eclipse integrated help. Some were making cfh
> compiles for Windows etc. because that AIR application wasn't really
> usable. So, is this group bound by any promises to keep that thing alive?
I don't know what you are talking about. Please provide more detail. IMHO,
Apache Flex is not responsible for any Adobe documentation format. We can
provide our own if we want to. Naturally, it will be easier to leverage the
ASDoc comments in the source so that will likely be the starting point. And
again, if you don't like it, start your own documentation project.
> - Finally, there were online resources such as Flex Developer Manual, Flex
> User Manual. They were sided in a sense they discussed framework in
> connection to Flash Builder, but they are not making too many
> cross-references. Anyway, is Adobe going to keep that alive too, or is it
> under Apache jurisdiction now / soon?
Adobe is unlikely to retire any current documentation for 5 years as the
whitepaper indicated that Adobe Flex 4.6 support runs that long at a
minimum.
> - Just to elaborate on this, beside the manuals themselves, there exists a
> kind of forum / user provided feedback feature with community help etc.
> It's not particularly lively forum, yet there's daily activity of about 10
> messages a day. I'm not sure about what happens to this project, who's
> taking over it etc. Any thoughts?
Again, that is an Adobe thing. Apache Flex is not obligated to replicate it.
> - Are there any ideas about what / what kind of documentation / user
> interaction is Apache going to provide to the users? Is it going to
> leverage user manuals?
We will do what our members can do. Are you going to pitch in?
--
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui