[openstack-dev] [docs] About the convention to use '.' instead of 'source'.

Jeremy Stanley fungi at yuggoth.org
Sun Feb 18 16:01:52 UTC 2018


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.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180218/6691ef80/attachment.sig>


More information about the OpenStack-dev mailing list