Gentoo Archives: gentoo-dev

From: Duncan <1i5t5.duncan@×××.net>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Re: spec draft for cross-compile support in future EAPI (EAPI-5)
Date: Sat, 16 Jun 2012 20:55:39
In Reply to: [gentoo-dev] spec draft for cross-compile support in future EAPI (EAPI-5) by Thomas Sachau
Thomas Sachau posted on Sat, 16 Jun 2012 12:31:40 +0200 as excerpted:

> Since i am not that sure about my ability to write formal specs, i am > presenting my first draft for further review and suggestions for > improvement.
Just a format suggestion. Call it nitpicky if you want, and yes, my client isn't perfect, but I'm sure people with a bit of experience writing such specs will tell you I'm not alone... Several of your points ended up as very long single lines. My client can wrap, but that wraps the points as well (so for example 2.1 starts in the middle of a line). So I was left with the choice to either massively horizontally scroll, or of trying to figure out where one point ended and another began, since wrapping it... /wrapped/ it, so points appeared in the middle of a line. Please: * If you use long lines, leave a vertical space (blank line) between points so when a client wraps them, they wrap as individual paragraphs. * Alternatively, wrap at something sensible. (The traditional wrap for posting is 72 chars or so, 80 minus a few to allow a few levels of quoting without rewrap. I wouldn't complain at 90, but if you're going to bother, you might as well go the standard route and avoid further issues.) Long lines as paragraphs would probably be easier especially early in the process when you're modifying a lot, but you still risk (even more) limited clients having issues with it. YMMV. -- Duncan - List replies preferred. No HTML msgs. "Every nonfree program has a lord, a master -- and if you use the program, he is your master." Richard Stallman