> 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: > > > > > * 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. > > (a) isn't a real problem in the editors that most programmers use. In > Emacs, type M-q; in vi, type "gqap". > > I'm willing to deal with (b).
I wasn't aware of these options. That'll suit just fine. Hopefully Sublime will have something similar. > > 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. > > > > > * 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. _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
