Changeset a514fed

Timestamp:

Apr 11, 2025, 6:40:42 PM (6 months ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

master

Children:

5ad6f0d

Parents:

30548de

Message:

update user documentation

Location:

doc/user

Files:

• Makefile (modified) (1 diff)
• user.tex (modified) (26 diffs)

doc/user/Makefile

@@ -46 +46 @@
 
 all : ${DOCUMENT}
+
+INSTALLDOCDIR = /u/cforall/public_html/doc
+install : all ${INSTALLDOCDIR}
+        cp -f ${DOCUMENT} ${INSTALLDOCDIR}/${DOCUMENT}
 
 clean :

doc/user/user.tex

@@ -11 +11 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Fri Jan 17 14:20:39 2025
-%% Update Count     : 6971
+%% Last Modified On : Fri Apr 11 18:33:42 2025
+%% Update Count     : 7064
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -597 +597 @@
 This extension is backwards compatible, matches with the use of underscore in variable names, and appears in \Index*{Ada} and \Index*{Java} 8.
 \CC uses the single quote (©'©) as a separator, restricted within a sequence of digits, \eg ©0xaa©©'©©ff©, ©3.141©©'©©592E1©©'©©1©.
-However, the drawback of the \CC approach is difficults parsing for IDEs between character and numeric constants, as quotes are no longer balanced (©'x'© and ©3.14©©'©©159©).
+However, the drawback of the \CC approach is differentiating between character and numeric constants by IDEs, as quotes are no longer balanced (©'x'© and ©3.14©©'©©159©).
 
 
 \section{Exponentiation Operator}
 
-C, \CC, and Java (and other programming languages) have \emph{no} exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow(x,y)}, to perform the exponentiation operation.
-\CFA extends the basic operators with the exponentiation operator ©?©\R{©\\©}©?©\index{?\\?@©?@\@?©} and ©?©\R{©\\©}©=?©\index{?\\=?@©@\@=?©}, as in, ©x ©\R{©\\©}© y© and ©x ©\R{©\\©}©= y©, which means $x^y$ and $x \leftarrow x^y$.
+Exponentiation, $x^y$, means raise $x$ to the $y$th power.
+When $y$ is a positive integer, exponentiation corresponds to $\prod_{i=1}^{y} x$.
+
+C, \CC, Java and other programming languages have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, using a routine like \Indexc{pow( x, y )} instead.
+Ada, Haskell, Python and other programming languages often use operators ©^© or ©**© for exponentiation.
+However, neither of these operators work in C as ©^© means exclusive-or and ©**© means double dereference.
+Furthermore, using a routine for exponentiation does not match with mathematical expectation, \ie ©-x**-y© becomes ©pow( -x, -y )©.
+
+\CFA extends the basic C operator set with symbol \R{©\\©} (backslash) as the exponentiation operator, represented by routines ©?©\R{©\\©}©?©\index{?\\?@©?@\@?©} and ©?©\R{©\\©}©=?©\index{?\\=?@©@\@=?©}, respectively.
+For example, ©x ©\R{©\\©}© y© and ©x ©\R{©\\©}©= y© mean $x^y$ and $x \leftarrow x^y$.
 The priority of the exponentiation operator is between the cast and multiplicative operators, so ©-f(x) \ -g(y)© is parenthesized as ©(-f(x)) \ (-g(y))©.
-
-There are exponentiation operators for integral and floating types, including the builtin \Index{complex} types.
-Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication ($O(\log y)$ or shifting if the exponent is 2).
+The C ©pow© routines continues to be available for backwards compatibility.
+
+Exponentiation is overloaded for integral and floating types, including the builtin \Index{complex} types.
+Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication ($O(\log y)$ or shifting if the exponent is 2.
 Overflow for a large exponent or negative exponent returns zero.
 Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the exponent cannot be negative.
@@ -615 +624 @@
 \end{cfa}
 Note, ©5 \ 32© and ©5L \ 64© overflow, and ©-4 \ -3© is a fraction but stored in an integer so all three computations generate an integral zero.
-Because exponentiation has higher priority than ©+©, parenthesis are necessary for exponentiation of \Index{complex constant}s or the expression is parsed as ©1.0f+©\R{©(©}©2.0fi \ 3.0f©\R{©)©}©+2.0fi©, requiring \R{©(©}©1.0f+2.0fi©\R{©)©}© \ ©\R{©(©}©3.0f+2.0fi©\R{©)©}.
+Because exponentiation has higher priority than ©+©, parenthesis are required for exponentiation of \Index{complex constant}s or the expression is parsed as ©1.0f+©\R{©(©}©2.0fi \ 3.0f©\R{©)©}©+2.0fi©, requiring \R{©(©}©1.0f+2.0fi©\R{©)©}© \ ©\R{©(©}©3.0f+2.0fi©\R{©)©}.
 
 The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation version is available.
@@ -624 +633 @@
 T ?®\®?( T ep, unsigned long int y );
 \end{cfa}
-A user type ©T© must define one (©1©), and multiplication (©*©) \see{\VRef{s:Operator}}.
+A user type ©T© must define one (©1©) and multiplication (©*©) \see{\VRef{s:Operator}}.
 
 
@@ -638 +647 @@
 Declarations in the \Indexc{do}-©while© condition are not useful because they appear after the loop body.}
 \begin{cfa}
-if ( ®int x = f()® ) ...                        §\C{// x != 0}§
+if ( ®int x = f()® ) ...                        §\C[2.75in]{// x != 0}§
 if ( ®int x = f(), y = g()® ) ...       §\C{// x != 0 \&\& y != 0}§
 if ( ®int x = f(), y = g(); x < y® ) ... §\C{// relational expression}§
@@ -646 +655 @@
 while ( ®int x = f(), y = g()® ) ... §\C{// x != 0 \&\& y != 0}§
 while ( ®int x = f(), y = g(); x < y® ) ... §\C{// relational expression}§
-while ( ®struct S { int i; } x = { f() }; x.i < 4® ) ... §\C{// relational expression}§
+while ( ®struct S { int i; } x = { f() }; x.i < 4® ) ... §\C{// relational expression}\CRT§
 \end{cfa}
 Unless a relational expression is specified, each variable is compared not equal to 0, which is the standard semantics for the ©if©/©while© expression, and the results are combined using the logical \Indexc{&&} operator.
@@ -692 +701 @@
 \end{tabular}
 \end{cquote}
-In addition, subranges are allowed to specify a contiguous set of case values.
+In addition, inclusive ranges are allowed using symbol ©~© to specify a contiguous set of case values, both positive and negative.
 \begin{cquote}
-\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{\hspace{2em}}l@{}}
-\multicolumn{1}{c@{\hspace{3em}}}{\textbf{C}}   & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CFA}}      & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{©gcc©}}     \\
+\setlength{\tabcolsep}{15pt}
+\begin{tabular}{@{}llll@{}}
+\multicolumn{1}{c}{\textbf{C}}  & \multicolumn{1}{c}{\textbf{\CFA}}     & \multicolumn{1}{c}{\textbf{©gcc©}}    \\
 \begin{cfa}
 switch ( i ) {
-  case 1: case 2: case 3: case 4:
+  case -4: case -3: case -2: case -1:
         ...
   case 10: case 11: case 12: case 13:
@@ -707 +717 @@
 \begin{cfa}
 switch ( i ) {
-  case ®1~4:®
+  case ®-4~-1:®
         ...
   case ®10~13:®
@@ -716 +726 @@
 \begin{cfa}
 switch ( i ) {
-  case 1§\R{\textvisiblespace}§®...®4:
+  case -4§\R{\textvisiblespace}§®...®-1:
         ...
   case 10§\R{\textvisiblespace}§®...®13:
@@ -725 +735 @@
 \begin{cfa}
 
-// 1, 2, 3, 4
+// -4, -3, -2, -1
 
 // 10, 11, 12, 13
@@ -733 +743 @@
 \end{tabular}
 \end{cquote}
-While ©gcc© has the same range mechanism, it has an awkward syntax, ©2©\R{\textvisiblespace}©...42©, because a space is required after a number, otherwise the period is a decimal point.
+While ©gcc© has the same range mechanism, it has an awkward syntax, ©2©\R{\textvisiblespace}©...42©, because a space is required after the lower bound, otherwise the period is a decimal point.
 
 \CFA also allows lists of subranges.
 \begin{cfa}
-case ®1~5, 12~21, 35~42®:
+case ®-5~-1, 12~21, 35~42®:
 \end{cfa}
 
@@ -807 +817 @@
 
 While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive for many programmers and is different from most programming languages with a ©switch© statement.
-Hence, default fall-through semantics results in programming errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
+Hence, default fall-through semantics results in errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
 
 \item
@@ -820 +830 @@
         } // if
 \end{cfa}
-This usage branches into control structures, which is known to cause both comprehension and technical difficulties.
+This usage branches into control structures, which causes comprehension and technical difficulties.
 The comprehension problem results from the inability to determine how control reaches a particular point due to the number of branches leading to it.
 The technical problem results from the inability to ensure declaration and initialization of variables when blocks are not entered at the beginning.
 There are few arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
-This C idiom is known as ``\Index*{Duff's device}''~\cite{Duff83}, from this example:
+This C idiom is known as ``\Index*{Duff's device}''~\cite{Duff83}, from the example:
 \begin{cfa}
 register int n = (count + 7) / 8;
@@ -1056 +1066 @@
 That is, the optional low set value, the optional scan direction (ascending/descending), the (possibly) required range character, the optional include last-scan value, the required high set value, and the optional range character and step value.
 \R{Warning}: the regular expression allows the form ©~H©, but this syntax has a preexisting meaning in C: complement the bits of ©H©, \eg ©for ( ~5 )© meaning ©for ( -6 )©, as ©-6© is the complement of ©5©.
-This anomaly is unlikely to cause problems because programers will write the shorter ©for ( 5 )©.
+This anomaly is unlikely to cause problems because programers should write the shorter ©for ( 5 )©.
 
 The previous ©for© loops have an anonymous loop index in which the range iteration is computed.
@@ -2948 +2958 @@
 Specifically, the inheritance relationship for ©Name©s is:
 \begin{cfa}
-Name $\(\subseteq\)$ Name2 $\(\subseteq\)$ Name3 $\(\subseteq\)$ const char * // enum type of Name
+Name §\(\subseteq\)§ Name2 §\(\subseteq\)§ Name3 §\(\subseteq\)§ const char * // enum type of Name
 \end{cfa}
 Hence, given
@@ -3990 +4000 @@
 \subsection{Casting}
 
-In C, the cast operator is used to explicitly convert between types.
+Casting is a mechanism to explicitly change the type and representation of a value.
+If the type and representation are changed, the cast is a \newterm{conversion};
+if only the type is changed but not the value representation, the cast is a \newterm{coercion}.
+For example, in:
+\begin{cfa}
+int i, *ip;
+double d;
+d = (double)i; §\C{// conversion}§
+ip = (int *)d; §\C{// coercion}§
+\end{cfa}
+the conversion cast implicitly runs code that transforms an integer representation into the best-effort floating-point representation.
+Another conversion case exists in object-oriented programming-languages to walk an inheritence hierarchy looking for specific types along the path.
+The coercion cast lies about the representation of the value as the integer point is actually pointing at a floating-point value;
+indirect operations through ©ip© are as odds with direct operations on ©d©.
+In general, coercion casts are only necessary for systems programming, like building a memory allocator, where raw storage is typed and returned for use by the language or the runtime system to access storage in special ways.
+
+For coercion casts, there are often fine-grain variations to precisely expalin how the storage is to be typed.
+\CC and \CFA have a number specialized casts., there are four types of explicit casting operators.
+\begin{enumerate}
+\item
+©dynamic_cast© Used for conversion of polymorphic types.
+\item
+©static_cast© Used for conversion of nonpolymorphic types.
+\item
+©const_cast© Used to remove the type qualifiers and possibly attributes.
+\item
+©reinterpret_cast© Used for simple reinterpretation of bits.
+\end{enumerate}
+
+\begin{cfa}
+        '(' type_no_function ')' cast_expression
+        '(' aggregate_control '&' ')' cast_expression           // CFA
+        '(' aggregate_control '*' ')' cast_expression           // CFA
+        '(' VIRTUAL ')' cast_expression                                 // CFA
+        '(' VIRTUAL type_no_function ')' cast_expression        // CFA
+        '(' RETURN type_no_function ')' cast_expression // CFA (ASCRIPTION)
+        '(' COERCE type_no_function ')' cast_expression // CFA (COERCION)
+        '(' qualifier_cast_list ')' cast_expression             // CFA, (modify CVs of cast_expression)
+\end{cfa}
+
+
+Specialized Casts
+
+There is some use in Cforall for cast operators with semantics other than the standard C cast.
+To make these alternate casts look like the familiar C cast, this proposal follows the example of the virtual proposal's virtual cast `(virtual Foo)x` and uses an added (pseudo-)keyword inside the cast parens.
+
+C (Conversion) Cast
+
+The standard C cast performs conversions, transformations between types which may make a new object with a different in-memory representation.
+Cforall maintains these semantics in a backward-compatible way while accounting for name overloading by choosing the lowest-cost interpretation of the argument expression which is convertable to the target type, breaking ties by conversion cost.
+
+The C cast must be maintained for backward-compatibility, and developing a second cast operator with identical semantics seems an undesirable multiplication of language features, but `(convert Foo)` or `(to Foo)` would be reasonable options for a keyword.
+An alternate semantics for a Cforall-specific conversion cast would be to choose the cast interpretation with the lowest sum of conversion cost and interpretation cost, which aligns better with Cforall function call resolution algorithm.
+
+Ascription Cast
+
+Using casts in Cforall for type ascription ("select the interpretation of this type") works by the conversion-cost tiebreaker behaviour of the cast operator.
+However, the ascription interpretation of casts is prioritized less than the conversion interpretation of casts, sometimes resulting in some surprising results, as in the following example:
+\begin{cfa}
+int f(int);      // f1
+int f(double);   // f2
+int g(int);      // g1
+double g(long);  // g2
+
+f((double)42);   // selects f2 by cast on argument
+(double)g(42);   // does NOT select g2, argument conversion cost results in g1
+\end{cfa}
+An ascription cast which reversed the priorities of the C cast would be useful for selecting expressions based on their return type; a reversal of the priorities of the standard C cast would work for this (that is, select the lowest-cost conversion, breaking ties based on argument cost).
+A plausible stricter semantics would be to select the cheapest interpretation with a zero-cost conversion to the target type, reporting a compiler error otherwise (this semantics would make ascription a solely compile-time phenomenon, rather than relying on possible runtime conversions).
+A resonable keyword would be `(as Foo)`, which is short, evocative, and echos "ascription"; `(return Foo)` would not introduce new keywords, and speaks to its use in return-type selection, as in the following corrected version of the example above:
+\begin{cfa}
+(as double)g(42);  // selects g2, as expected (under either presented ascription semantics)
+\end{cfa}
+
+Coercion Cast
+
+Some of the explict conversions in C are defined to be a coercions (reinterpret the bits of this value as another type).
+Use of coercions often relies on non-standard implementation details of the provided environment, and as such is discouraged, but is sometimes necessary.
+Since all explicit pointer casts in C are coercions, any lvalue ©x© in C/Cforall can be coerced with the pattern ©*(Foo*)&x©, but this is complex and doesn't extend to rvalues.
+\begin{cfa}
+int i = 5;
+double d = *(double*)&i; // value coercion
+printf( "%g %g %x\n", d, *(double *)&i, *(int *)&d );
+
+int i = 5; // pointer coercion
+double d = *(double*)&i; // value coercion
+\end{cfa}
+A dedicated coercion cast would solve these issues; ©(reinterpret Foo)© (from C++), ©(transmute Foo)© (from Rust), or ©(coerce Foo)© would be reasonable keywords.
+
+Qualifier Cast
+
+A more restricted (and thus safer) form of coercion is modifiying the qualifiers of a type; C++ has ©const_cast© for this purpose, and a similar feature would be useful for Cforall.
+With regard to syntax, ©(requalify const Foo)©/©(requalify Foo)© to add/strip ©const© would echo C++, but given that the vast majority of uses are stripping const-qualfiers, ©(non const)© would be shorter, clearer, easily searchable, and not require the programmer to exactly match the argument type.
+In this syntax, coercion casts could be used to add qualifiers, or another cast type (say ©(with const)©) could be introduced to add qualfiers.
+
+Virtual Cast
+see virtual.txt; semantics equivalent to C++ dynamic cast
+
+
 In \CFA, the cast operator has a secondary use, which is type ascription, since it forces the expression resolution algorithm to choose the lowest cost conversion to the target type.
 That is, a cast can be used to select the type of an expression when it is ambiguous, as in the call to an overloaded function.
@@ -4037 +4145 @@
 If ©g© is free of side effects, this is equivalent to ©[(int)(g().0), (int)(g().1.0), (int)(g().2)]©.
 Since ©void© is effectively a 0-element tuple, (3) discards the first and third return values, which is effectively equivalent to ©[(int)(g().1.0), (int)(g().1.1)]©).
-% will this always hold true? probably, as constructors should give all of the conversion power we need. if casts become function calls, what would they look like? would need a way to specify the target type, which seems awkward. Also, C++ basically only has this because classes are closed to extension, while we don't have that problem (can have floating constructors for any type).
+% will this always hold true? probably, as constructors should give all of the conversion power we need.
+if casts become function calls, what would they look like? would need a way to specify the target type, which seems awkward.
+Also, C++ basically only has this because classes are closed to extension, while we don't have that problem (can have floating constructors for any type).
 Note that a cast is not a function call in \CFA, so flattening and structuring conversions do not occur for cast expressions.
 As such, (4) is invalid because the cast target type contains 4 components, while the source type contains only 3.
@@ -4193 +4303 @@
 g( w2 );
 \end{cfa}
-Note, in all cases 3 arguments are supplied even though the syntax may appear to supply less than 3. As mentioned, a
-tuple does not have structure like a record; a tuple is simply converted into a list of components.
+Note, in all cases 3 arguments are supplied even though the syntax may appear to supply less than 3.
+As mentioned, a tuple does not have structure like a record; a tuple is simply converted into a list of components.
 \begin{rationale}
 The present implementation of \CFA does not support nested routine calls when the inner routine returns multiple values; \ie a statement such as ©g( f() )© is not supported.
@@ -5300 +5410 @@
 
 \item
-\Indexc{quoted}( ©char & ch©, ©const char Ldelimiter = '\''©, ©const char Rdelimiter = '\0'© )\index{manipulator!quoted@©quoted©}
+\Indexc{quote}( ©char & ch©, ©const char Ldelimiter = '\''©, ©const char Rdelimiter = '\0'© )\index{manipulator!quote@©quote©}
 consumes the string ©"LCR"©, where ©L© is the left ©delimiter© character, ©C© is the value in ©ch©, and ©R© is the right delimiter character, which skips whitespace, consumes and ignores the left delimiter, reads a single character into ©ch©, and consumes and ignores the right delimiter (3 characters).
 If the delimit character is omitted, it defaults to ©'\''© (single quote).
 \begin{cfa}[belowskip=0pt]
 char ch;
-sin | quoted( ch );   sin | quoted( ch, '"' );   sin | quoted( ch, '[', ']' );
+sin | quote( ch );   sin | quote( ch, '"' );   sin | quote( ch, '[', ']' );
 \end{cfa}
 \begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@@ -5313 +5423 @@
 \item
 \begin{sloppypar}
-\Indexc{quoted}( $wdi\ manipulator$, ©const char Ldelimiter = '\''©, ©const char Rdelimiter = '\0'© )\index{manipulator!quoted@©quoted©}
+\Indexc{quote}( $wdi\ manipulator$, ©const char Ldelimiter = '\''©, ©const char Rdelimiter = '\0'© )\index{manipulator!quote@©quote©}
 consumes the scanset ©"L[^R]R"©, where ©L© is the left ©delimiter© character and ©R© is the right delimiter character, which skips whitespace, consumes and ignores the left delimiter, reads characters until the right-delimiter into the string variable (null terminated), and consumes and ignores the right delimiter.
-If the delimit character is omitted, it defaults to ©'\''© (single quote).
+If the delimit character is omitted, it defaults to ©'"'© (double quote).
 \end{sloppypar}
 \begin{cfa}[belowskip=0pt]
 char cs[10];
-sin | quoted( wdi( sizeof(cs), cs ) ); §\C[3in]{// " is the start/end delimiter}§
-sin | quoted( wdi( sizeof(cs), cs ), '\'' ); §\C{// ' is the start/end delimiter}§
-sin | quoted( wdi( sizeof(cs), cs ), '[', ']' ); §\C{// [ is the start and ] is the end delimiter}\CRT§
+sin | quote( wdi( sizeof(cs), cs ) ); §\C[3in]{// " is the start/end delimiter}§
+sin | quote( wdi( sizeof(cs), cs ), '\'' ); §\C{// ' is the start/end delimiter}§
+sin | quote( wdi( sizeof(cs), cs ), '[', ']' ); §\C{// [ is the start and ] is the end delimiter}\CRT§
 \end{cfa}
 \begin{cfa}[showspaces=true]
@@ -5357 +5467 @@
 sin | ignore( d );                                              §\C{// d is unchanged}§
 sin | ignore( cs );                                             §\C{// cs is unchanged, no wdi required}§
-sin | ignore( quoted( wdi( sizeof(cs), cs ) ) ); §\C{// cs is unchanged}§
+sin | ignore( quote( wdi( sizeof(cs), cs ) ) ); §\C{// cs is unchanged}§
 \end{cfa}
 \begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@@ -5794 +5904 @@
 In \CFA, as in C, all scalar types can be incremented and
 decremented, which is defined in terms of adding or subtracting 1.
-The operations ©&&©, ©||©, and ©!© can be applied to any scalar arguments and are defined in terms of comparison against 0 (ex. ©(a && b)© becomes ©(a != 0 && b != 0)©).
+The operations ©&&©, ©||©, and ©!© can be applied to any scalar arguments and are defined in terms of comparison against 0 (\eg ©(a && b)© becomes ©(a != 0 && b != 0)©).
 
 In C, the integer constants 0 and 1 suffice because the integer promotion rules can convert them to any arithmetic type, and the rules for pointer expressions treat constant expressions evaluating to 0 as a special case.
@@ -5800 +5910 @@
 Defining special constants for a user-defined type is more efficient than defining a conversion to the type from ©bool©.
 
-Why just 0 and 1? Why not other integers? No other integers have special status in C.
-A facility that let programmers declare specific constants..const Rational 12., for instance. would not be much of an improvement.
+Why just 0 and 1?
+Why not other integers?
+No other integers have special status in C.
+A facility that let programmers declare specific constants ©const Rational 12©, for instance. would not be much of an improvement.
 Some facility for defining the creation of values of programmer-defined types from arbitrary integer tokens would be needed.
 The complexity of such a feature does not seem worth the gain.
 
 For example, to define the constants for a complex type, the programmer would define the following:
-
 \begin{cfa}
 struct Complex {
@@ -6525 +6636 @@
 For example, container/vector is a valid module name, where container is the parent module name, and vector is the sub-module under container.
 
-Only the interfaces of a module are visible from outside, when the module is imported. export is a type decorator to declare a module interface.
+Only the interfaces of a module are visible from outside, when the module is imported, export is a type decorator to declare a module interface.
 A method, a global variable or a type can be declared as a module interface.
 Types defined in a module and referenced by an exported function or a variable must be exported, too.
@@ -6558 +6669 @@
 All of the exported names are visible in the file that imports the module.
 The exported names can be accessed within a namespace based on the module name in the first syntax (ex moduleName.foo).
-If moduleName has several elements separated by '/' to describe a sub-module (ex. import container/vector;), the last element in the moduleName is used as the namespace to access the visible names in that module (ex vector.add(...);).
-The as keyword is used to confine the imported names in a unique namespace (ex. anotherName.foo). anotherName must be a valid identifier (same rules as a variable name) which means it cannot have '/' in it.
+If moduleName has several elements separated by '/' to describe a sub-module (\eg import container/vector;), the last element in the moduleName is used as the namespace to access the visible names in that module (ex vector.add(...);).
+The as keyword is used to confine the imported names in a unique namespace (\eg anotherName.foo). anotherName must be a valid identifier (same rules as a variable name) which means it cannot have '/' in it.
 Conflicts in namespaces will be reported by the compiler.
 The second method can be used to solve conflicting name problems.
@@ -6582 +6693 @@
 
 Additionally, using the .as. syntax, a user can force the compiler to add the imported names into the current namespace using .as ..With these module rules, the following module definitions and imports can be achieved without any problem.
-
 \begin{cfa}
 module M1;