Re: [FalconJX] Generating ASDoc

[Josh Tynjala <jo...@gmail.com>]

Search engine compatibility is one of the most basic requirements of
documentation, in my opinion. If you can't find a component/property/method
from Google, it's not very useful. I guess Google's crawler will run
JavaScript, though. With that in mind, maybe a non-static app can be used
for the API reference and still be indexed.

I think to do this right, the app needs to use the HTML history API. The
URL should update as you navigate to pages for different components, and
the back button needs to work too. Additionally, you need to be able to
copy-paste a URL and be able to return to the same content later. That
means that the server needs to know that each of these URLs should load the
exact same HTML. The JavaScript can figure out which JSON content to load.

example.com/docs/
example.com/docs/com.example.SomeComponent/
example.com/docs/com.example.AnotherComponent/

I know on Apache server, an .htaccess file gives you the ability to rewrite
URLs and load different content. In the example above, you might add one in
the docs folder that tells it to always load example.com/docs/index.html as
long as the request isn't for CSS/JSON/images.

- Josh

On Tue, Oct 11, 2016 at 11:23 AM, Alex Harui <ah...@adobe.com> wrote:

> Hi,
>
> FlexJS currently has its ASDoc generated by calling the ASDoc tool in the
> flex-sdk repo.  That's because the Falcon compiler code we got from Adobe
> had no implementation of ASDoc support.  We could probably go on like this
> forever, but it would be nicer to be able to have FlexJS/FalconJX not have
> any dependencies on the regular Flex SDK and ASDoc represents what might
> be the last dependency.  Also, I am still thinking that FlexJS may need a
> "smarter" doc tool that could be written in FlexJS and run on AIR or web
> that has more intelligent API filtering and searching.  And if I were to
> write such a tool, it might be easier to work from JSON data than a pile
> of xml or html files, which is what the current ASDoc tool does.
>
> I spent some time looking at how to get Falcon and/or FalconJX to output
> ASDoc comments into files.  Teaching Falcon to do it seemed really hard.
> The Falcon code is really designed to create a SWF, not a pile of files.
> It was a lot easier to get FalconJX to do it, since it already knows how
> to output a pile of JS files.  So I now have code that dumps the raw ASDoc
> comments in between some xml-like tags.
>
> Right now I'm thinking I will change the raw output to be JSON.  Or is
> there a good reason to keep the old xml output?  The flex-sdk ASDoc tool
> takes the xml output and uses Saxon as an XSLT to generate html.  Do we
> want to do that?  Or use Velocity or some other XSLT tool?  Or is JSON the
> new way to go?
>
> If we go with JSON, we probably don't need to add these other XSLT
> dependencies to Falcon/FalconJX.  And the new ASDoc FlexJS app would be a
> good test of our code.  I remember concerns in past discussions about not
> having HTML files for search engines to index, but isn't this sort of
> thing a standard problem for RIAs?  We probably need to have a default
> solution.
>
> One more note:  Because of the way FalconJX is architected (thanks again
> to Michael Schmalle), it is relatively simple to swap out a JSON emitter
> for an XML emitter.  I will probably just do a JSON emitter for now.  If
> someone really wants the XML/XSLT solution, they can work on it themselves.
>
> Thoughts?
> -Alex
>
>

Re: [FalconJX] Generating ASDoc

[Josh Tynjala <jo...@gmail.com>]

According to MDN and caniuse, IE 10 supports the history API.

https://developer.mozilla.org/en-US/docs/Web/API/History_API
http://caniuse.com/#feat=history

On caniuse, sometimes supported versions are hidden because they aren't
widely used anymore. It may look like IE 11 is the minimum version when you
first load the page, but they're saying that since IE 10 has 0.3%
marketshare, it doesn't matter anymore. Click Show All to see everything..

- Josh

On Tue, Oct 11, 2016 at 1:36 PM, Alex Harui <ah...@adobe.com> wrote:

>
>
> On 10/11/16, 1:10 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>
> >Anchors could probably be acceptable as a starting point in a minimum
> >viable product. That wouldn't need the server-side integration. However,
> >you don't need to use anchors with the HTML history API. Calling
> >pushState() changes the address bar without reloading.
>
> Cool!  Didn't know about pushState.  Is it true it doesn't work in IE<11?
>
> Having different implementations like this is why we are pushing on the
> whole beads & multiple-component-set support.  There is rarely only one
> way to do things.
>
> Thanks,
> -Alex
>
>

Re: [FalconJX] Generating ASDoc

[Alex Harui <ah...@adobe.com>]

On 10/11/16, 1:10 PM, "Josh Tynjala" <jo...@gmail.com> wrote:

>Anchors could probably be acceptable as a starting point in a minimum
>viable product. That wouldn't need the server-side integration. However,
>you don't need to use anchors with the HTML history API. Calling
>pushState() changes the address bar without reloading.

Cool!  Didn't know about pushState.  Is it true it doesn't work in IE<11?

Having different implementations like this is why we are pushing on the
whole beads & multiple-component-set support.  There is rarely only one
way to do things.

Thanks,
-Alex

Re: [FalconJX] Generating ASDoc

[Josh Tynjala <jo...@gmail.com>]

Anchors could probably be acceptable as a starting point in a minimum
viable product. That wouldn't need the server-side integration. However,
you don't need to use anchors with the HTML history API. Calling
pushState() changes the address bar without reloading.

- Josh

On Tue, Oct 11, 2016 at 12:26 PM, Alex Harui <ah...@adobe.com> wrote:

>
>
> On 10/11/16, 12:14 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>
> >Search engine compatibility is one of the most basic requirements of
> >documentation, in my opinion. If you can't find a
> >component/property/method
> >from Google, it's not very useful. I guess Google's crawler will run
> >JavaScript, though. With that in mind, maybe a non-static app can be used
> >for the API reference and still be indexed.
>
> I completely agree that ASDoc must be searchable.  I don't know how folks
> solve this problem, but IMO, it isn't limited to ASDoc.  Any RIA, written
> in Flex or not, like a shopping catalog, wants to be indexed by search
> engines.  Does anybody know what the popular solutions are?  Whatever they
> are, we want to try to package that as a component, so others can use it.
>
> >
> >I think to do this right, the app needs to use the HTML history API. The
> >URL should update as you navigate to pages for different components, and
> >the back button needs to work too. Additionally, you need to be able to
> >copy-paste a URL and be able to return to the same content later. That
> >means that the server needs to know that each of these URLs should load
> >the
> >exact same HTML. The JavaScript can figure out which JSON content to load.
> >
> >example.com/docs/
> >example.com/docs/com.example.SomeComponent/
> >example.com/docs/com.example.AnotherComponent/
>
> Yep, and we will need to component-ize such functionality for our
> downstream developers.
>
> >
> >I know on Apache server, an .htaccess file gives you the ability to
> >rewrite
> >URLs and load different content. In the example above, you might add one
> >in
> >the docs folder that tells it to always load example.com/docs/index.html
> >as
> >long as the request isn't for CSS/JSON/images.
>
> Again, I don't know what the popular solutions are.  Hopefully we have
> some knowledgable people in our community.  IIRC, for regular Flex, we
> used anchors instead of sub-directories, so the browser address bar showed:
>
> example.com/docs/index.html
> example.com/docs/index.html#com.example.SomeComponent/
> example.com/docs/index.html#com.example.AnotherComponent/
>
> I think you have to use anchors so the page isn't re-loaded.  But whatever
> solution(s) is popular, we want to encapsulate it for other app developers.
>
>
> -Alex
>
>

Re: [FalconJX] Generating ASDoc

[Alex Harui <ah...@adobe.com>]

On 10/11/16, 12:14 PM, "Josh Tynjala" <jo...@gmail.com> wrote:

>Search engine compatibility is one of the most basic requirements of
>documentation, in my opinion. If you can't find a
>component/property/method
>from Google, it's not very useful. I guess Google's crawler will run
>JavaScript, though. With that in mind, maybe a non-static app can be used
>for the API reference and still be indexed.

I completely agree that ASDoc must be searchable.  I don't know how folks
solve this problem, but IMO, it isn't limited to ASDoc.  Any RIA, written
in Flex or not, like a shopping catalog, wants to be indexed by search
engines.  Does anybody know what the popular solutions are?  Whatever they
are, we want to try to package that as a component, so others can use it.

>
>I think to do this right, the app needs to use the HTML history API. The
>URL should update as you navigate to pages for different components, and
>the back button needs to work too. Additionally, you need to be able to
>copy-paste a URL and be able to return to the same content later. That
>means that the server needs to know that each of these URLs should load
>the
>exact same HTML. The JavaScript can figure out which JSON content to load.
>
>example.com/docs/
>example.com/docs/com.example.SomeComponent/
>example.com/docs/com.example.AnotherComponent/

Yep, and we will need to component-ize such functionality for our
downstream developers.

>
>I know on Apache server, an .htaccess file gives you the ability to
>rewrite
>URLs and load different content. In the example above, you might add one
>in
>the docs folder that tells it to always load example.com/docs/index.html
>as
>long as the request isn't for CSS/JSON/images.

Again, I don't know what the popular solutions are.  Hopefully we have
some knowledgable people in our community.  IIRC, for regular Flex, we
used anchors instead of sub-directories, so the browser address bar showed:

example.com/docs/index.html
example.com/docs/index.html#com.example.SomeComponent/
example.com/docs/index.html#com.example.AnotherComponent/

I think you have to use anchors so the page isn't re-loaded.  But whatever
solution(s) is popular, we want to encapsulate it for other app developers.


-Alex