[m-rev.] for review: convert NEWS file to markdown and begin restructuring it
Julien Fischer
jfischer at opturion.com
Tue Dec 31 14:20:47 AEDT 2019
Hi Peter,
On Tue, 31 Dec 2019, Peter Wang wrote:
> On Mon, 30 Dec 2019 23:56:51 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
>>
>> For review by anyone.
>>
>> In addition to the diff, I have attached the full NEWS file and also the
>> HTML version generated by pandoc. Reviews wishing to generate their own
>> HTML versions using pandoc, should use the command:
>>
>> $ pandoc -s -o news.html NEWS
>>
>> You should also note that ancient versions of pandoc will produce very
>> strange results. I found this out the hard way :-(
>
> Since we're following commonmark, any alternative processor can be used
> in case pandoc is hard to install for anyone, e.g. "cmark" from the same
> author as pandoc.
I used pandoc precisely because it was easy to install, "yum install
pandoc" on one machine, "brew install pandoc" on the other ;-)
Of course installing it from source is a different matter ...
...
>> index c06c3731f..4597fe435 100644
>> --- a/NEWS
>> +++ b/NEWS
>> @@ -1,10 +1,9 @@
>> -NEWS since Mercury 14.01.x
>> ---------------------------
>> +# NEWS since Mercury 14.01.x
>>
>> -Changes that may break compatibility:
>> +## Changes that may break compatibility
>
> Could use underline-style headers for the first two levels
> to make it nicer to read as plain text.
Done.
>> - "func" and "pred") and Mercury operators (such as clause neck operator ":-")
>> + `"func"` and `"pred"`) and Mercury operators (such as clause neck operator `":-"`)
>> but which cannot be parsed as the Mercury constructs that those Mercury
>> keywords and operators are part of, it now generates a specific error
>> message for each discrepancy. In the past, when it found such code,
>> @@ -13,43 +12,46 @@ Changes that may break compatibility:
>> declared type and the called functions and predicates did not exist,
>> leading to confusing error messages from the compiler.
>>
>> - The compiler's new approach generates considerably better diagnostics,
>> - but it does mean that code that uses Mercury's keywords and/or operators
>> - in ways that are inconsistent with Mercury's own uses of those keywords
>> - and operators won't compile anymore. Such code will need to be changed,
>> + The compiler\'s new approach generates considerably better diagnostics,
>
> You don't need to escape apostrophes.
Fixed.
>> + but it does mean that code that uses Mercury\'s keywords and/or operators
>> + in ways that are inconsistent with Mercury\'s own uses of those keywords
>> + and operators will not compile anymore. Such code will need to be changed,
>> typically by changing the names of some function symbols, functions
>> or predicates.
>>
>> -* Code that switches on a field of a term could previously written
>> - directly as
>> +* Code that switches on a field of a term could previously written directly as
>>
>> - (
>> + ```
>> + (
>> Term ^ field = value1,
>> ...
>> - ;
>> + ;
>> Term ^ field = value2,
>> ...
>> - )
>> + )
>> + ```
>
> You could indent the code blocks another four spaces instead of using
> backticks (i.e. the code blocks would start on column 8). This is
> similar to how it was formatted before, and reads nicer as plain text.
Done.
Diff below -- thanks for that!
Julien.
------------------------
diff --git a/NEWS b/NEWS
index b38c7b0e3..9bd380468 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,8 @@
-# NEWS since Mercury 14.01.x
+NEWS since Mercury 14.01.x
+==========================
-## Changes that may break compatibility
+Changes that may break compatibility
+------------------------------------
* When the Mercury compiler looks at code using Mercury keywords (such as
`"func"` and `"pred"`) and Mercury operators (such as clause neck operator `":-"`)
@@ -12,37 +14,33 @@
declared type and the called functions and predicates did not exist,
leading to confusing error messages from the compiler.
- The compiler\'s new approach generates considerably better diagnostics,
- but it does mean that code that uses Mercury\'s keywords and/or operators
- in ways that are inconsistent with Mercury\'s own uses of those keywords
+ The compiler's new approach generates considerably better diagnostics,
+ but it does mean that code that uses Mercury's keywords and/or operators
+ in ways that are inconsistent with Mercury's own uses of those keywords
and operators will not compile anymore. Such code will need to be changed,
typically by changing the names of some function symbols, functions
or predicates.
* Code that switches on a field of a term could previously written directly as
- ```
- (
- Term ^ field = value1,
- ...
- ;
- Term ^ field = value2,
- ...
- )
- ```
+ (
+ Term ^ field = value1,
+ ...
+ ;
+ Term ^ field = value2,
+ ...
+ )
The compiler would then internally rearrange this as
- ```
- Field = Term ^ field,
- (
- Field = value1,
- ...
- ;
- Field = value2,
- ...
- )
- ```
+ Field = Term ^ field,
+ (
+ Field = value1,
+ ...
+ ;
+ Field = value2,
+ ...
+ )
and then recognize this as a switch on `Field`.
@@ -73,7 +71,7 @@
If a module `m` has an `import_module` or `use_module` declaration for
module `x.y.z`, it must also have `import_module` or `use_module` declarations
for its ancestors `x` and `x.y`. And if the import or use of `x.y.z`
- is in module `m`\'s interface, then the import or use of `x.y.z`\'s
+ is in module `m`'s interface, then the import or use of `x.y.z`'s
ancestor modules must also be in the interface.
* References to everything imported via `:- use_module` declarations
@@ -84,57 +82,51 @@
* It is now an error for a program to redefine a builtin type. The affected
type names are:
- ```
- int
- int{8,16,32,64}
- uint
- uint{8,16,32,64}
- float
- character
- string
- {}
- =
- pred
- func
- pure
- semipure
- impure
- ''
- ```
+ int
+ int{8,16,32,64}
+ uint
+ uint{8,16,32,64}
+ float
+ character
+ string
+ {}
+ =
+ pred
+ func
+ pure
+ semipure
+ impure
+ ''
* It is now an error for a program to redefine a builtin inst. The affected
inst names are:
- ```
- =<
- any
- bound
- bound_unique
- clobbered
- clobbered_any
- free
- ground
- is
- mostly_clobbered
- mostly_unique
- mostly_unique_any
- not_reached
- unique
- unique_any
- ```
+ =<
+ any
+ bound
+ bound_unique
+ clobbered
+ clobbered_any
+ free
+ ground
+ is
+ mostly_clobbered
+ mostly_unique
+ mostly_unique_any
+ not_reached
+ unique
+ unique_any
* It is now an error for a program to redefine a builtin mode. The affected
mode names are:
- ```
- =
- >>
- any_func
- any_pred
- func
- is
- pred
- ```
+ =
+ >>
+ any_func
+ any_pred
+ func
+ is
+ pred
* We have deleted the builtin inst synonyms `old` and `new`: their uses
should be replaced with `any` and `free` respectively.
@@ -142,10 +134,10 @@
* We have deleted the builtin modes `no` and `oo`: their uses should be
replaced with `oa` and `ia` respectively.
-* The minimum version of the Java platform required by Mercury\'s Java
+* The minimum version of the Java platform required by Mercury's Java
backend is now Java SE 8.
-* The representation of integer constants in the standard library\'s `term`
+* The representation of integer constants in the standard library's `term`
and `lexer` modules has been generalised. The base, signedness and size of
each integer constant is now recorded. Furthermore, these modules now use
arbitrary-precision integers to represent the values of integer constants.
@@ -179,11 +171,12 @@
`string.poly_type` should be used directly. This may require an explicit
import of the `string` module.
-## Changes to the Mercury language
+Changes to the Mercury language
+-------------------------------
* We have added nine new primitive types: `uint`, `int8`, `int16`, `int32`,
`int64`, `uint8`, `uint16`, `uint32` and `uint64`. The type `uint` is an
- unsigned integer type of the same size as Mercury\'s `int` type; the types
+ unsigned integer type of the same size as Mercury's `int` type; the types
`int8`, `int16`, `int32` and `int64` are signed integer types of width
8, 16, 32 and 64 bits respectively; the types `uint8`, `uint16`, `uint32`
and `uint64` are unsigned integer types of width 8, 16, 32 and 64 bits
@@ -191,13 +184,11 @@
Literals of these new types must have a distinguishing suffix, for example:
- ```
- 999u
- 561i32
- 0b1111100111i64
- 0o16u8
- 0x3e732i64
- ```
+ 999u
+ 561i32
+ 0b1111100111i64
+ 0o16u8
+ 0x3e732i64
Basic operations on the new primitive types are provided by the new standard
library modules: `uint`, `int8`, `int16`, `int32`, `int64`, `uint8`,
@@ -206,16 +197,14 @@
* We have added a new kind of scope to the language: determinism checks
for switch arms. These scopes are introduced by any of the new keywords
- ```
- require_switch_arms_det
- require_switch_arms_semidet
- require_switch_arms_multi
- require_switch_arms_nondet
- require_switch_arms_cc_multi
- require_switch_arms_cc_nondet
- require_switch_arms_erroneous
- require_switch_arms_failure
- ```
+ require_switch_arms_det
+ require_switch_arms_semidet
+ require_switch_arms_multi
+ require_switch_arms_nondet
+ require_switch_arms_cc_multi
+ require_switch_arms_cc_nondet
+ require_switch_arms_erroneous
+ require_switch_arms_failure
`require_switch_arms_<determinism> [Var] Goal` tells the compiler to require
`Goal` to be a switch on `Var` in which all the switch arms have determinisms
@@ -229,11 +218,9 @@ for switch arms. These scopes are introduced by any of the new keywords
* We have added a new kind of scope to the language for disabling warnings
within the scope. A goal such as
- ```
- disable_warnings [singleton_vars] (
- Goal
- )
- ```
+ disable_warnings [singleton_vars] (
+ Goal
+ )
is equivalent to `Goal`, with the exception that the compiler will not
generate warnings about singleton variables inside `Goal`.
@@ -270,7 +257,8 @@ for switch arms. These scopes are introduced by any of the new keywords
* Digits in numeric literals may now be separated by underscores in order
to improve readability.
-## Changes to the Mercury standard library
+Changes to the Mercury standard library
+---------------------------------------
### New Integer Modules
@@ -640,7 +628,7 @@ for switch arms. These scopes are introduced by any of the new keywords
### Changes to the `pretty_printer` module
* The type `formatter_limit` has been renamed to `func_symbol_limit`, since
- this better reflects the type\'s purpose.
+ this better reflects the type's purpose.
* We have replaced the `set_formatter` function with a predicate of the same
name, since this allows the use of state variable notation when setting up more
@@ -840,7 +828,8 @@ for switch arms. These scopes are introduced by any of the new keywords
- `from_reverse_list`/1
-## Changes to the Mercury compiler
+Changes to the Mercury compiler
+-------------------------------
* We have extended tail call optimization from self recursive calls only
to mutually recursive calls as well, when generating high level C code,
@@ -893,7 +882,7 @@ for switch arms. These scopes are introduced by any of the new keywords
to turn those mutually recursive procedures into procedures that each
contain only *self* tail recursion.
-* We have significantly improved the compiler\'s ability to detect, and
+* We have significantly improved the compiler's ability to detect, and
to generate warnings about, code that violates the occurs check.
* We have fixed a long-standing bug causing crashes in deep profiling
@@ -922,7 +911,7 @@ for switch arms. These scopes are introduced by any of the new keywords
* We have improved support for AIX.
* The compiler now reports an error for binary/octal/hexadecimal integer
- literals that cannot be represented in the compiler\'s native `int` type.
+ literals that cannot be represented in the compiler's native `int` type.
* Class files generated for executables in the Java grade are now automatically
packaged up into Java archives (JARs).
@@ -949,7 +938,8 @@ for switch arms. These scopes are introduced by any of the new keywords
* We have upgraded the bundled Boehm GC to v7.6.10 and libatomic_ops to v7.6.2.
-## Changes to the Mercury debugger
+Changes to the Mercury debugger
+-------------------------------
* Interactive queries are now supported on OS X.
@@ -964,7 +954,8 @@ for switch arms. These scopes are introduced by any of the new keywords
* We have added a `browse --web` command to view terms in a web browser.
-## Changes to the extras distribution
+Changes to the extras distribution
+----------------------------------
* We have added support for Unicode and other enhancements to the `lex` and
`regex` libraries. Thanks to Sebastian Godelet.
More information about the reviews
mailing list