On Sun, 18 Feb 2018 15:44:04 -0500 Doug Hellmann <[email protected]> wrote:
> Excerpts from Jeremy Stanley's message of 2018-02-18 16:01:52 +0000: > > On 2018-02-18 03:55:51 -0600 (-0600), Monty Taylor wrote: > > [...] > > > I'd honestly argue in favor of assuming bash and using 'source' > > > because it's more readable. We don't make allowances for alternate > > > shells in our examples anyway. > > > > > > I personally try to use 'source' vs . and $() vs. `` as > > > aggressively as I can. > > > > > > That said - I completely agree with fungi on the description of > > > the tradeoffs of each direction, and I do think it's valuable to > > > pick one for the docs. > > > > Yes, it's not my call but I too would prefer more readable examples > > over a strict adherence to POSIX. As long as we say somewhere that > > our examples assume the user is in a GNU bash(1) environment and > > that the examples may require minor adjustment for other shells, I > > think that's a perfectly reasonable approach. If there's a > > documentation style guide, that too would be a great place to > > encourage examples following certain conventions such as source > > instead of ., $() instead of ``, [] instead of test, an so on... and > > provide a place to explain the rationale so that reviewers have a > > convenient response they can link for bulk "improvements" which seem > > to indicate ignorance of our reasons for these choices. > > I've proposed reverting the style-guide change that seems to have led to > this discussion in https://review.openstack.org/#/c/545718/2 FYI, we've just approved this. Thanks, pk __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
