(no subject)

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

(no subject)

siko1056
Recently, I "Markdownified" the online version of the NEWS file and added some categories to avoid repetitive sayings like "... to be ML compatible.... will be removed from Octave 7...." which is boring to read:


Now I am able to read the changes on my smartphone without horizontal scrolling as well ;-)

Are there any objections against using Markdown for the NEWS file in general?  Octave already uses Markdown for the README file and the current style of the NEWS file is quite close to Markdown anyways.  This makes it easier to create a good looking news announcements without to much post-processing on the website.

By using a plain text editor the file is still readable [1] (even better if the editor supports Markdown-syntax highlighting).  The only drawback as with README is, that we cannot help the editor by adding a prefix like "NEWS.md".  This would violate the GNU Standard in automake [2].

If there are no objections, I would merge my NEWS-5.1.md changes with the stable branch (omitting some website related additions) and Markdownify the current default branch.

Best,
Kai


Reply | Threaded
Open this post in threaded view
|

Re: Use Markdown for NEWS file

John W. Eaton
Administrator
No objections from me.

jwe

On 3/4/19 7:29 AM, Kai Torben Ohlhus wrote:

> Recently, I "Markdownified" the online version of the NEWS file and
> added some categories to avoid repetitive sayings like "... to be ML
> compatible.... will be removed from Octave 7...." which is boring to read:
>
> https://www.gnu.org/software/octave/NEWS-5.1.html
>
> Now I am able to read the changes on my smartphone without horizontal
> scrolling as well ;-)
>
> Are there any objections against using Markdown for the NEWS file in
> general?  Octave already uses Markdown for the README file and the
> current style of the NEWS file is quite close to Markdown anyways.  This
> makes it easier to create a good looking news announcements without to
> much post-processing on the website.
>
> By using a plain text editor the file is still readable [1] (even better
> if the editor supports Markdown-syntax highlighting).  The only drawback
> as with README is, that we cannot help the editor by adding a prefix
> like "NEWS.md".  This would violate the GNU Standard in automake [2].
>
> If there are no objections, I would merge my NEWS-5.1.md
> <http://NEWS-5.1.md> changes with the stable branch (omitting some
> website related additions) and Markdownify the current default branch.
>
> Best,
> Kai
>
> [1] https://hg.octave.org/web-octave/file/0bcf9964773c/NEWS-5.1.md
> [2] https://www.gnu.org/software/automake/manual/automake.html#Strictness
>


Reply | Threaded
Open this post in threaded view
|

Re:

Carnë Draug
In reply to this post by siko1056
On Mon, 4 Mar 2019 at 12:32, Kai Torben Ohlhus <[hidden email]> wrote:

>
> Recently, I "Markdownified" the online version of the NEWS file and
> added some categories to avoid repetitive sayings like "... to be ML
> compatible.... will be removed from Octave 7...." which is boring to
> read:
>
>    https://www.gnu.org/software/octave/NEWS-5.1.html
>
> Now I am able to read the changes on my smartphone without
> horizontal scrolling as well ;-)
>
> Are there any objections against using Markdown for the NEWS file in
> general?  Octave already uses Markdown for the README file and the
> current style of the NEWS file is quite close to Markdown anyways.
> This makes it easier to create a good looking news announcements
> without to much post-processing on the website.
>
> By using a plain text editor the file is still readable [1] (even
> better if the editor supports Markdown-syntax highlighting).  The
> only drawback as with README is, that we cannot help the editor by
> adding a prefix like "NEWS.md".  This would violate the GNU Standard
> in automake [2].
>
> If there are no objections, I would merge my NEWS-5.1.md changes
> with the stable branch (omitting some website related additions) and
> Markdownify the current default branch.
>

Markdown is a family of syntaxes.  If we are going to use one of them,
can we document somewhere which one we are using and add a link to its
documentation?  Or maybe limit to a subset of the markup.

Reply | Threaded
Open this post in threaded view
|

Re: Use Markdown for NEWS file

siko1056
On Mon, Mar 4, 2019 at 5:41 PM Carnë Draug <[hidden email]> wrote:
On Mon, 4 Mar 2019 at 12:32, Kai Torben Ohlhus <[hidden email]> wrote:
>
> Recently, I "Markdownified" the online version of the NEWS file and
> added some categories to avoid repetitive sayings like "... to be ML
> compatible.... will be removed from Octave 7...." which is boring to
> read:
>
>    https://www.gnu.org/software/octave/NEWS-5.1.html
>
> Now I am able to read the changes on my smartphone without
> horizontal scrolling as well ;-)
>
> Are there any objections against using Markdown for the NEWS file in
> general?  Octave already uses Markdown for the README file and the
> current style of the NEWS file is quite close to Markdown anyways.
> This makes it easier to create a good looking news announcements
> without to much post-processing on the website.
>
> By using a plain text editor the file is still readable [1] (even
> better if the editor supports Markdown-syntax highlighting).  The
> only drawback as with README is, that we cannot help the editor by
> adding a prefix like "NEWS.md".  This would violate the GNU Standard
> in automake [2].
>
> If there are no objections, I would merge my NEWS-5.1.md changes
> with the stable branch (omitting some website related additions) and
> Markdownify the current default branch.
>

Markdown is a family of syntaxes.  If we are going to use one of them,
can we document somewhere which one we are using and add a link to its
documentation?  Or maybe limit to a subset of the markup.

You are right, I am not precise with the term "Markdown".  The Jekyll website currently uses the kramdown converter [1], which support several flavors of Markdown [2].

In general I don't suggest to use each possible Markdown feature in the NEWS file.  It is more the stupid observation that if we chose

- item

instead of

 ** item

and use some `code` and ### Headers where appropriate, we get a perfect source for the website without changing the previous workflow with NEWS too much.  Even extra features like lightweight tables where created by developers without having kramdown in mind ;-)  To me it is just a natural way of getting good documentation done in plain text.

It's just a NEWS file, so I don't want to over specify it's usage.  For those who need one, plain Markdown will always work [3] and when using extra features, those lines eventually have to be touched be me or others to make them work on the website.

Best,
Kai