[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Use Markdown for NEWS file

From: Kai Torben Ohlhus
Subject: Re: Use Markdown for NEWS file
Date: Tue, 5 Mar 2019 09:10:06 +0100

On Mon, Mar 4, 2019 at 5:41 PM Carnë Draug <address@hidden> wrote:
On Mon, 4 Mar 2019 at 12:32, Kai Torben Ohlhus <address@hidden> 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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]