=begin pod :kind("Language") :subkind("Language") :category("beginning")

=TITLE Brief introduction

=SUBTITLE Using Raku official documentation

Documenting a large language like Raku has to balance several contradictory
goals, such as being brief whilst being comprehensive, catering to professional
developers with wide experience whilst also being accessible to newcomers to the
language.

Note the recent name change to Raku from Perl 6 has resulted in some objects
having changed names and their former names, while still available, are
deprecated and their use is not recommended in new code. Those items
are shown in the following table:

=begin table :caption<Raku object names versus deprecated Perl 6 names>
Raku | Perl 6 | Notes
=====+========+======
raku | perl   | routine
*RAKULIB | PERL6LIB | environment variable for module paths (*NYI)
.raku | .p6 | file extension for Raku scripts
.rakumod | .pm6 | file extension for Raku modules
=end table

For a quick hands-on introduction, there is a short
L<C<annotated programming example>|/language/101-basics>.

For programmers with experience in other languages, there are a number of
B<Migration> guides that compare and contrast the features of Raku with other
languages.

A number of B<Tutorials> cover several areas in which Raku is particularly
innovative. The section headers should help navigate the remaining documents.

There are a number of L<C<useful resources>|https://raku.org/resources> listed
elsewhere on the raku.org site. These include articles, books, slide
presentations, and videos.

It has been found that newcomers to Raku often ask questions that indicate
assumptions carried over from other programming paradigms. It is suggested that
the following sections in the C<Fundamental topics> section should be reviewed
first.

=begin item
L<C<Signatures>|/type/Signature> - each routine, which includes subroutines and
methods, has a signature. Understanding the information given in the signature
of a C<sub> or C<method> provides a quick way to grasp the operation and effect
of the routine.
=end item

=begin item
L<C<Containers>|/language/containers> - variables, which are like the nouns of
a computer language, are containers in which information is stored. The first
letter in the formal name of a container, such as the '$' of $my-variable, or
'@' of @an-array-of-things, or '%' of %the-scores-in-the-competition, conveys
information about the container. However, Raku is more abstract than other
languages about what can be stored in a container. So, for example, a $scalar
container can contain an object that is in fact an array.
=end item

=begin item
L<C<Classes and Roles>|/language/classtut> - Raku is fundamentally based on
objects, which are described in terms of classes and roles. Raku, unlike some
languages, does not B<impose> object-oriented programming practices, and useful
programs can be written as if Raku was purely procedural in nature. However,
complex software, such as the Rakudo compiler of Raku, is made much simpler
by writing in object-oriented idioms, which is why the Raku documentation is
more easily understood by reviewing what a class is and what a role is. Without
understanding about classes and roles, it would be difficult to understand
types, to which a whole section of the documentation is devoted.
=end item

=begin item
L<C<Traps to Avoid>|/language/traps> - Several common assumptions lead to code
that does not work as the programmer intended. This section identifies some
of them. It is worth reviewing when something doesn't quite work out.
=end item

=end pod
