Open Stack

On Sun, 18 Feb 2018 15:44:04 -0500
Doug Hellmann <doug at doughellmann.com> 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