On 09/27/2017 07:30 PM, Sandra Loosemore wrote:
> On 09/27/2017 03:05 AM, Rainer Orth wrote:
>> Hi Andreas,
>>
>>> On 09/27/2017 10:10 AM, Rainer Orth wrote:
>>>> Hi Andreas,
>>>>
>>>>> On 09/26/2017 02:26 PM, Rainer Orth wrote:
>>>>>> Hi Andreas,
>>>>>>
>>>>>>> diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
>>>>>>> index 307c726..3acfd85 100644
>>>>>>> --- a/gcc/doc/sourcebuild.texi
>>>>>>> +++ b/gcc/doc/sourcebuild.texi
>>>>>>> @@ -1398,6 +1398,9 @@ Target supports a vector misalign access.
>>>>>>> @item vect_no_align
>>>>>>> Target does not support a vector alignment mechanism.
>>>>>>>
>>>>>>> +@item vect_no_peel
>>>>>>> +Target does not require any loop peeling for alignment purposes.
>>>>>>> +
>>>>>>> @item vect_no_int_min_max
>>>>>>> Target does not support a vector min and max instruction on
>>>>>>> @code{int}.
>>>>>>
>>>>>> please keep the items sorted alphabetically.
>>>>>
>>>>> The items do not appear to be sorted alphabetically.
>>>>
>>>> they should be. Your patch makes the ordering even more random.
>>>>
>>>> Patch to fix this preapproved ;-)
>>> The items rather appear to be arranged by subject. Does it really make
>>> sense do pull items like this
>>> apart just to have it in alphabetical order?
>>>
>>> @item vect_intfloat_cvt
>>> Target supports conversion from @code{signed int} to @code{float}.
>>>
>>> @item vect_uintfloat_cvt
>>> Target supports conversion from @code{unsigned int} to @code{float}.
>>>
>>> @item vect_floatint_cvt
>>> Target supports conversion from @code{float} to @code{signed int}.
>>>
>>> @item vect_floatuint_cvt
>>> Target supports conversion from @code{float} to @code{unsigned int}.
>>>
>>>
>>> I've added the no_peel item intentionally to the hw_misalign/no_align block.
>>
>> granted, there are some attempts at that, but I find it hard to make my
>> way through that longish list. The way it is, you have to skip through
>> the whole list beginning to end. Texinfo seems to have no subsubsection
>> which would allow to make the sub-grouping explicit...
>>
>> Let's hear what Sandra thinks.
>
> Ummmm. There is no common convention in the GCC documentation and other
> parts of the manual do deliberately diverge from alphabetization in
> places. There's a perpetual tension between putting the most
> commonly-needed information first vs grouping things by related concepts
> vs alphabetize vs the tendency of people to insert new items at random
> places in an existing list regardless of how it's previously been
> organized. :-(
>
> Alphabetical lists are useful when you already know the name of the
> thing you are searching for, but almost everybody reads the
> documentation in a web browser or PDF viewer with a search feature
> nowadays so you can find the term no matter how the list is sorted. So
> I'd say we shouldn't alphabetize as a matter of policy if there is some
> other organization that makes sense.
>
> In this case, the section is already broken into multiple sublists by
> topic, most of the sublists are fairly short, and where there's some
> discernible sort order within the sublists, it seems to be grouping
> related things together rather than alphabetical. So I wouldn't insist
> on alphabetizing this particular sublist either.
>
> -Sandra
Ok thanks for the clarification. I'll try to fit the documentation updates into
the existing
structure. Updated patchset here:
https://gcc.gnu.org/ml/gcc-patches/2017-09/msg01862.html
Bye,
-Andreas-
