rb-appscript 0.3.0 → 0.4.0

data/CHANGES

@@ -1,3 +1,48 @@
+2007-08-17 -- 0.4.0 (beta 1)
+
+- renamed the following aem/appscript methods to be consistent with AppleScript:
+
+	start -> beginning
+	starts_with -> begins_with
+	does_not_start_with -> does_not_begin_with
+	start_transaction -> begin_transaction
+
+Users should update existing code as necessary.
+
+- aem and appscript no longer accept non-test references as test clauses. Previously, a reference such as 'its.visible' would automatically be expanded to the comparison test 'its.visible.eq(true)' as a convenience. However, this shortcut didn't apply when these non-test references appeared as arguments to the #and and #or logical test methods, which meant that this shortcut behaviour was inconsistent and potentially confusing; therefore it has been removed. Users should update existing code as necessary.
+
+- added AE::AEDesc#send_thread_safe; this is now used by AEM instead of AE::AEDesc.send to allow reply events to be received on non-main threads (note: this is a non-issue in non-threaded processes or in processes that only use Ruby 1.x's green threads within the main native thread, but as the additional overhead isn't noticeable it does no harm to make it the default behaviour anyway).
+
+- added AE::AEDesc#flatten and AE::AEDesc.unflatten for serialising AEDescs
+
+- added support for custom reference roots in AEM and Appscript
+
+- AEM::Application#inspect now displays correct class name when Application class is subclassed
+
+- Appscript::Reference#[] now accepts real references and aem specifiers as by-filter test clauses (previously only accepted GenericReference)
+
+- added note about rubygems to appscript manual; added rubygems support to sample scripts
+
+- aete parser no longer raises error if aete isn't fully parsed (i.e. same as AppleScript) [SI]
+
+- added Appscript::Reference#help
+
+
+2007-04-10 -- 0.3.1
+
+- 64-bit support in rbae.c [JB]
+
+- Terminology.dump will use 'ascrgdte' event to obtain aetes if AE.get_app_terminology is unavailable
+
+- added TypeUInt16, TypeUInt64 support to Codecs#unpack
+
+- added Codecs#pack_uint16; by default, this packs numbers in range (2**63)..(2**64 - 1) as 64-bit floats (lossy), but clients could override this to pack as TypeUInt64 where supported by OS and applications
+
+- changed timeout for ascrgdte event to 120 sec
+
+- terminology parser no longer errors on zero-length aetes
+
+
 2007-01-18 -- 0.3.0
 
 - removed 'AS' alias; client scripts should refer to Appscript module, e.g.:

data/README

@@ -27,7 +27,11 @@ Please note that the version of Ruby included with Mac OS X 10.4 is missing the
 ======================================================================
 NOTES
 
-- rb-appscript 0.3.0 contains a couple of API changes from rb-appscript 0.2.x; see the CHANGES file and documentation for details
+- rb-appscript 0.4.0 is the first beta release. Except for bug fixes, no further changes are planned prior to the 1.0 release.
+
+- rb-appscript 0.4.0 contains a couple of API changes from earlier versions; see the CHANGES file and documentation for details
+
+- rb-appscript 0.4.0  provides preliminary 64-bit support for OS X 10.5 in the following modules: AE, AEM, Appscript. Note that the OSAX module currently remains 32-bit only; this will be addressed after OS X 10.5 is released.
 
 ======================================================================
 AUTHOR

data/TODO

@@ -1,27 +1,7 @@
 TO DO
 
-- see if there's a way to provide a SafeObject base class for Appscript::Reference and Appscript::GenericReference that doesn't depend on inserting callbacks into Module (or are Rubyists fine with the current approach?)
+- Add a libxml2-based sdef parser for use by Terminology.dump, OSAX::ScriptingAddition in 64-bit Leopard as OSAGetAppTerminology is not available there. Also use weak binding for OSAGetAppTerminology, OSACopyScriptingDefinition in rbae.c
 
-- see if it's possible to work better with irb's autocomplete (autocomplete support is currently limited to start of a reference; not sure why)
+- can numbers in range (2**63)..(2**64 - 1) safely be packed as typeUInt64 on 10.5+? Or stick with packing those as lossy 64-bit floating point for compatibility?
 
-- ae/aem/appscript-defined exception classes aren't quite idiomatic Ruby
-
-- any additional tests
-
-- improve/polish documentation
-
-- see also TO DO comments in rbae.c
-
--------
-
-- _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.
-
-- support sending and receiving events on non-main threads
-
-- provide an example project (or source for) that uses ruby2exe to build a standalone 'applet'
-
-- any more built-in Ruby class<->AE type converters needed?
-
-- in AEM::CommandError, extract and report any kOSA... error parameters, if present
-
-- implement built-in help by bridging to osadict
+- _aem/connect.rb module refers directly to Send::Event instead of going via the AEM::Application::Event hook, which might cause problems when used in an OSA component or other situation where client needs to customise all event creation and/or dispatch.

data/doc/aem-manual/04_references.html

@@ -117,7 +117,7 @@ p ref
 
 <p><img src="aemreferenceinheritance.gif" title="aem reference class hierarchy" />
 
-<p>Note that the user shouldn't instantiate these classes directly; instead, aem will instantiate them as appropriate when the client calls the properties and methods of one of the three root objects - <code>app</code>, <code>con</code>, <code>its</code> - of of other aem reference objects.</p>
+<p>Note that the user shouldn't instantiate these classes directly; instead, aem will instantiate them as appropriate when the client calls the methods of other aem reference objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all aem references.</p>
 
 <p>In fact, it really isn't necessary to remember the reference class hierarchy at all, only to know which concrete classes implement which methods. All user-accessible properties and methods are defined by just four superclasses:</p>
 
@@ -154,7 +154,7 @@ p ref
 
     Methods:
 
-        start
+        beginning
             Result : InsertionSpecifier
 
         end
@@ -213,7 +213,7 @@ p ref
             val : anything
             Result : Test
     
-        starts_with(val) -- self starts with value
+        begins_with(val) -- self begins with value
             val : anything
             Result : Test
     
@@ -311,7 +311,7 @@ p ref
 <h3>Insertion location reference form</h3>
 
 <pre><code>InsertionSpecifier &lt; Specifier -- refers to insertion point before or after/at
-        start or end of element(s); e.g. ref.before</code></pre>
+        beginning or end of element(s); e.g. ref.before</code></pre>
 
 <h3>Property reference forms</h3>
 
@@ -350,14 +350,14 @@ ElementByRelativePosition &lt; SingleElement -- refers to the previous or next e
 <h3>Multiple element reference forms</h3>
 
 <pre><code>ElementsByRange &lt; MultipleElements -- refers to a range of elements
-        in the referenced container object(s) (including start and 
+        in the referenced container object(s) (including beginning and 
         end points); e.g. ref.by_range(AEM.con.elements('cpar').by_index(2),
                 AEM.con.elements('cpar').last)
 
 
 ElementsByFilter &lt; MultipleElements -- refers to all elements in the
         referenced container object(s) that fulfill a given condition; 
-        e.g. ref.by_filter(AEM.its.name.startswith('a'))
+        e.g. ref.by_filter(AEM.its.name.begins_with('a'))
 
 
 AllElements(MultipleElements) -- refers to all elements of 

data/doc/aem-manual/05_targettingapplications.html

@@ -61,8 +61,8 @@
 
         event(...) -- construct an Apple event (see next chapter for details)
 
-        start_transaction(session=nil) -- start a new transaction;
-                all Events constructed after start_transaction is
+        begin_transaction(session=nil) -- begin a new transaction;
+                all Events constructed after begin_transaction is
                 called will belong to the same transaction until
                 end_transaction or abort_transaction is called
             session : anything -- optional value identifying the 
@@ -104,7 +104,7 @@ KAE::TypeProcessSerialNumber</code></pre>
 
 <h2>Transactions</h2>
 
-<p>The <code>start_transaction</code> and <code>end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
+<p>The <code>begin_transaction</code> and <code>end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
 
 <p>Note that during a transaction, sending the application an event not created during that transaction will cause an error. Similarly, sending the application an event created during a transaction after that transaction has ended will cause an error.</p>
 

data/doc/aem-manual/07_findapp.html

@@ -25,7 +25,7 @@
 
 <h2>The <code>FindApp</code> module</h2>
 
-<p>The findapp module is used to obtain the full path to an application given it file name, bundle ID, or creator code. It exports the following functions:</p>
+<p>The <code>FindApp</code> module is used to obtain the full path to an application given it file name, bundle ID, or creator code. It exports the following functions:</p>
 
 <pre><code>by_name(name) -- Find the application with the given name. 
     name : string -- application's name, e.g. 'Finder.app'. The '.app' suffix

data/doc/appscript-manual/04_gettinghelp.html

@@ -20,7 +20,80 @@
 
 <!-- content -->
 <div id="content">
-<p>There are several ways to get information about applications' scripting interfaces: the <code>osadict</code> command-line tool, the ASDictionary application, and introspection.</p>
+<p>When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the built-in <code>help</code> method, the ASDictionary and <code>osadict</code> tools, and introspection.</p>
+
+
+
+<h2>Built-in <code>help</code> method</h2>
+
+<p>Appscript's <code>Application</code> and <code>Reference</code> classes include a powerful interactive help system that allows you to explore applications' scripting interfaces from within running scripts and Ruby's interactive <code>irb</code> interpreter. The <code>help</code> method can provide information on any suite, class, command or reference, and display the inheritance and relationships for a selected class or the entire application.</p>
+
+<div class="hilitebox">
+<p>Rb-appscript's built-in <code>help</code> method relies on the AppscriptHelpAgent application, available separately from the <a href="http://rb-appscript.rubyforge.org">appscript website</a>. See the AppscriptHelpAgent Read Me for installation instructions.</p>
+
+<p>Note that AppscriptHelpAgent is <em>not</em> required to access any other feature of rb-appscript, and its installation it is entirely optional. If AppscriptHelpAgent is not installed, invoking <code>help</code> will simply result in a "No help available" message being displayed and the script will continue to run as normal.</p>
+</div>
+
+<p>Built-in help is invoked by calling an <code>app</code> object's <code>help</code> method, optionally passing it a string indicating the type of information you want. For example, to view the help system's own help, call the <code>help</code> method with <code>'-h'</code> as its argument:</p>
+
+<pre><code>app('TextEdit').help('-h')</code></pre>
+
+<p>To print a description of any class or command or view inheritance and relationships, pass the <code>help</code> method a help string containing one or more of the following options:</p>
+
+<dl>
+<dt>-h</dt>
+<dd>show help</dd>
+<dt>-o</dt>
+<dd>overview of all suites, classes and commands</dd>
+<dt>-k</dt>
+<dd>list all built-in keywords (type names)</dd>
+<dt>-u [suite-name]</dt>
+<dd>summary of named suite or all suites</dd>
+<dt>-t [class-or-command-name]</dt>
+<dd>terminology for named class/command or current reference</dd>
+<dt>-i [class-name]</dt>
+<dd>inheritance tree for named class or all classes</dd>
+<dt>-r [class-name]</dt>
+<dd>one-to-one and one-to-many relationships for named class or current reference</dd>
+<dt>-s [property-or-element-name]</dt>
+<dd>values of properties and elements of object(s) currently referenced</dd>
+</dl>
+
+<p>Arguments (shown in brackets) are optional. Additional information on usage is available via <code>help('-h')</code>.</p>
+
+<p>Examples:</p>
+
+<pre><code>app('Finder').help('-o')
+app('Finder').help('-t window')
+app('Finder').files.help # same as help('-t')
+app('Finder').help('-d item -r folder -i container')
+app('Finder').files.help('-s')</code></pre>
+
+
+<p>To print detailed information on a specific reference, call its <code>help</code> method without arguments. Examples:</p>
+
+<pre><code>app('TextEdit').help
+app('TextEdit').version.help
+app('TextEdit').documents.help</code></pre>
+
+
+<p>To print detailed information on a specific command, call the <code>help</code> method on an application or reference object with the <code>-t</code> option followed by the command's name. Examples:</p>
+
+<pre><code>app('TextEdit').help('-t open')
+app('TextEdit').documents.help('-t count -t close')</code></pre>
+
+<div class="hilitebox">
+<p>Tip: <code>help</code> calls can safely be inserted at any point in a reference without disrupting your script's execution:</p>
+
+<pre><code>c = app('TextEdit')<strong>.help.help('-o -i -s')</strong>.documents.<strong>help</strong>[1]<strong>.help</strong>.count</code></pre>
+</div>
+
+
+
+<h2>ASDictionary</h2>
+
+<p>ASDictionary, available from the <a href="http://sourceforge.net/projects/appscript"> py-appscript website</a>, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.</p>
+
 
 
 <h2>osadict</h2>
@@ -49,14 +122,10 @@ iCal&gt; exit
 osadict -Ns rb StandardAdditions -t display dialog</code></pre>
 
 
-<h2>ASDictionary</h2>
-
-<p>ASDictionary, available from the <a href="http://sourceforge.net/projects/appscript"> py-appscript website</a>, renders application terminology resources in plain text and HTML formats. It provides a convenient drag-n-drop alternative to using the <code>osadict -H ...</code> command.</p>
-
 
 <h2>Introspection</h2>
 
-<p>Appscript's <code>Application</code> and <code>Reference</code> classes define several methods for obtaining information on the target application: </p>
+<p>Appscript's <code>Application</code> and <code>Reference</code> classes define several instance methods for obtaining information on the target application: </p>
 
 <dl>
 <dt><code>properties</code></dt>
@@ -75,7 +144,7 @@ osadict -Ns rb StandardAdditions -t display dialog</code></pre>
 <dd>Takes a command's name as string and returns the names of its parameters.</dd>
 </dl>
 
-<p>Like Ruby's standard <code>methods</code> method, all of these methods return a list of strings.</p>
+<p>As with Ruby's <code>Object#methods</code>, all of these methods return a list of strings.</p>
 
 <p>Examples</p>
 
@@ -88,6 +157,11 @@ p te.parameters('make')
 # ["at", "new", "with_data", "with_properties"]</code></pre>
 
 
+<h2>Notes</h2>
+
+<p>While appscript's documentation systems try to be reasonably forgiving of flawed or faulty terminology resources, there may be a few particularly problematic applications on which they fail. Should this happen, use ASDictionary to export the application's terminology in plain text format instead.</p>
+
+
 <h2>Other sources of help</h2>
 
 <ul>

data/doc/appscript-manual/05_keywordconversion.html

@@ -37,11 +37,14 @@
 
 <li>Names that match the methods already defined on appscript's Application and Reference classes have an underscore appended. The reserved method names are:
 
-<pre><code>abort_transaction             instance_variable_get
-after                         instance_variable_set
-and                           instance_variables
-any                           is_in
-before                        is_not_in
+<pre><code>abort_transaction             ignore
+after                         inspect
+and                           instance_eval
+any                           instance_variable_get
+before                        instance_variable_set
+begin_transaction             instance_variables
+beginning                     is_in
+begins_with                   is_not_in
 by_aem_app                    keywords
 by_creator                    last
 by_id                         launch
@@ -54,9 +57,9 @@ commands                      middle
 contains                      ne
 current                       next
 display                       not
-does_not_contain              object_id
-does_not_end_with             or
-does_not_start_with           parameters
+does_not_begin_with           object_id
+does_not_contain              or
+does_not_end_with             parameters
 dup                           previous
 elements                      private_methods
 end                           properties
@@ -65,16 +68,13 @@ ends_with                     public_methods
 eq                            result_type
 extend                        send
 first                         singleton_methods
-freeze                        start
-ge                            start_transaction
-gt                            starts_with
-hash                          taint
-help                          timeout
-ID                            to_a
-id                            to_s
-ignore                        type
-inspect                       untaint
-instance_eval                 wait_reply</code></pre>
+freeze                        taint
+ge                            timeout
+gt                            to_a
+hash                          to_s
+help                          type
+ID                            untaint
+id                            wait_reply</code></pre>
 </div>
 </li>
 </ul>

data/doc/appscript-manual/07_applicationobjects.html

@@ -48,7 +48,7 @@ app.current # the host process</code></pre>
 
 <dl>
 <dt><code>name</code></dt>
-<dd>The application's filename or POSIX path, e.g. <code>'TextEdit'</code>, <code>'TextEdit.app'</code>, <code>'/Applications/TextEdit.app'</code>. Where a filename is provided, appscript uses LaunchServices to locate the application. Paths beginning with <code>~</code>, e.g. <code>'~/Dev/MyApp.app'</code>, will be expanded automatically. An <code>.app</code> suffix is optional. For example, given the name <code>'TextEdit'</code>, appscript will first search for an application with that exact name. If none is found, it'll automatically add a <code>.app</code> suffix (<code>'TextEdit.app'</code>) and try again.</dd>
+<dd>The application's filename or POSIX path, e.g. <code>'TextEdit'</code>, <code>'TextEdit.app'</code>, <code>'/Applications/TextEdit.app'</code>. Where a filename is provided, appscript uses LaunchServices to locate the application. An <code>.app</code> suffix is optional. e.g. Given the name <code>'TextEdit'</code>, appscript first searches for an application with that exact filename; if none is found, it automatically adds an <code>.app</code> suffix (<code>'TextEdit.app'</code>) and tries again.</dd>
 
 <dt><code>id</code></dt>
 <dd>The application's bundle id, e.g. <code>'com.apple.textedit'</code>. Cocoa applications often have unique bundle ids.</dd> 
@@ -131,11 +131,11 @@ set(reference, :to =&gt; value) -- Set an object's data.
 
 <h2>Transaction support</h2>
 
-<p>Application objects implement three additional methods, <code>start_transaction</code>, <code>end_transaction</code> and <code>abort_transaction</code> that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro.</p>
+<p>Application objects implement three additional methods, <code>begin_transaction</code>, <code>end_transaction</code> and <code>abort_transaction</code> that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro.</p>
 
-<p>Once the application object's <code>start_transaction</code> method is called, all subsequent commands to that application will be sent as part of the same transaction until <code>end_transaction</code> or <code>abort_transaction</code> is called.</p>
+<p>Once the application object's <code>begin_transaction</code> method is called, all subsequent commands to that application will be sent as part of the same transaction until <code>end_transaction</code> or <code>abort_transaction</code> is called.</p>
 
-<p>The <code>start_transaction</code> method takes an optional <code>session</code> argument that indicates the specific transaction session to open (in applications that support this).</p>
+<p>The <code>begin_transaction</code> method takes an optional <code>session</code> argument that indicates the specific transaction session to open (in applications that support this).</p>
 
 <p class="hilitebox">Remember to call <code>end_transaction</code> or <code>abort_transaction</code> at the end of every transaction. (This includes transactions interrupted by a raised exception.) If a transaction is accidentally left open, appscript will try to end it automatically when the application object is garbage-collected, but this is not guaranteed to succeed.</p>
 

data/doc/appscript-manual/08_realvsgenericreferences.html

@@ -36,11 +36,11 @@ app.by_url('eppc://my-mac.local/Finder').home.folders.name</code></pre>
 
 <pre><code>app.documents.end
 con.word[3]
-its.name.starts_with('d')</code></pre>
+its.name.begins_with('d')</code></pre>
 
 <p>Generic references are only evaluated when used used within real references, either as selectors:</p>
 
-<pre><code>app('Finder').home.folders[<em>its.name.starts_with('d')</em>].get
+<pre><code>app('Finder').home.folders[<em>its.name.begins_with('d')</em>].get
 
 app('Tex-Edit Plus').windows[1].text[<em>con.words[2]</em>, <em>con.words[-2]</em>].get</code></pre>
 

data/doc/appscript-manual/09_referenceforms.html

@@ -106,7 +106,7 @@ files.any</code></pre>
                                        before the specified element
 elements[selector].next(class) -- nearest element of a given class to appear 
                                    after the specified element
-        class : Symbol -- class of element (see <a href="4_classesandenums.html">Classes and Enumerated Types</a>)</code></pre>
+        class : Symbol -- class of element (see <a href="06_classesandenums.html">Classes and Enumerated Types</a>)</code></pre>
 
 <p>Examples:</p>
 <pre><code>words[3].next(:word)
@@ -115,11 +115,11 @@ paragraphs[-1].previous(:character)</code></pre>
 
 <h3>by Range</h3>
 
-<p>Range references select all elements between and including two references indicating the start and end of the range. The start and end references are normally declared relative to the container of the elements being selected. Appscript defines an object, <code>con</code> (short for 'container'), to indicate this container; for example, to indicate the third paragraph of the currrent container object:</p>
+<p>Range references select all elements between and including two references indicating the start and stop of the range. The start and stop references are normally declared relative to the container of the elements being selected. Appscript defines an object, <code>con</code> (short for 'container'), to indicate this container; for example, to indicate the third paragraph of the currrent container object:</p>
 
 <pre><code>con.paragraphs[3]</code></pre>
 
-<p>For convenience, the range reference also allows start and end references to be written in shorthand form where their element class is the same as the elements being selected; thus:</p>
+<p>For convenience, the range reference also allows start and stop references to be written in shorthand form where their element class is the same as the elements being selected; thus:</p>
 
 <pre><code>ref.paragraphs[con.paragraphs[3], con.paragraphs[-1]]</code></pre>
 
@@ -132,16 +132,16 @@ paragraphs[-1].previous(:character)</code></pre>
 <pre><code>ref.words[con.characters[5], con.paragraphs[-2]]</code></pre>
 
 <p>Syntax:</p>
-<pre><code>elements[start, end]
-        start : Fixnum | Bignum | String | Reference -- start of range
-        end : Fixnum | Bignum | String | Reference -- end of range</code></pre>
+<pre><code>elements[start, stop]
+        start : Fixnum | Bignum | String | Reference -- beginning of range
+        stop : Fixnum | Bignum | String | Reference -- end of range</code></pre>
 	
 <p>Examples:</p>
 <pre><code>folders['Documents', 'Movies']
 documents[1, 3]
 text[con.characters[5], con.words[-2]]</code></pre>
 
-<p class="hilitebox">Note: ranges are specified as [start-position, <em>end-position</em>] (AEM-style ranges), not [start-position, <em>length</em>] (Ruby-style ranges).</p>
+<p class="hilitebox">Note: ranges are specified as [start-position, <em>stop-position</em>] (AEM-style ranges), not [start-position, <em>length</em>] (Ruby-style ranges).</p>
 
 <h3>by Filter</h3>
 
@@ -167,11 +167,11 @@ reference.eq(value) # ==
 reference.ne(value) # !=
 reference.gt(value) # &gt;
 reference.ge(value) # &gt;=
-reference.starts_with(value)
+reference.begins_with(value)
 reference.ends_with(value)
 reference.contains(value)
 reference.is_in(value)
-reference.does_not_start_with(value)
+reference.does_not_begin_with(value)
 reference.does_not_end_with(value)
 reference.does_not_contain(value)
 reference.is_not_in(value)
@@ -180,11 +180,9 @@ reference.is_not_in(value)
 <p>Examples:</p>
 <pre><code>its.eq('')
 its.size.gt(1024)
-its.words.first.starts_with('A')
+its.words.first.begins_with('A')
 its.characters.first.eq(its.characters.last)</code></pre>
 
-<p>Note that Boolean comparison tests can be written as either <code>reference.eq(true)</code> or just <code>reference</code>, e.g. <code>folderRef.files[its.locked]</code></p></li>
-
 <li><p>Zero or more logical tests, implemented as properties/methods on conditional tests. The <code>and</code> and <code>or</code> methods take one or more conditional or logic tests as arguments.</p>
 
 <p>Syntax:</p>
@@ -195,7 +193,7 @@ test.not</code></pre>
 <p>Examples:</p>
 <pre><code>its.eq('').not
 its.size.gt(1024).and(its.size.lt(10240))
-its.words[1].starts_with('A').or(
+its.words[1].begins_with('A').or(
     its.words[2].contains('ce'),
     its.words[1].eq('Foo'))</code></pre></li>
 </ul>
@@ -207,7 +205,7 @@ its.words[1].starts_with('A').or(
 <p>Insertion locations can be specified at the beginning or end of all elements, or before or after a specified element or element range.</p>
 
 <p>Syntax:</p>
-<pre><code>elements.start
+<pre><code>elements.beginning
 elements.end
 elements[selector].before
 elements[selector].after</code></pre>