Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

Hi Michael

On 9/13/20 10:20 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On 9/13/20 2:53 PM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> On 9/13/20 2:01 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar
>> <colomar.6.4.3@gmail.com> wrote:
>
> [...]
>
> Here I would *not* show these kinds of typedefs. The point is
> that these types should be treated as being somewhat unknown
> (e.g., for casts in printf()). Here, I think instead maybe we
> just have a statement that POSIX makes no specific requirements
> for the representation of this type.

Agreed.

>
> [...]
>
>>>> Sure.  And for the structs, I'd allow:
>>>>
>>>> 'man struct timespec'   (For simplicity)
>>>> 'man struct-timespec'   (Similar to the git man pages)
>>>> 'man timespec'          (For compatibility with libbsd)
>>>
>> [...]
>
> Offhand, I can't think of any such conflicts. Many of the data
> types have names suffixed with "_t", and there should be no
> conflicts there.

Yes.

>
> For other types, such as timeval, timespec, etc, I don't expect
> there are many conflicts. One case that I can think of where
> there's a function and a struct with the same name is 'sigaction'.
> But there's not really a problem there, since, on the one hand,
> I don't expect that that is one of the types that should be
> documented in system_data_types(7),
Why not?

> and on the other hand,
> currently "man sigaction" takes you to the page that documents
> both the function and the structure.

Fair enough.

>> [...]
>
> Throw in 'struct timeval' too?

Fine.

>
>> Do you think there's any page that has a similar format to what we want
>> to base on it?
>
> I think nothing special is required. See man-pages(7) for general
> info on the layout of pages. I expect the types can be placed
> as an alphabetically ordered hanging list under DESCRIPTION.

Ok.

New question:

I've already started and I'm writing the short description on 'time_t'.

POSIX has copyright and all rights reserved, but do you think it would
be fair use to copy descriptions such as "Used for time in seconds."?
Or do I have to come up with a new short description?

Thanks,

Alex