On Wed, Dec 03, 2014 at 05:09:08PM -0500, Ted Unangst wrote:
> On Wed, Dec 03, 2014 at 20:36, Jason McIntyre wrote:
>
> >
> > i think in the past some developers expressed a desire to not demote
> > -and and -or, as they are traditional bsd. i think we changed the
> > examples as a desire to provide portable examples, but still wanted to
> > keep the idea that -and and -or are perfectly acceptable.
> >
> > that's my understanding, and the reason why i made those changes in that
> > way.
> >
> > if i have it wrong, or there is a sudden swing to pooh pooh -and and
> > -or, i guess we could change it a bit. still, i dislike the idea of
> > documenting that we support stuff but try to obfuscate it. it just makes
> > it harder for the reader (and therefore still think my diff was better ;)
>
> I think when the BSD way is superior in some way, it makes sense to
> elevate it. For -and vs -a, it doesn't seem like -and is obviously
> superior.
>
well, there's a difference between showing something as superior and not
demoting something. as far as i'm aware, we're not demoting.
> For madvise, we document the posix options as an alternative, which I
> think makes sense. They're longer and uglier.
>
> I am at first glance unsure if the two -a -and operators are equal or
> different when they are both documented together. Could they be
> synonyms or two variations of similar operators? I like the idea that
> one spelling is documented and then the second introduced as an
> alternative.
>
you can;t deduce everything at a glance. if it's not clear, read the
text.
sorry, but
item
item
blah blah description
is really common in our pages. it means we've grouped them. maybe
they're the same, maybe they're just related. but the format totally
makes sense.
so, for example, you could also level this complaint against this
current text:
expression -and expression
expression expression
are they equal or different?
hiding it away does not make sense, unless we are deliberately trying to
get people not to use these forms. are we? if you don;t care about
portability, why prefer the posix forms?
> If you think my diff is too wordy, we could move the text around a
> bit, perhaps later in the section and say "-and and -or are
> alternatives to -a and -o" or such.
i don;t think it's too wordy. i think it doesn;t make sense.
unless we are saying we don;t want people using these formats.
jmc
