[ovs-dev] Markdown coding standard

[Finucane, Stephen]

> On 02/12/15 at 05:37pm, Finucane, Stephen wrote:
> > I note that there are no coding standard for Markdown documents. Given
> this, I have some questions:
> >
> >   * What's the expected format for code blocks (multi-line and single-
> line)?
> 
> We haven't standardized on anything yet. Is there an exciting good
> guidelines doc that we could inherit? Maybe just refer to the github
> markdown syntax page?

Shockingly enough, no. Doesn't help that Markdown, awesome though it may be, has had very little guidance:

    http://lwn.net/Articles/610975/

> 
> >   * Can we use GHFM-extensions (i.e. syntax-highlighted code fences)
> 
> I think that's fine as long as they are compatible with the markdown
> parser invoked in build-aux/dist-docs to generate the docs for the
> website.

Wasn't even aware of that. I'll check it out to be sure.

> 
> >   * Line limit? It's not necessary to wrap Markdown if you don't want to,
> but files seem to alternate between 72, 79 and 80+ quite a bit
> 
> I basically did the minimum required to get quotes formatted correctly
> and didn't reformat everything. Cleanups are definitely welcome.

I have one for 'INSTALL.DPDK.md' that I'll submit soon as I can. I'll try to look at some others too. However, it would of course be better if this could be automated. I tried using Pandoc (Markdown -> HTML -> Markdown) but even with 'github_markdown' formatting it didn't parse like GitHub did.

> 
> >   * Any "expected approach" to validating Markdown output (i.e. confirm
> that it will preview correctly on GitHub)
> 
> Personally I have been using Haroopad when changing the docs to verify
> correct rendering.

Yes, I've been using this site (http://jbt.github.io/markdown-editor/) coupled with some SublimeText plugins to do this. It would be great if this could be automated but I guess you'd need something like Selenium to validate formatting.