All of lore.kernel.org
 help / color / mirror / Atom feed
From: Alejandro Colomar <colomar.6.4.3@gmail.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: linux-man <linux-man@vger.kernel.org>,
	Florian Weimer <fweimer@redhat.com>,
	libbsd@lists.freedesktop.org
Subject: Re: [IDEA] New pages for types: structs and typedfefs
Date: Sun, 13 Sep 2020 23:29:21 +0200	[thread overview]
Message-ID: <65e2bdf5-425b-9381-b1ac-3f101113c70f@gmail.com> (raw)
In-Reply-To: <3a56a8af-6371-89f3-cac2-31dd64791c99@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



  reply	other threads:[~2020-09-13 21:29 UTC|newest]

Thread overview: 51+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-09-11 12:47 [IDEA] New pages for types: structs and typedfefs Alejandro Colomar
2020-09-12  6:33 ` Michael Kerrisk (man-pages)
2020-09-12  8:59   ` Alejandro Colomar
2020-09-12  9:26     ` Alejandro Colomar
2020-09-13 12:01     ` Michael Kerrisk (man-pages)
2020-09-13 12:53       ` Alejandro Colomar
2020-09-13 20:20         ` Michael Kerrisk (man-pages)
2020-09-13 21:29           ` Alejandro Colomar [this message]
2020-09-14  0:20             ` [RFC v1] system_data_types.7: Draft (and links to it: <type>.3) Alejandro Colomar
2020-09-14 10:37               ` Michael Kerrisk (man-pages)
2020-09-14 10:55                 ` Michael Kerrisk (man-pages)
2020-09-22 20:21             ` [IDEA] New pages for types: structs and typedfefs Michael Kerrisk (man-pages)
2020-09-22 20:38               ` Thorsten Glaser
2020-09-23  8:36                 ` Michael Kerrisk (man-pages)
2020-09-23 19:54                   ` Thorsten Glaser
2020-09-14  9:19       ` Jakub Wilk
2020-09-14  9:49         ` Alejandro Colomar
2020-09-18  2:16       ` Guillem Jover
2020-09-19  8:45         ` Michael Kerrisk (man-pages)
2020-09-14 10:22 ` Alejandro Colomar
2020-09-14 14:03   ` [RFC v2] system_data_types.7: Draft v2 Alejandro Colomar
2020-09-14 15:00     ` Michael Kerrisk (man-pages)
2020-09-14 15:52       ` Alejandro Colomar
2020-09-14 19:33         ` Michael Kerrisk (man-pages)
2020-09-15  0:47   ` [RFC v3] sigval.3, ssize_t.3, suseconds_t.3, time_t.3, timer_t.3, timespec.3, timeval.3, system_data_types.7: Document system types (draft v3) Alejandro Colomar
2020-09-15  6:22     ` Michael Kerrisk (man-pages)
2020-09-15 13:33   ` [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval Alejandro Colomar
2020-09-15 21:30     ` Michael Kerrisk (man-pages)
2020-09-16  0:59       ` Thorsten Glaser
2020-09-16  8:03         ` Michael Kerrisk (man-pages)
2020-09-16 10:06           ` Andries E. Brouwer
2020-09-16 11:00             ` Michael Kerrisk (man-pages)
2020-09-16 10:52   ` [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
2020-09-16 10:56     ` Alejandro Colomar
2020-09-16 11:01   ` [RFC v6] " Alejandro Colomar
2020-09-16 19:24     ` Michael Kerrisk (man-pages)
2020-09-16 19:51       ` Alejandro Colomar
2020-09-16 21:32         ` Thorsten Glaser
2020-09-17  9:23           ` Alejandro Colomar
2020-09-17 10:27         ` Michael Kerrisk (man-pages)
2020-09-17 10:42   ` [PATCH v7 0/8] Document system data types Alejandro Colomar
2020-09-17 21:05     ` Michael Kerrisk (man-pages)
2020-09-17 21:16       ` Alejandro Colomar
2020-09-17 10:42   ` [PATCH v7 1/8] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 2/8] sigval.3: Add link page Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 3/8] ssize_t.3: " Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 4/8] suseconds_t.3: " Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 5/8] time_t.3: " Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 6/8] timer_t.3: " Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 7/8] timespec.3: " Alejandro Colomar
2020-09-17 10:43   ` [PATCH v7 8/8] timeval.3: " Alejandro Colomar

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=65e2bdf5-425b-9381-b1ac-3f101113c70f@gmail.com \
    --to=colomar.6.4.3@gmail.com \
    --cc=fweimer@redhat.com \
    --cc=libbsd@lists.freedesktop.org \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.