Community Documentation Projects

So when I started this forum few years ago, the idea was about having a good forum where people can talk about ActionScript 3.0 and related subjects

something not just there while there is hype and gone the next day when it’s not anymore “a la mode”

something that stay around and is of somewhat good quality, by that understand where people can actually write sample of source code with syntax coloring, where it is easy to copy/paste, where you can search, where there is no advertising or spam, etc.

Originally I wanted mainly a place where people can talk about redtamarin stuff but rethinking about it I just thought “what the hell let’s just include everything AS3”, hence here as3lang community forums.


But other things happened right and left.

First, as a developer I think having access to a language specification is quite important,
ok maybe not something you will refer to every day, but still something you do want to be able to consult from time to time, and there when you search “actionscript language specification” you should end up on this page

https://help.adobe.com/livedocs/specs/actionscript/3/wwhelp/wwhimpl/js/html/wwhelp.htm

but instead you get a 404

that’s why few years ago I started to copy it to at the very worst have an archive of that spec
github.com/as3lang/ActionScript3/wiki/Specification

oh sure you have the web archives

but if you click on the latest archive from August 7th 2017, the way the HTML is done you can only see the frontpage and not navigate the spec, that’s not good.

But ultimately some wiki pages on a github does not really do it for me.

So from that I went to “oh let’s just make a book”, and so from the same markdown content and using something like gitbook I started to copy and archives that kind of important documentation.


Second, again with Redtamarin, it is not only the language spec I needed, I also wanted to document the whole builtins of the language and cleanly indicate: here stuff for Flash, here for AIR and here for Redtamarin.

redtamarin_docs

In short, redoing the AS3LCR (ActionScript 3.0 Language and Component Reference)
that you all know located here help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/

Also, in this AS3LCR, I noticed few things not being documented anymore or other things that are available but considered “undocumented”, etc. so anyway I wanted to be able to publish the same doc and extend it with more docs and cover everything, yep even the undocumented stuff.

One example to keep it short, the Proxy class

It should be listed under the package flash.utils
flash.utils package, but it is nowhere to be found

If you point to the direct URL you can still find it here
Proxy class (at the bottom of the page you can see the doc was last generated Mon Nov 28 2011, 06:48 AM -08:00)

Also in that doc you can read

Note: Prior to Flash 11 and AIR 3.0, the Proxy class was a member of the flash.utils package. It is now a top-level class.

oh then we should find it in top-level then right ?

nope

it is not listed there
help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/package-detail.html

and you can not find it here either
help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/Proxy.html

I’m not sure for you but for me it is a huge problem, the Proxy class is highly useful and I would like to have some doc if/when I want to use it.

Publishing my own AS3LCR via Redtamarin, allow me then to keep the documentation around.


Third, but there is more.

See, in this AS3LCR, you can find link that reference other documentations

  • under Related API Elements
    you will find internal link that redirect to another part of the AS3LCR
  • under Learn more
    you will find external links to either other Adobe documentations or any other websites
  • under More examples
    you will find external links to other Adobe documentations that are directly related to ActionScript

that other Adobe documentations that are directly related to ActionScript
it is the ActionScript 3.0 Developer’s Guide

And I thought, oh wait … if this doc goes down there is a monumental piece of ActionScript knowledge that will be gone for good, and again that is no good.

For example, even if I duplicate perfectly or even better the AS3LCR
if you consult the Array class documentation

under more examples: Creating arrays
point to the page http://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee1.html (which is part of the “ActionScript 3.0 Developer’s Guide”)

Sure, for now I can use those links in my own documentation, but what if those other sites go down?

Ideally, ultimately, I would like to replace the link with a copy of this documentation to be very sure it never ever goes down.


That’s why I’m announcing the following projects which goal are purely based on preserving the documentation we have, and why not extend/improve it if the opportunity occurs.

From the Redtamarin project

  • a complete copy of the AS3LCR (within the Redtamarin sources)
  • and a reference manual that goes deeper on Redtamarin related subjects
    redsdk-book
    Redtamarin Software Development Kit Reference

From the as3lang project

  • as3spec-book
    ActionScript 3 Language Specification
  • as3esp-book
    ActionScript 3 Ecosystem Starter Pack
  • as3doc-book
    ActionScript 3 Documenting Projects
  • as3xpad-book
    ActionScript 3 Cross-Platform Applications Development
  • more to come (eg. a book that replicate the structure/content of the “ActionScript 3.0 Developer’s Guide”)

all those books will be hosted and available online at something like
books.as3lang.org or doc.as3lang.org or whatever

Those are empty repositories, I mainly written bit of this and there on local repos, I need to sync all that.

In principle, all books are structured based on gitbook (even if considered deprecated it is good enough for now), they will be mainly published in English, but other languages are possible and they are there to cover the basics of working with ActionScript 3.

Each books will be published as

  • HTML, gitbook frames
  • single page HTML
  • PDF
  • EPUB

And will be available online and as downloadable archives if you need a local copy.

Here few screenshots on the as3spec


That said, I’m no book writer and I do know all these are time consuming projects, so I was wondering who in the community would be interested in contributing ?
anything really: writing, copy editing, designing, etc.

The idea is to have reference manuals so instead of repeating the same things over and over on forums we can simply point to some nice documentation eg. documenting what Adobe does not really document (and will probably not), also preserving/copying already existing documentations that might vanish in the future.

As “reward” so far I can only offer the classic github kudos and your twitter/name/company listed under the contributors list, maybe later some documentation bounty I could sponsor, but that’s about it I guess.

Nothing urgent off course, depending on the motivation around it I will sync sooner or later on github, eg. if nobody care I will sync probably later on my own time, if some interests I will sync earlier so people can access the sources etc.

let me know what you think :slight_smile:

7 Likes

This is really cool. Losing the documentation is a major concern.

I’d be happy to volunteer!
I can do writing and copy editing (I’m a good writer).

I’ve also been saving a lot of documentation, so I have some things too.
Would love to throw in with this since this is really important. Thank you for doing this.

1 Like

I also offer to help if there are any contributions that can be made by beginners. I don’t know much about AS3 (I’m still trying to learn) but this is the only programming language I’ve ever seen and enjoyed using. :blush:

1 Like

What bothers me the most is that Adobe is as if it doesn’t want AS3 to survive as if it wants to get rid of it. I like writing in AS3 I totally dislike java & javasript. I cannot understand why such a flexible and powerful programming language is so war-ridden. I think that any official reference to AS3 will disappear very soon (from what we have seen started). Lynda.com has removed all content for AS3 & Flash had over 12 educational titles. So I find it important, if not our obligation, to support the process of saving as much information as we can. My English is not good enough, my time is limited but I want to contribute.

1 Like

Thank you all of you @alienmelon @Adriana and @SilverScript :slight_smile:

same logic here, I posted few archives on this forum but with time they get buried down so not practical in the end

on my side I got a lot of copy/archives/etc. (I wget entire blogs)
so yeah that would be great to get your stuff too, and maybe other people stuff too,
maybe try to organise them a little by categories etc.

don’t worry for that , I ll try to make the process as streamlined as possible and I will assist in case of bump on the road

maybe, but that’s the thing if a community produce the content then we own it, not Adobe
so whatever Adobe do or don’t it will not really matters


OK, I will try to put something in place so people can test the build/generation of the docs on their side, it should work on Windows/macOS/Linux and after that it will be about all of us talking a little to see what goes first, second, third, etc. depending on what people want to do.

In term of docs and contents, we will have few cases

  • Adobe doc already online
    so merely transcribing the content to markdown, copy the images, etc.
    in term of licensing those docs are under by-nc-sa so we can copy them without fearing we will lost the work later by some DMCA take down

    • those docs even if they start as simple copy, could then be extended later
    • or we could add new chapters on subjects not covered etc.
  • Content to be created and organised into categories
    think taking notes from forums, adobe release notes, maybe blog posts
    and rewriting/reorganising the content into a clean chapter
    for ex: “How to sign iOS Adobe AIR app”

  • Content from blog posts, maybe part of books
    and again rewriting/reorganising the content into a clean chapter by categories

It doesn’t have to be complex or take a lot of time right from the start
really we can start with empty chapters, and with time fill the content

as a practical example, from the “ActionScript 3.0 Developer’s Guide”
you have this page Basics of arrays

in gitbook/markdown you organize the chapters something like that

* [Core ActionScript Classes](01-core/README.md)
  * [Working with dates and times](01-core/DATETIME.md)
    * [Managing calendar dates and times](01-core/datetime/MCDT.md)
    * [Controlling time intervals](01-core/datetime/CTI.md)
    * [Date and time example: Simple analog clock](01-core/datetime/EXAMPLE.md)
  * [Working with strings](01-core/STRINGS.md)
    * etc.
  * [Working with arrays](01-core/ARRAYS.md)
    * [Basics of arrays](01-core/arrays/BASICS.md)

the folder structure is like this

.
|_ 01-core
       |_ README.md
       |_ DATETIME.md
       |_ STRINGS.md
       |_ ARRAYS.md
       |_ datetime
       |      |_ MCDT.md
       |      |_ ...
       |
       |_ strings
       |      |_ ...
       |
       |_ arrays
       |      |_ BASICS.md
       |      |_ ...
       |

so to edit the chapter “Basics of arrays”
you just need to edit 01-core/arrays/BASICS.md

note: we might even be able to have a tool that convert HTML to markdown to ease the process

form there you generate the doc
when you test locally
http://localhost:1234/as3dev/en/01-core/arrays/BASICS.html

and once the doc is uploaded to a server the URL path should be something like
http://books.as3lang.org/as3dev/en/01-core/arrays/BASICS.html


In short, it can be very granular, you will not have to edits 1000s of pages of content, already just editing 1 page this and there would help a lot

Also, if you feel like it, you could or someone else, add new chapters, from blog posts like
Constructing Arrays, Sorted Array, etc. by Jackson Dunstan and/or other posts/blogs/articles and/or your own additions

All the editing will be in markdown (GitHub-Flavored Markdown) and so will support basic table, and also syntax highlighting, so if you edited some wiki pages in Github you should be good to go :slight_smile:

And so bit by bit all those docs should be growing and hopefully motivate others to contribute too

Only thing I’m not completely sure is the publishing, I would not like to be a “blocker” for that (eg. having to push the content of the server once someone else edit something), so far I will try to make it automated as whoever edit content can push the content to the online website.

Let’s say if you were to publish something today the build would generate a date timestamp 20191002-11h51m00s for “2 October 2019 at 11 hour 51 minutes”

and on my side I would have the server always serve the last timestamp
that way if you edit something you don’t have to wait to see it online
(and yes it could be abused but in case of “bad content” we just need to delete the timestamp causing problems)

And finally in term of workflow you will have
$ build/book to generate the content
$ build/test to test it locally
$ build/publish to push it live on the server

with probably few more options to customise that
eg. if you are editing/testing one particular page, you don’t really need to generate the PDF and EBOOK right away

Also, once you push your updates on github the content will be also readable there (at the very worst if for some reasons it can not published online)

After that it is mainly a consensus about “where do we put what”

For example, in my particular case, I use a lot asdoc, and finding good documentation online is very hard if not impossible, Adobe have moved some online HTML doc to a big PDF, and I also noted a lot of tricks and hacks not necessarily documented for asdoc, so I was thinking publishing just a small book about documenting what you can do with asdoc.

That’s just me, but it can apply to anyone, if on your side you find some old blog posts have to be preserved, or some slides/PDF, or your own notes, or a particular way of doing etc.
that could fit in its own book if the content is big or could fit in chapter in an already existing book, or could be some “notes” added as comments on an already existing chapter, etc.

I’m not sure of everything, I’m just saying it is a community edited documentation so there should be room for everyone to bring stuff in the idea “this should not be forgotten, this should be preserved”

Feel free to add your input, I ll notify the forum when a couple of github repos are ready to work with, and thank you all for expressing your will to contribute :slight_smile:

2 Likes

Happy to contribute where I can!

I think documentation on reference and techniques is one of the things most missing from the community activity at the moment, so great to see anything that could replace the old adobe dev net articles (https://www.adobe.com/devnet/air.html). We tried to get some articles published there a few years ago and just met with road blocks.

2 Likes

great @marchbold to have you on board too :slight_smile:
I’m pretty sure your contribution on ANE and more would be fantastic

and yeah off course 100% agreeing documentation is the most missing part
such a shame because so much can be done with AS3/AIR/etc. and often people just don’t know it is possible or it is just there already available

I know all this is largely influenced by Redtamarin but I will really try to make it open on all the subjects around AS3 in general and yeah fast and easy publishing should be key

2 Likes

I’d gladly help in any way I can. I am beginner but always happy to learn…

2 Likes

So I made a little script :wink:

if by any chance you got as3shebang installed

you will need also pandoc and curl installed in your path

#!/usr/bin/env as3shebang

import shell.*;
import C.stdlib.*;
import C.sys.stat.*;


/* Note:

   usage:
   $ ./fetchpage https://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee3.html 01-core/arrays/BASICS.md

   file should be under
   01-core/arrays/BASICS.md


   alternative usage:
   $ ./fetchpage https://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee3.html BASICS.md

   in the current directory
   BASICS.md
*/

function usage()
{
    var str:String = "";
        str += "fetchpage url filepath\n";
        str += "fetch a URL from ActionScript 3.0 Developer’s Guide and autoconvert it to markdown\n";
        str += "\n";
        str += "usage:\n";
        str += "$ ./fetchpage https://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee3.html 01-core/arrays/BASICS.md\n";
        str += "\n";

    trace( str );
}


if( Program.argv.length == 0 )
{
    usage();
    exit( 0 );
}

// eg. https://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee3.html
var url:String = Program.argv[0];

if( (url == "") || (url == null) )
{
    trace( "missing first argument" );
    exit( 1 );
}

// eg. 01-core/arrays/BASICS.md
var target:String = Program.argv[1];

if( (target == "") || (target == null) )
{
    trace( "missing second argument" );
    exit( 1 );
}

var base:String = FileSystem.getBasenameFromPath( target );
var path:String = FileSystem.getDirectoryFromPath( target );
var original:String = "ORIGINAL.html";

if( base == path )
{
    path = "";
}

//trace( "base  = " + base );
//trace( "path  = " + path );

trace( "fetching " + url );
trace( "and convert it to markdown in " + target );

if( FileSystem.exists( target ) )
{
    FileSystem.remove( target );
}

if( (path != "") && !FileSystem.exists( path ) )
{
    mkdirp( path );
}

var tmp:String = base.split( ".md" ).join( ".html" );

// 1. fetch original and 1st pandoc filter
system( "curl --silent " + url + " | pandoc --from=html --to=markdown_strict -o " + original );


// 2. clean up HTML header, footer, etc.
var marker1:String = "<div id=\"content_wrapper\">";
var marker2:String = "<div id=\"userprefs\">";
var marker3:String = "<p>Flash Player 9 and later, Adobe AIR 1.0 and later</p>";

var from1:String = "<div id=\"ionCount\">"
var to1:String   = "id=\"chcImage\" /></a></p>";
var regex1:RegExp = new RegExp( from1 + "[^]*" + to1, "gm" );

var file:String = FileSystem.read( original );

    file = file.split( marker1 )[1];
    file = file.split( marker2 )[0];
    file = file.split( marker3 ).join( "" );
    file = file.replace( regex1, "" );

FileSystem.write( tmp, file );


// 3. 2nd pandoc filter
system( "cat " + tmp + " | pandoc --from=html --to=markdown_strict -o " + target );

// 4. clean up temp files
FileSystem.remove( original );
FileSystem.remove( tmp );

exit( 0 );

usage is
$ ./fetchpage https://help.adobe.com/en_US/as3/dev/WS5b3ccc516d4fbf351e63e3d118a9b90204-7ee3.html 01-core/arrays/BASICS.md

file should be under
01-core/arrays/BASICS.md

the result

Basics of arrays
================

Often in programming you’ll need to work with a set of items rather than
a single object. For example, in a music player application, you might
want to have a list of songs waiting to be played. You wouldn’t want to
have to create a separate variable for each song on that list. It would
be preferable to have all the Song objects together in a bundle, and be
able to work with them as a group.

An array is a programming element that acts as a container for a set of
items, such as a list of songs. Most commonly all the items in an array
are instances of the same class, but that is not a requirement in
ActionScript. The individual items in an array are known as the array’s
*elements* . You can think of an array as a file drawer for variables.
Variables can be added as elements in the array, which is like placing a
folder into the file drawer. You can work with the array as a single
variable (like carrying the whole drawer to a different location). You
can work with the variables as a group (like flipping through the
folders one by one searching for a piece of information). You can also
access them individually (like opening the drawer and selecting a single
folder).

For example, imagine you’re creating a music player application where a
user can select multiple songs and add them to a playlist. In your
ActionScript code, you have a method named addSongsToPlaylist() , which
accepts a single array as a parameter. No matter how many songs you want
to add to the list (a few, a lot, or even only one), you call the
addSongsToPlaylist() method only one time, passing it the array
containing the Song objects. Inside the addSongsToPlaylist() method, you
can use a loop to go through the array’s elements (the songs) one by one
and actually add them to the playlist.

The most common type of ActionScript array is an *indexed array* . In an
indexed array each item is stored in a numbered slot (known as an
*index* ). Items are accessed using the number, like an address. Indexed
arrays work well for most programming needs. The Array class is one
common class that’s used to represent an indexed array.

Often, an indexed array is used to store multiple items of the same type
(objects that are instances of the same class). The Array class doesn’t
have any means for restricting the type of items it contains. The Vector
class is a type of indexed array in which all the items in a single
array are the same type. Using a Vector instance instead of an Array
instance can also provide performance improvements and other benefits.
The Vector class is available starting with Flash Player 10 and Adobe
AIR 1.5.

A special use of an indexed array is a *multidimensional array* . A
multidimensional array is an indexed array whose elements are indexed
arrays (which in turn contain other elements).

Another type of array is an *associative array* , which uses a string
*key* instead of a numeric index to identify individual elements.
Finally, ActionScript 3.0 also includes the Dictionary class, which
represents a *dictionary* . A dictionary is an array that allows you to
use any type of object as a key to distinguish between elements.

#### Important concepts and terms

The following reference list contains important terms that you will
encounter when programming array and vector handling routines:

 Array   
An object that serves as a container to group multiple objects.

 Array access (\[\]) operator   
A pair of square brackets surrounding an index or key that uniquely
identifies an array element. This syntax is used after an array variable
name to specify a single element of the array rather than the entire
array.

 Associative array   
An array that uses string keys to identify individual elements.

 Base type   
The data type of the objects that a Vector instance is allowed to store.

 Dictionary   
An array whose items consist of pairs of objects, known as the key and
the value. The key is used instead of a numeric index to identify a
single element.

 Element   
A single item in an array.

 Index   
The numeric “address” used to identify a single element in an indexed
array.

 Indexed array   
The standard type of array that stores each element in a numbered
position, and uses the number (index) to identify individual elements.

 Key   
The string or object used to identify a single element in an associative
array or a dictionary.

 Multidimensional array   
An array containing items that are arrays rather than single values.

 T   
The standard convention that’s used in this documentation to represent
the base type of a Vector instance, whatever that base type happens to
be. The T convention is used to represent a class name, as shown in the
Type parameter description. (“T” stands for “type,” as in “data type.”).

 Type parameter   
The syntax that’s used with the Vector class name to specify the
Vector’s base type (the data type of the objects that it stores). The
syntax consists of a period ( . ), then the data type name surrounded by
angle brackets ( &lt;&gt; ). Put together, it looks like this:
Vector.&lt;T&gt; . In this documentation, the class specified in the
type parameter is represented generically as T .

 Vector   
A type of array whose elements are all instances of the same data type.


Not sure how it can works with all the pages, the result on this one is not bad
I will probably try to automatically fetch and convert some amount of pages to prefill the markdown, and if it works at the very worst people would just have to cleanup manually little bits this and there, but still better than to copy/paste everything by hand :smiley:

1 Like

thanks to you too @Harpwood and no worry I will make it beginner friendly

1 Like

The tourist season is over. Today I am going back to my home. In a couple of days I will be ready to work full time with my projects and of course If I am able to contribute in any way I can, to the community docs! Working remotely with a team sounds like an invaluable experience to me!

OK so a little follow up

about the “ActionScript 3.0 Developer’s Guide”

officially can be found here
https://help.adobe.com/en_US/as3/dev/index.html

but it had previous versions

Flash CS3 Documentation
http://livedocs.adobe.com/flash/9.0/main/wwhelp/wwhimpl/js/html/wwhelp.htm
archive

the archive is unexploitable “as is” because of the fucked up html structure

if someone has a copy of the files that can be viewed locally I’m interested (to cross reference with other docs)


and
Programming Adobe ActionScript 3.0 for Adobe Flash
http://help.adobe.com/en_US/ActionScript/3.0_ProgrammingAS3/
archive

actually returns a 404, the content is pretty similar to the “ActionScript 3.0 Developer’s Guide” but with a different layout of the chapters, the archive can be used to do cross-reference.

For ex, “ActionScript 3.0 Developer’s Guide” not talking about an earlier subject that this “Programming Adobe ActionScript 3.0 for Adobe Flash” takled about, we could then re-add this content.


and

Adobe Flex 4.6
http://help.adobe.com/en_US/flex/using/index.html
archive

some AS3LCR doc points to some of those pages that are not available anymore, only in archive

the classic redirect you get to the PDF
https://help.adobe.com/archive/en_US/flex/using/flex_4.6_help.pdf

There too, we could add some content to the “ActionScript 3.0 Developer’s Guide”


And finally the samples
https://www.adobe.com/devnet/flash/samples.html
archive

and thanks to web archive we can still download the numerous zip files
for ex FlashPlatformAS3DevGuideExamples.zip

if we then copy the doc we will also need to host those zip files for the samples
and include a link or links in the doc

1 Like