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.
Best,
Kai