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). > 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. > > > > * 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. _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
