flex-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh Tynjala <joshtynj...@gmail.com>
Subject Re: [FalconJX] Generating ASDoc
Date Tue, 11 Oct 2016 19:14:03 GMT
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.


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 <aharui@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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message