Re: Manual pages from glibc-doc

[Xavier Leroy <Xavier.Leroy@inria.fr>]

[-- Attachment #1: Type: text/plain, Size: 13154 bytes --]

On Sun, May 21, 2023 at 12:25 PM Alejandro Colomar <alx.manpages@gmail.com>
wrote:

> Hi Xavier,
>
> On 5/21/23 11:40, Xavier Leroy wrote:
> > Hello Alex,
> >
> > On Thu, May 18, 2023 at 8:23 PM Alex Colomar <alx.manpages@gmail.com>
> wrote:
> >
> >> Hello Xavier,
> >>
> >> I see there are some manual pages in the glibc-doc package.
> >> Most of glibc's manual pages are part of the Linux man-pages
> >> project.  I would be interested in absorbing the ones present
> >> in the glibc-doc package into the Linux man-pages project.
> >>
> >> That would probably remove whatever overhead there is in
> >> maintaining a separate package just for a few manual pages.
> >>
> >> Would you like that?
> >>
> >
> > Well, I wrote those man pages a long time ago, in the late 1990's, to
> > document the first version of the LinuxThreads library.  The LinuxThreads
> > code was later completely rewritten by Drepper and Molnar at Redhat (for
> > the better!), so I forgot about the man pages, and did not know they were
> > still distributed as part of the glibc-doc package.
> >
> > I hope the pages have been maintained and updated by the Glibc team,
> > because the first version that I wrote was fairly specific to the
> > LinuxThreads v1 implementation and its limitations, and is probably
> useless
> > today.  Likewise, the POSIX Threads standard changed quite a bit in the
> > last 25 years, with new functions that are implemented in Glibc but lack
> a
> > man page in glibc-doc.
>
> Thanks for the history.  I've investigated a bit after your email.
>

Thanks for the historian's work !


> It seems that the pages were removed from glibc upstream in 2005 [1],
>

This is consistent with the development of NPTL, the LinuxTheads
replacement, at RedHat in 2004-2005.  Once NPTL was ready for inclusion in
Glibc, it made sense to remove the LinuxThread man pages.


> and then imported in the Debian glibc source package later in 2013 [2].
>

I didn't know about that.  Strange move from the Debian maintainers.

The last time a page's text was updated seems from 2002 by Drepper.
>

OK, this confirms that the text is probably outdated.


>
> >
> > To answer your question:
> > - I don't think it's a good idea to take these man pages "as is" and drop
> > them in the man-pages project, because they are probably obsolete and
> > incomplete.
> > - However, if you or others would like to use these man pages as a
> starting
> > point for a comprehensive, up-to-date and maintained documentation for
> > POSIX Threads functions in Linux, you're most welcome.
> > - In both cases, I'd like my name and e-mail address to be removed from
> the
> > man pages, as I no longer support them.
>
> Yes, I plan to import these pages, specifying the historic details
> found in this thread, keeping your name in the import commit, if you
> don't mind, and then remove your name in the first commit, and start
> cleaning them up.  I'd compare them to the POSIX pages, to see if
> there's any obviously outdated stuff, and fix it.  Small details
> that are not obvious from reading POSIX, I guess time will fix them.
>
> So, you want your name removed.  Any other request?  The pages don't
> seem to have a license.  Should GPL be applied to them as they were
> once part of glibc?  If so, is GPL-3.0-or-later a good one?  Or
> should I relicense as Linux-man-pages-copyleft?
>

I'm happy with the man-pages-copyleft  license.  If you need me to write a
more formal message for the licensing of these pages, let me know.

No other requests than 1- removing my name, and 2- updating the pages as
much as you and others can.



> Does the above plan look good to you?
>
> Yes !  Thank you for proposing it.

Kind regards,

- Xavier Leroy



> Cheers,
> Alex
>
> >
> > Kind regards,
> >
> > - Xavier Leroy
> >
> >
> >
> >
> >
> >
> >>
> >> Cheers,
> >> Alex
> >>
> >> --
> >> <http://www.alejandro-colomar.es/>
> >> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
> >>
> >
>
> [1]:
>
> alx@debian:~/src/gnu/glibc/glibc$ git lg --stat --
> 'linuxthreads/man/pthread*';
> * 88e3fbcb5d N - Sun, 3 Jul 2005 04:40:34 +0000 (18 years ago)
> |           linuxthreads, linuxthreads_db: Directories removed (preserved
> in ports repository). - Roland McGrath|
> |  linuxthreads/man/pthread_atfork.man               |  53 -----
> |  linuxthreads/man/pthread_attr_init.man            | 221
> ------------------
> |  linuxthreads/man/pthread_cancel.man               | 155 -------------
> |  linuxthreads/man/pthread_cleanup_push.man         | 194 ----------------
> |  linuxthreads/man/pthread_cond_init.man            | 234
> --------------------
> |  linuxthreads/man/pthread_condattr_init.man        |  39 ----
> |  linuxthreads/man/pthread_create.man               |  46 ----
> |  linuxthreads/man/pthread_detach.man               |  44 ----
> |  linuxthreads/man/pthread_equal.man                |  23 --
> |  linuxthreads/man/pthread_exit.man                 |  32 ---
> |  linuxthreads/man/pthread_join.man                 |  70 ------
> |  linuxthreads/man/pthread_key_create.man           | 151 -------------
> |  .../man/pthread_kill_other_threads_np.man         |  40 ----
> |  linuxthreads/man/pthread_mutex_init.man           | 213
> ------------------
> |  linuxthreads/man/pthread_mutexattr_init.man       |  84 -------
> |  linuxthreads/man/pthread_mutexattr_setkind_np.man |  39 ----
> |  linuxthreads/man/pthread_once.man                 |  34 ---
> |  linuxthreads/man/pthread_self.man                 |  23 --
> |  linuxthreads/man/pthread_setschedparam.man        |  79 -------
> |  linuxthreads/man/pthread_sigmask.man              | 123 ----------
> |  20 files changed, 1897 deletions(-)
>
> * a334319f65 N - Wed, 22 Dec 2004 20:10:10 +0000 (18 years ago)
> |           (CFLAGS-tst-align.c): Add -mpreferred-stack-boundary=4. -
> Ulrich Drepper|
> |  linuxthreads/man/pthread_atfork.man               |  53 +++++
> |  linuxthreads/man/pthread_attr_init.man            | 221
> ++++++++++++++++++
> |  linuxthreads/man/pthread_cancel.man               | 155 +++++++++++++
> |  linuxthreads/man/pthread_cleanup_push.man         | 194 ++++++++++++++++
> |  linuxthreads/man/pthread_cond_init.man            | 234
> ++++++++++++++++++++
> |  linuxthreads/man/pthread_condattr_init.man        |  39 ++++
> |  linuxthreads/man/pthread_create.man               |  46 ++++
> |  linuxthreads/man/pthread_detach.man               |  44 ++++
> |  linuxthreads/man/pthread_equal.man                |  23 ++
> |  linuxthreads/man/pthread_exit.man                 |  32 +++
> |  linuxthreads/man/pthread_join.man                 |  70 ++++++
> |  linuxthreads/man/pthread_key_create.man           | 151 +++++++++++++
> |  .../man/pthread_kill_other_threads_np.man         |  40 ++++
> |  linuxthreads/man/pthread_mutex_init.man           | 213
> ++++++++++++++++++
> |  linuxthreads/man/pthread_mutexattr_init.man       |  84 +++++++
> |  linuxthreads/man/pthread_mutexattr_setkind_np.man |  39 ++++
> |  linuxthreads/man/pthread_once.man                 |  34 +++
> |  linuxthreads/man/pthread_self.man                 |  23 ++
> |  linuxthreads/man/pthread_setschedparam.man        |  79 +++++++
> |  linuxthreads/man/pthread_sigmask.man              | 123 ++++++++++
> |  20 files changed, 1897 insertions(+)
>
> * 0ecb606cb6 N - Thu, 12 Jul 2007 18:26:36 +0000 (16 years ago)
> |           2.5-18.1 - Jakub Jelinek|
> |  linuxthreads/man/pthread_atfork.man               |  53 -----
> |  linuxthreads/man/pthread_attr_init.man            | 221
> ------------------
> |  linuxthreads/man/pthread_cancel.man               | 155 -------------
> |  linuxthreads/man/pthread_cleanup_push.man         | 194 ----------------
> |  linuxthreads/man/pthread_cond_init.man            | 234
> --------------------
> |  linuxthreads/man/pthread_condattr_init.man        |  39 ----
> |  linuxthreads/man/pthread_create.man               |  46 ----
> |  linuxthreads/man/pthread_detach.man               |  44 ----
> |  linuxthreads/man/pthread_equal.man                |  23 --
> |  linuxthreads/man/pthread_exit.man                 |  32 ---
> |  linuxthreads/man/pthread_join.man                 |  70 ------
> |  linuxthreads/man/pthread_key_create.man           | 151 -------------
> |  .../man/pthread_kill_other_threads_np.man         |  40 ----
> |  linuxthreads/man/pthread_mutex_init.man           | 213
> ------------------
> |  linuxthreads/man/pthread_mutexattr_init.man       |  84 -------
> |  linuxthreads/man/pthread_mutexattr_setkind_np.man |  39 ----
> |  linuxthreads/man/pthread_once.man                 |  34 ---
> |  linuxthreads/man/pthread_self.man                 |  23 --
> |  linuxthreads/man/pthread_setschedparam.man        |  79 -------
> |  linuxthreads/man/pthread_sigmask.man              | 123 ----------
> |  20 files changed, 1897 deletions(-)
>
> * 79996eeed1 N - Sun, 28 Jul 2002 19:04:09 +0000 (21 years ago)
> |           Update. - Ulrich Drepper|
> |  linuxthreads/man/pthread_mutex_init.man | 2 +-
> |  1 file changed, 1 insertion(+), 1 deletion(-)
>
> * 6736e93bab N - Sat, 6 Apr 2002 01:45:15 +0000 (21 years ago)
> |           Update. - Ulrich Drepper|
> |  linuxthreads/man/pthread_mutexattr_init.man       | 20 +++++------
> |  linuxthreads/man/pthread_mutexattr_setkind_np.man | 39
> +++++++++++++++++++++
> |  2 files changed, 49 insertions(+), 10 deletions(-)
>
> * 638621aff9 N - Fri, 14 Dec 2001 22:17:03 +0000 (21 years ago)
> |           Update. - Ulrich Drepper|
> |  linuxthreads/man/pthread_atfork.man | 13 ++++---------
> |  1 file changed, 4 insertions(+), 9 deletions(-)
>
> * 0a51738ed9 N - Sun, 23 May 1999 09:27:35 +0000 (24 years ago)
> |           Correct example. - Ulrich Drepper|
> |  linuxthreads/man/pthread_cond_init.man | 5 ++---
> |  1 file changed, 2 insertions(+), 3 deletions(-)
>
> * 5afdca0087 N - Wed, 11 Mar 1998 12:42:25 +0000 (25 years ago)
>             LinuxThreads library. - Ulrich Drepper
>    linuxthreads/man/pthread_atfork.man               |  58 +++++
>    linuxthreads/man/pthread_attr_init.man            | 221
> ++++++++++++++++++
>    linuxthreads/man/pthread_cancel.man               | 155 +++++++++++++
>    linuxthreads/man/pthread_cleanup_push.man         | 194 ++++++++++++++++
>    linuxthreads/man/pthread_cond_init.man            | 235
> ++++++++++++++++++++
>    linuxthreads/man/pthread_condattr_init.man        |  39 ++++
>    linuxthreads/man/pthread_create.man               |  46 ++++
>    linuxthreads/man/pthread_detach.man               |  44 ++++
>    linuxthreads/man/pthread_equal.man                |  23 ++
>    linuxthreads/man/pthread_exit.man                 |  32 +++
>    linuxthreads/man/pthread_join.man                 |  70 ++++++
>    linuxthreads/man/pthread_key_create.man           | 151 +++++++++++++
>    .../man/pthread_kill_other_threads_np.man         |  40 ++++
>    linuxthreads/man/pthread_mutex_init.man           | 213
> ++++++++++++++++++
>    linuxthreads/man/pthread_mutexattr_init.man       |  84 +++++++
>    linuxthreads/man/pthread_once.man                 |  34 +++
>    linuxthreads/man/pthread_self.man                 |  23 ++
>    linuxthreads/man/pthread_setschedparam.man        |  79 +++++++
>    linuxthreads/man/pthread_sigmask.man              | 123 ++++++++++
>    19 files changed, 1864 insertions(+)
>
>
>
> [2]:
>
> alx@debian:~/src/debian/glibc$ git lg --stat --
> 'debian/local/manpages/pthread*';
> * 2c35c554 N - Fri, 29 Nov 2013 11:00:45 +0000 (9 years ago)
>               * Remove linuxthreads from the tarball:     - rules.d/
> tarball.mk: don't fetech linuxthreads and linuxthreads_db.     - rules.d/
> build.mk: don't build linuxthreads manpages.     - rules: don't run make
> clean in linuxthreads directory.     - patches/any/local-sysctl.diff: drop
> the linuxthreads part.     - patches/all/local-pthread-manpages.diff:
> remove.     - local/manpages/pthread_*.3: import the few remaining
> linuxthreads       manpages.     - debhelper.in/glibc-doc.manpages:
> update manpage locations. - Aurelien Jarno
>    debian/local/manpages/pthread_atfork.3               |  53 +++++++
>    debian/local/manpages/pthread_cond_init.3            | 229
> ++++++++++++++++++++++++++++++
>    debian/local/manpages/pthread_condattr_init.3        |  38 +++++
>    debian/local/manpages/pthread_key_create.3           | 151
> ++++++++++++++++++++
>    debian/local/manpages/pthread_mutex_init.3           | 209
> +++++++++++++++++++++++++++
>    debian/local/manpages/pthread_mutexattr_init.3       |  81 +++++++++++
>    debian/local/manpages/pthread_mutexattr_setkind_np.3 |  38 +++++
>    debian/local/manpages/pthread_once.3                 |  34 +++++
>    8 files changed, 833 insertions(+)
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
>