Open Stack

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

Doug