[ovs-dev] Markdown coding standard

Ben Pfaff blp at nicira.com
Mon Feb 16 18:37:24 UTC 2015


On Mon, Feb 16, 2015 at 09:18:44AM +0000, Finucane, Stephen wrote:
> > On Fri, Feb 13, 2015 at 05:28:34PM +0000, Finucane, Stephen wrote:
> > > > On Thu, Feb 12, 2015 at 09:21:35PM +0100, Thomas Graf wrote:
> > > > > On 02/12/15 at 05:37pm, Finucane, Stephen wrote:
> > > 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.
> > 
> > I don't care whether the right margin is a little ragged; a 72 to 79
> > range is fine with me.
> > 
> > Single-line paragraphs make (b) much worse in practice because it looks
> > like every paragraph that changed at all changed entirely.  Then you
> > have to resort to wordwise-diffs and scroll far to the right (in gitk)
> > or just basically give up on spotting changes (in git diff) to see the
> > actual changes.  Line-per-paragraph is the way that the OpenFlow LaTeX
> > spec is maintained and, trust me, it's not better.  Finally, if you try
> > to view a file that consists of line-per-paragraph text in viewers that
> > don't wrap lines, it's basically unreadable since you have to scroll
> > left and right like mad.
> 
> OK. I'm used to diff tools/apps (meld, Gerrit) that are capable of
> wordwise-diffs so I don't see this (ditto with editors' wrapping of
> text). This could be nasty otherwise for sure.

I guess I need to learn about "meld" sometimes then.  I'm in the habit
of using gitk, "git citool", and Emacs' tools for version control
(primarily git-status and smerge-mode).  Most of these support wordwise
diffs but still make it somewhat hard to see small diffs to very long
lines.  Is "meld" good at that problem?

> > > > > >   * 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.
> > 
> > I didn't realize there wasn't an idea of valid vs. invalid Markdown.
> 
> Exactly. Checked this out of the weekend and I got diddly squat. We
> could probably do easy manual validation with a "HTML visual diff"
> tool but I'm no webdev and am thus unsure of the availability of such
> tools.

I guess I've been thinking of the .md files as text primarily but with
some decent enhancements in some environments.  From that point of view
it's not crucial to make them perfect.

If we spot some common errors in Markdown, then it would probably be
simple to write a "lint"-like tool to check for those.  (I used to work
with a collaborator named Tal who made some very characteristic errors,
so I wrote a tool named "tallint" to find and report them automatically.
It was very handy.)



More information about the dev mailing list