[m-rev.] for review: convert NEWS file to markdown and begin restructuring it

[Peter Wang]

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 haven't really edited the content of the entries beyond removing some
> redundancies and shifting some things that make break compatibility with
> exisiting code into the appropriate section.
> 
> I will deal with the sections of the document separately.
> 
> I would also note that there several fairly major changes that currently
> have no entry, notably:
> 
> * the library license change.
> * the changes to the random module.
> 
> Julien.
> 
> -----------
> 
> This diff makes two changes to the NEWS file. The first is to convert it into
> markdown. There are a number of reasons we want to do this:
> 
>     1. It allows us to automate the conversion to HTML.
>     2. It will look nicer on github.
>     3. It will still look (reasonably) nice as plain text.
> 
> The second change is to begin restructuring the contents of the file along the
> lines proposed in the thread on the developers list titled
> "Renaming the NEWS file -> NEWS.md" from February 2018. Specifically, this
> change implements the proposals that the be exactly one entry in the file for
> any library module and that those entries be sorted by module name.
> 
> NEWS:
>     Make the above changes.> diff --git a/NEWS b/NEWS

> 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.

>  * When the Mercury compiler looks at code using Mercury keywords (such as
> -  "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.

> +  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.

Peter