[Scilab-Dev] Switch to use Markdown for CHANGES

Sat Jun 11 01:11:46 CEST 2016

Hello Clément,

Le 09/06/2016 19:08, Clément David a écrit :
> Dear Scilab contributors,
>
> For the (near to be released) beta-2, I updated the CHANGES files to use the Markdown format [1].
> The idea is to be able to generate some document (html and pdf) from it in a semi-automatic way.
> Another point would be to have it nicely formatted on hosting platforms (github/gitlab) that render
> markdown on the fly.
>
> What do you think about that ? It is currently not clear to me if we should add an empty line
> between each `*` and if we should use set bugzilla URLs.
>
> [1]: https://codereview.scilab.org/#/c/18222
>
> Thanks for your remark,
>
> PS: for the beta-2, we will probably push it but any modification is possible for the stable
> release.

My feeling and suggestions are the following:

  * a formated output is certainly better than a simple-text one :)
  * I found the former Scilab releases notes very smart. The
    presentation on 2 columns was smart and welcome. It allows using a
    smaller font, to get more compact but still very readable notes.
  * A sans-serif font is always more readable. Arial is nice.
  * An hypertext output is nice also (or mainly) because it allows
    hyperlinks, including ones targeting bugzilla. However, any
    text-decoration should be avoided: underlining decrease links
    readability.

  * To avoid heaviness of the bug lists, heading dots may be removed.

  * In CHANGES,
      o In the final HTML rendering of the bugs lists, i find that
        Pierre-Aimé proposal to remove "fixed" is indeed better.
      o short references to bugzilla should be preferred to leave more
        space to the bug description:
        http://bugzilla.scilab.org/2104    instead    of
        http://bugzilla.scilab.org/show_bug.cgi?id=2104
      o Without what you call "markdown", i definitely preferred noting
        functions with parentheses like in "linespace()" instead of only
        "linespace". The purpose was to highlight Scilab reserved words
        wrt to common words in a sentence. However, if quoting markdown
        are used, i think that parentheses are no longer required: They
        would now make notations heavier than required. So i propose to
        not use them in forthcoming CHANGES.

  * For compactness, i definitely prefer avoiding any \n after each `*` item
  * For the same reason, i think that any sublist having only one term
    per line shall be avoided. An inline list shall be preferred. For
    instance,
      o Symbolic module functions have been removed:
          + |addf()|
          + |cmb_lin()|
          + |ldivf()|
          + |mulf()|
          + |rdivf()|
          + |solve()|
          + |subf()|
          + |trianfml()|
          + |trisolve()|
          + |block2exp()|
        |looks useless. I would prefer much more simply|
      o

        Symbolic module functions have been removed:||addf|, |cmb_lin|,
        |ldivf|, |mulf|, |rdivf|, |solve|, |subf|, |trianfml|,
        |trisolve|, block2exp|

  * As well,
      o

        Functions based on former Scilab stack have been removed:

          + |comp()|
          + |errcatch()|
          + |iserror()|
          + |fun2string()|
          + |getvariablesonstack()|
          + |gstacksize()|
          + |macr2lst()|
          + |stacksize()|
          + |code2str()|
          + |str2code()|
          + |-mem| launching option (used to set |stacksize()| at startup).

        could be abstracted in
      o

        Functions based on former Scilab stack have been removed:||||

          +

            |||comp, ||errcatch,||iserror||,
            fun2string,||getvariablesonstack, ||gstacksize, ||macr2lst,
            ||stacksize, ||code2str, ||str2code|||

          +

            |-mem| launching option (used to set |stacksize()| at startup).

I have implemented some of these suggestions in the attached CHANGES.html:

  * in <head><style>:
          a:link { text-decoration: none; font-weight: bold;}
           body { font-family:"arial"; font-size:11px }
           ul { page-break-before:avoid; }   /* not enough to actually
    avoid page breaks at bad places. A pity.  */
           h2 { page-break-after:avoid; }     /* .... */
           h3 { page-break-after:avoid; }     /* .... */

  * The list of bugs on 6.0.06beta2 release is encapsulated in
    <div style="column-count:2; -moz-column-count:2;
    -webkit-column-count:32 ">
    <ul style="list-style-type: none;">
    ...
    </ul>
    </div>
  * The second list is left as is for comparison.

I don't know if such options could be implemented if you think they 
could improve the output.

I was expecting other contributions before / instead spending my night 
to write to you here.

But apparently, considerations about subtracted uniform distributions 
are much more efficient to awake everybody on Scilab mailing lists.
Next time, you shall introduce your call-for-comments with something 
about maths :))

Good night
Samuel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20160611/c086f29f/attachment.htm>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20160611/c086f29f/attachment.html>