[ovs-dev] Markdown coding standard

[Finucane, Stephen]

> On Thu, Feb 12, 2015 at 09:21:35PM +0100, Thomas Graf wrote:
> > On 02/12/15 at 05:37pm, Finucane, Stephen wrote:
> > >   * 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.
> 
> Just to add to this, I prefer to avoid lines longer than 79 characters.

Under normal circumstances, so do I. However, I did a good deal of work on the DPDK vSwitch documentation and learnt much about "maintaining" Markdown docs. One of the big findings from this was that the paragraph-orientated nature of Markdown docs makes the hard line breaks very difficult to maintain. Adding even a single additional word to a line can result in having to change multiple following lines (due to flowing of text onto those following lines). People either (a) don't bother or (b) submit patches that look significantly bigger than they are.

You could probably avoid this temporarily by recommending text be wrapped at 72 and allowing up to 79, but this would only delay the issue. My vote would be for single-line paragraphs for the documentation. However, I don't know how much this would impact peoples' workflow.

> > >   * 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.
> 
> Maybe we should add a target to validate Markdown on builds, like we
> have targets to check other invariants.

Automation is always a win but I'm not aware of any way to validate formatting of documents (PDF, HTML, Markdown etc.). You'll never be in a situation whereby the Markdown will fail to convert to HTML - you'll just see some really funky output. I'll have a look around and chat to some folks.