POSIX conformance document

POSIX conformance document

[Bruno Haible]

POSIX [1] specifies that conforming implementations shall come with a
"conformance document" that describes "implementation-defined" characteristics
[2]. Two such example conformance documents are [3], [4].

For Linux (or any Linux distro), I cannot find such a document on the web.

Is such a document only considered useful for business/marketing purposes?
Isn't there some value in it also for regular users and developers?

Will there be some effort to create such a document for the upcoming
POSIX.1-2024 standard, for Linux and the GNU libraries and tools?

I'm asking because I've collected the answers for all *gettext() functions
and the msgfmt and xgettext programs (that will be part of this new POSIX),
but I don't know where to best document them. Likely in the manual of
GNU libc and GNU gettext, right?

         Bruno

[1] https://en.wikipedia.org/wiki/POSIX
[2] https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/basedefs/V1_chap02.html
[3] https://empyreal96.github.io/nt-info-depot/SourceLevel/base/subsys/posix/pcd.doc
[4] https://www.qnx.com/developers/docs/6.5.0SP1.update/com.qnx.doc.neutrino_prog/posix_conformance.html

Re: POSIX conformance document

[Alejandro Colomar]

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

Hi Bruno!

On Fri, May 31, 2024 at 11:21:28PM GMT, Bruno Haible wrote:
> POSIX [1] specifies that conforming implementations shall come with a
> "conformance document" that describes "implementation-defined" characteristics
> [2]. Two such example conformance documents are [3], [4].
> 
> For Linux (or any Linux distro), I cannot find such a document on the web.

Most Linux distros are not UNIX certified.  There have been a few, from
what I read, but don't know much about them.  I found one that is in
the Wikipedia, and which has links to such a document:

<https://en.wikipedia.org/wiki/Inspur_K-UX>
<https://web.archive.org/web/20151210194928/http://www.opengroup.org/csq/repository/RID%3Dinspur/XY1/1.html>

That one is UNIX 03 certified, which is POSIX.1-2001 + XSI extensions.

Maybe that helps.

> Is such a document only considered useful for business/marketing purposes?

Mostly.

> Isn't there some value in it also for regular users and developers?

The documentation for each API usually documents the implementation-
defined behavior, and differences to other systems.  We don't have it
centralized in a single document, but we have something.

While I don't see much usefulness for myself as a user in having a
centralized document for that, I can't discard usefulness for others, or
for myself at a different time.

> Will there be some effort to create such a document for the upcoming
> POSIX.1-2024 standard, for Linux and the GNU libraries and tools?

Heh, I suppose not, unless some company sponsors it, or some individual
feels a strong need for it.  But just guessing.

> 
> I'm asking because I've collected the answers for all *gettext() functions
> and the msgfmt and xgettext programs (that will be part of this new POSIX),
> but I don't know where to best document them. Likely in the manual of
> GNU libc and GNU gettext, right?

Yeah, that could be a good place for it.  The manual pages are in GNU
gettext:

	$ apt-file find -x 'man/man3/[a-z]*gettext.3'
	gettext-base: /usr/share/man/man3/dcgettext.3.gz
	gettext-base: /usr/share/man/man3/dcngettext.3.gz
	gettext-base: /usr/share/man/man3/dgettext.3.gz
	gettext-base: /usr/share/man/man3/dngettext.3.gz
	gettext-base: /usr/share/man/man3/gettext.3.gz
	gettext-base: /usr/share/man/man3/ngettext.3.gz

In the Linux man-pages project I'm documenting differences with POSIX or
the BSDs in the VERSIONS section (see man-pages(7)); sometimes in
CAVEATS, if it's a tricky detail; it depends.  You could send a patch
for their manual pages adding that section documenting the differences
with POSIX, or the implementation details.

>          Bruno
> 
> [1] https://en.wikipedia.org/wiki/POSIX
> [2] https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/basedefs/V1_chap02.html
> [3] https://empyreal96.github.io/nt-info-depot/SourceLevel/base/subsys/posix/pcd.doc
> [4] https://www.qnx.com/developers/docs/6.5.0SP1.update/com.qnx.doc.neutrino_prog/posix_conformance.html

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: POSIX conformance document

[Brian Inglis]

On 2024-05-31 15:21, Bruno Haible wrote:
> POSIX [1] specifies that conforming implementations shall come with a
> "conformance document" that describes "implementation-defined" characteristics
> [2]. Two such example conformance documents are [3], [4].
> 
> For Linux (or any Linux distro), I cannot find such a document on the web.
> 
> Is such a document only considered useful for business/marketing purposes?
> Isn't there some value in it also for regular users and developers?
> 
> Will there be some effort to create such a document for the upcoming
> POSIX.1-2024 standard, for Linux and the GNU libraries and tools?
> 
> I'm asking because I've collected the answers for all *gettext() functions
> and the msgfmt and xgettext programs (that will be part of this new POSIX),
> but I don't know where to best document them. Likely in the manual of
> GNU libc and GNU gettext, right?
> 
>           Bruno
> 
> [1] https://en.wikipedia.org/wiki/POSIX
> [2] https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/basedefs/V1_chap02.html
> [3] https://empyreal96.github.io/nt-info-depot/SourceLevel/base/subsys/posix/pcd.doc
> [4] https://www.qnx.com/developers/docs/6.5.0SP1.update/com.qnx.doc.neutrino_prog/posix_conformance.html

Hi Bruno,

You might want to sign up to the Open Group to access the Austin Group (POSIX) 
documents (including latest drafts to update your info and documents), become a 
member, email your questions, and participate as a documentor and implementor on 
their list:

	https://www.opengroup.org/austin/

You can also view their discussions and document defect issues on web archive:

	https://www.mail-archive.com/austin-group-l@opengroup.org/

and get updates from an Atom/RSS Feed (e.g. Firefox/Chrome/... bookmark feeds):

	https://www.mail-archive.com/austin-group-l@opengroup.org/maillist.xml

without subscribing to their ML.

[Alex has contacted them about POSIX man pages, and hopefully may get info about 
updating POSIX man pages to 2024: latest draft standard has been approved by 
IEEE and Open Group Board, internal publication of the standard with final front 
matter is due 2024-06-14, ISO/IEC ballot closes 2024-06-28.]

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: POSIX conformance document

[Alejandro Colomar]

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

Hi Brian,

On Sat, Jun 01, 2024 at 09:15:23AM GMT, Brian Inglis wrote:
> On 2024-05-31 15:21, Bruno Haible wrote:
> [Alex has contacted them about POSIX man pages,

This is a reference to
<https://lore.kernel.org/linux-man/25806cfb-8845-e4d4-6c18-6b02cb8c92ab@kernel.org/T/#u>

I'll ping Andrew Josey about it.

> and hopefully may get info
> about updating POSIX man pages to 2024:

I hope they'll do.

> latest draft standard has been
> approved by IEEE and Open Group Board, internal publication of the standard
> with final front matter is due 2024-06-14, ISO/IEC ballot closes
> 2024-06-28.]

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: POSIX conformance document

[Bruno Haible]

Hi Alejandro,

> > Is such a document only considered useful for business/marketing purposes?
> 
> Mostly.
> 
> > Isn't there some value in it also for regular users and developers?
> 
> The documentation for each API usually documents the implementation-
> defined behavior, and differences to other systems.  We don't have it
> centralized in a single document, but we have something.
> 
> While I don't see much usefulness for myself as a user in having a
> centralized document for that, ...

OK, so let's discard the idea of a centralized document, and document it
where appropriate. Documenting it in individual package documentations
is also easier for our community.

> > Will there be some effort to create such a document for the upcoming
> > POSIX.1-2024 standard, for Linux and the GNU libraries and tools?
> 
> Heh, I suppose not, unless some company sponsors it, or some individual
> feels a strong need for it.  But just guessing.

I agree; there is no reason why anyone should make this effort in 2024
after it wasn't done in 2018.

> In the Linux man-pages project I'm documenting differences with POSIX or
> the BSDs in the VERSIONS section (see man-pages(7)); sometimes in
> CAVEATS, if it's a tricky detail; it depends.

Thanks for the pointer.

VERSIONS or STANDARDS (previously: CONFORMING TO) appear adequate for
documenting implementation-defined behaviour.

For texinfo documentation, I guess it will be up to the individual package
maintainer.

Bruno

Re: POSIX conformance document

[Bruno Haible]

Brian Inglis wrote:
> You might want to sign up to the Open Group to access the Austin Group (POSIX) 
> documents (including latest drafts to update your info and documents), become a 
> member, email your questions, and participate as a documentor and implementor on 
> their list:
> 
> 	https://www.opengroup.org/austin/
> 
> You can also view their discussions and document defect issues on web archive:
> 
> 	https://www.mail-archive.com/austin-group-l@opengroup.org/
> 
> and get updates from an Atom/RSS Feed (e.g. Firefox/Chrome/... bookmark feeds):
> 
> 	https://www.mail-archive.com/austin-group-l@opengroup.org/maillist.xml
> 
> without subscribing to their ML.

Thanks for the instructions. For simple defects, I occasionally do this.
For defects with a possibly complex treatment (due to different standards and/or
different incompatible vendors) I prefer to go through Eric Blake, who has
more experience in this area than I have.

Bruno