\input texinfo
m4_include(m4.m4)
@tex
\global\def\linkcolor{0 0 1}  % blue
\global\def\urlcolor{0 0 1}   % blue
@end tex

@set EDITION 1.1
@set VERSION 1.1
@set UPDATED 29 May 2016
@set UPDATE-MONTH May 2016

@comment $Id@w{$}
@comment %**start of header
@comment @include version.texi
@settitle GNU Java Training Wheels @value{VERSION}
@syncodeindex pg cp
@comment %**end of header

@copying

This manual is for GNU Java Training Wheels (version @value{VERSION},
@value{UPDATED}), which is a system for making it easier for novices
to learn to program in the Java language.

Copyright @copyright{} 2016 Davin Pearson.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@titlepage
@title GNU Java Training Wheels
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Davin Pearson (@email{davin.pearson@@gmail.com})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Java Training Wheels

This manual is for GNU Java Training Wheels (version @value{VERSION},
@value{UPDATED}).

@end ifnottex

@menu
* About GNU Java Training Wheels::
* J.T.W. Proof of concept #1 A superfor macro::
* J.T.W. Proof of concept #2 file inclusion::
* J.T.W. Tutorials::
* Packages in J.T.W. and Java::
* GNU Free Documentation License::
* Passwords for the answers to the tutorials::
* Index::
@end menu

@node    About GNU Java Training Wheels
@chapter About GNU Java Training Wheels

@cindex About GNU Java Training Wheels

This document documents a new programming language written by me,
Davin Pearson (email: TT(davin EM(dot) pearson EM(at) gmail EM(dot)
com)) called EM(J.T.W.), short for EM(Java Training Wheels) for the
sole purpose of making it easier to learn to program in Java.  The
J.T.W. language has a similar syntax to Delphi, Pascal, BASIC and
JavaScript and therefore learning J.T.W. before or while learning Java
provides a less steep learning curve than learning Java from scratch.
For many reasons you might even prefer to program in J.T.W. rather
than Java.  Here is why you should learn J.T.W. before or while
learning Java:

@itemize

  @item The J.T.W. language is supported by a parser that
  troubleshoots problematic J.T.W. code with clear error messages.

  @cindex Trouble-shooting problematic J.T.W. constructs
  @cindex Problematic J.T.W. constructs, trouble-shooting

  @item The J.T.W. language compiles to Java in a natural and
  straightforward way so it is easy to learn Java once you know
  J.T.W..  See the following diagram for a comparison of the
  J.T.W. and Java build processes.

  @cindex Mapping from J.T.W. -> Java
  @cindex J.T.W. -> Java mapping

@example
m4_include(jtw-diagram.txt)
@end example

  m4_changequote(,)

  @item Pascal-style BEGIN DOTS END constructs are supported
  instead of C-style TT(SQU DOTS GLY) constructs which is more
  sensible especially for novices.

  @cindex Pascal-style BEGIN DOTS END construct versus the C-style SQU DOTS GLY construct

  @item A simple syntax for the MAIN FUNCTION: BEGINMAIN DOTS ENDMAIN
  rather than the rather cumbersome: TT(POBLIC STATIC VOID
  MAIN()(String[] args) SQU DOTS GLY).

  @cindex A simple syntax for the MAIN FUNCTION.
  @cindex MAIN FUNCTION, a simple syntax for.

  @item Class variables, properties, functions, methods and
  constructors are declared as such much like Delphi which makes your
  code look clearer.  Specifically there are new keywords CLASSVAR,
  CONSTRUCTOR, FUNCTION, METHOD and PROPERTY.

  @cindex CLASSVAR construct
  @cindex CONSTRUCTOR construct
  @cindex FUNCTION construct
  @cindex METHOD construct
  @cindex PROPERTY construct

  @item The Delphi/Pascal/JavaScript keyword VAR for clearer local
  variables.

  @cindex The Delphi/Pascal/JavaScript keyword VAR for clearer local variables
  @cindex VAR for clearer local variables

  @cindex The Pascal/BASIC keyword THEN for clearer IF statements
  @cindex THEN for clearer IF statements

  @item The Pascal/BASIC keyword THEN for clearer IF statements.

  @cindex BASIC style AND and OR constructs rather than Java's cumbersome BO(TT(&&)) BO(TT(||)) constructs.

  @cindex C++ style AND and OR constructs rather than Java's cumbersome BO(TT(&&)) BO(TT(||)) constructs.

  @cindex AND construct from BASIC and C++ in J.T.W.

  @cindex OR construct from BASIC and C++ in J.T.W.

  @item The BASIC and C++ style keywords AND and OR rather than Java's
  rather cumbersome: BO(TT(&&)) and BO(TT(||)).

  @cindex ELSEIF construct rather than ELSE IF

  @item The P.H.P. keyword ELSEIF is supported instead of Java's
  cumbersome ELSE IF.

  @cindex SUPERFOR macro

  @item As proof of concept, a SUPERFOR macro is presented for
  enhanced BASIC-style FUR loops.
  See @ref{J.T.W. Proof of concept #1 A superfor macro}.

  @cindex File inclusion in J.T.W.

  @item As proof of concept, file inclusion is supported so that you
  can spread a class across several files.  Natural divisions are
  methods.  Different methods can be placed in different source files
  for those situations where methods become large and unwieldy.  See

  @ref{J.T.W. Proof of concept #2 file inclusion}.

  m4_changequote([,])
  m4_undefine([NEW])

  @item BO(NEW!) As of J.T.W version 1.1, packages are now supported. See
  @ref{Packages in J.T.W. and Java}.

  m4_define([NEW],TT(BO(new)))

@end itemize

@node    J.T.W. Proof of concept #1 A superfor macro
@chapter J.T.W. Proof of concept #1 A superfor macro

@cindex SUPERFOR looping construct

m4_include(superfor.tesinfo)

@node    J.T.W. Proof of concept #2 file inclusion
@chapter J.T.W. Proof of concept #2 file inclusion

m4_include(file-inclusion.tesinfo)

@node    J.T.W. Tutorials
@chapter J.T.W. Tutorials

@cindex Davin Pearson's Personal Website @url{http://davin.50webs.com}

The following tutorials including full model answers can be found on
my Website at the following location:

@center @url{http://davin.50webs.com/J.T.W}

The advantage of using my online tutorials is that the tutorials have
superior BO(syntax) EM(highlighting) of the code examples.  See the
following link @ref{Passwords for the answers to the tutorials} for
the passwords on my Website.

@menu

* Tutorial 1 Your first program:: Your first program and introducing
functions, parameters, arguments, strings, TT(System.out.println) and
comments to give you enough basic J.T.W. to get you started.

* Tutorial 2 Introduction to programming in Java:: Introducing chars,
the difference between == and =, booleans, the IF (DOTS) THEN DOTS
ELSEIF (DOTS) DOTS ELSEIF (DOTS) DOTS ELSE DOTS construct, local
variables, ints, the for construct and teaching you how to call
existing methods of the TT(String) CLASS but not teaching you how to
write your own methods until Tutorial 9.

* Tutorial 3 superfor loops and for loops:: Introducing
TT(System.out.print) for printing without a trailing carriage return,
introducing the SUPERFOR construct, revising loops that use the FUR
construct, introducing doubles and revising ints and chars.

* Tutorial 4 Four looping constructs:: Other types of loops such as
SUPERFOR, WHILE and DU DOTS WHILE, and revising IF statements and FUR
loops. Learning what is the best of these four looping constructs.

* Tutorial 5 A beer drinking song:: Using all of the J.T.W. constructs
that you have learned so far to rewrite a song to be more
general-purpose.

* Tutorial 6 Class variables:: Introducing class variables which are
different from variables that are local to functions.

* Tutorial 7 Non-Object arrays:: Introducing non-object arrays that
are either single dimensional or multi dimensional using two different
initialization syntaxes and introducing function name overloading.

* Tutorial 8 Accessing functions and class variables from another class:: Learning how to
access functions from another class and introducing boolean arrays.

* Tutorial 9 Mapping class variables to instance variables (also known as properties) and functions to methods::

   This gives you the full power of O.O.P. (Object Oriented
   Programming) classes.  Introducing getter methods and references
   for accessing objects. Introducing the NULL keyword for
   representing no object and introducing the TT(toString) method,
   while explaining why this METHOD is better than any other METHOD or
   PROPERTY for debugging your code.

* Tutorial 10 Object arrays:: Introducing object arrays that are
either single-dimensional or multi-dimensional. Revising two different
initialization syntaxes from Tutorial 7 on non-object arrays.

* Tutorial 11 References to another class:: When classes have
references to objects of other classes in their properties then you
can set up relationships between different classes.

* Tutorial 12 Overloading methods:: Swapping the properties of
two objects, and converting methods to functions and vice-versa.

* Tutorial 13 More about references:: More questions about references.

@cindex Linked lists

* Tutorial 14 Linked lists:: When a class has a reference to itself as a
property then you can build linked lists out of objects of this
class. BO(WARNING:) Linked lists are tricky for novice programmers to
grasp.

* Tutorial 15 Introducing inheritance:: Introducing inheritance,
polymorphism, getter and setter methods, the INSTANCEOF keyword for
run-time type inquiry and introducing the Object class.  Introducing
the NULL keyword for representing no object and introducing the
TT(toString) method, while explaining why this METHOD is better than
any other METHOD or PROPERTY for debugging your code.

* Tutorial 16 More inheritance:: Showing you how inheritance can be used to reduce
the amount of duplication of code.

* Tutorial 17 Arrays inheritance and polymorphism:: Teaches why in
most cases it is better to use polymorphism rather than run-time type
inquiry.

* Tutorial 18 Advanced J.T.W.:: Mapping J.T.W. to Java and the
internal details of the J.T.W. system, including a EM(GNU Makefile).

@end menu

@node    Tutorial 1 Your first program
@section Tutorial 1 Your first program

m4_include(tutorial-01.tesinfo)

@node    Tutorial 2 Introduction to programming in Java
@section Tutorial 2 Introduction to programming in Java

m4_include(tutorial-02.tesinfo)

@node    Tutorial 3 superfor loops and for loops
@section Tutorial 3 superfor loops and for loops

m4_include(tutorial-03.tesinfo)

@node    Tutorial 4 Four looping constructs
@section Tutorial 4 Four looping constructs

m4_include(tutorial-04.tesinfo)

@node    Tutorial 5 A beer drinking song
@section Tutorial 5 A beer drinking song

m4_include(tutorial-05.tesinfo)

@node    Tutorial 6 Class variables
@section Tutorial 6 Class variables

m4_include(tutorial-06.tesinfo)

@node    Tutorial 7 Non-Object arrays
@section Tutorial 7 Non-Object arrays

m4_include(tutorial-07.tesinfo)

@node    Tutorial 8 Accessing functions and class variables from another class
@section Tutorial 8 Accessing functions and class variables from another class

m4_include(tutorial-08.tesinfo)

@node    Tutorial 9 Mapping class variables to instance variables (also known as properties) and functions to methods
@section Tutorial 9 Mapping class variables to instance variables (also known as properties) and functions to methods

m4_include(tutorial-09.tesinfo)

@node    Tutorial 10 Object arrays
@section Tutorial 10 Object arrays

m4_include(tutorial-10.tesinfo)

@node    Tutorial 11 References to another class
@section Tutorial 11 References to another class

m4_include(tutorial-11.tesinfo)

@node    Tutorial 12 Overloading methods
@section Tutorial 12 Overloading methods

m4_include(tutorial-12.tesinfo)

@node    Tutorial 13 More about references
@section Tutorial 13 More about references

m4_include(tutorial-13.tesinfo)

@node    Tutorial 14 Linked lists
@section Tutorial 14 Linked lists

m4_include(tutorial-14.tesinfo)

@node    Tutorial 15 Introducing inheritance
@section Tutorial 15 Introducing inheritance

m4_include(tutorial-15.tesinfo)

@node    Tutorial 16 More inheritance
@section Tutorial 16 More inheritance

m4_include(tutorial-16.tesinfo)

@node    Tutorial 17 Arrays inheritance and polymorphism
@section Tutorial 17 Arrays inheritance and polymorphism

m4_include(tutorial-17.tesinfo)

@node    Tutorial 18 Advanced J.T.W.
@section Tutorial 18 Advanced J.T.W.

@menu
* Mapping J.T.W. to Java::
* Piping the output of javac and java::
* Makefile for building *.jtw into *.java and running *.class files::
@end menu

See @ref{How to build a collection of class files or an entire package}
for more information about compiling an entire package worth of
classes.

m4_include(tutorial-18.tesinfo)

@node    Packages in J.T.W. and Java
@chapter Packages in J.T.W. and Java

The structure of a PACKAGE mirrors the file system.  For example you
can have a PACKAGE named (for argument's sake) TT(pkg) which
corresponds to a folder TT(pkg) in your TT(~/jtw-tutorials) folder.
You can have a sub-package called (for argument's sake) TT(inner)
which will reside in the folder TT(~/jtw-tutorials/pkg/inner).  Even
though the second PACKAGE resides inside of the first PACKAGE, they
are still considered as separate packages.

m4_define([WEBSITE],[@uref{http://$1,TT($1)}])

There is a naming convention that I will not bother to use that helps
to give unique names to your packages.  If you own a website like
WEBSITE(davinpearson.com) you can name your packages like so:
TT(com/davinpearson/inner/inner2) where TT(com/davinpearson) where
TT(com.davinpearson.inner) and TT(com.davinpearson.inner.inner2) are
separate packages.  The fact that I own the domain name
TT(davinpearson.com) ensures that my PACKAGE specification
TT(com/davinpearson) is unique.  The TT(com) comes first because it is
the actual domain name rather than the TT(com) extension that is
unique.  It is therefore non-sensible to place any code directly in
the TT(com) folder.  So in effect we are piggy-backing onto an
existing standard i.e. Internet Domain Names.  The same feature is
exploited by Websites which ask for your email address as your login,
as email addresses are unique to individual people.

@menu
* Moving a class into a package::
* Moving a class into a sub-package::
* Importing a package::
* Importing a package from another package::
* How to build a collection of class files or an entire package::
* How to invoke javadoc on a package::
@end menu

m4_include(packages.tesinfo)

@node     GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.txt

@node     Passwords for the answers to the tutorials
@appendix Passwords for the answers to the tutorials

m4_include(tutorial-passwords.tesinfo)

@node Index
@unnumbered Index

@printindex cp

@bye

