Re: POSIX manual pages

[Brian Inglis <Brian.Inglis@Shaw.ca>]

On 2023-09-13 15:37, Alejandro Colomar wrote:
> Hi Brian,
> 
> On 2023-09-13 20:09, Brian Inglis wrote:
>> On 2023-09-13 10:15, Alejandro Colomar wrote:
>>> Hi Andrew,
>>>
>>> [I reordered your answer for my response.]
>>>
>>> On 2023-09-05 14:34, Andrew Josey wrote:
>>>>
>>>> hi Alejandro
>>>>
>>>> Apologies for the delay.
>>>
>>> NP
>>>
>>>>
>>>> Are you in touch with Michael Kerrisk?
>>>
>>> Nope.
>>>
>>>> It also appeared in discussions with Michael in 2020, that he had a way to convert the source format to man page format.
>>>
>>> Yep, this is probably "the way":
>>>
>>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages-posix.git/tree/posix.py>
>>>
>>>> In the past we have worked with him and made a permissions grant - 
>>>> which outlines the terms we are able to grant — these are limited by
>>>> the copyright holders.

>>> I understand.  Would it be possible to suggest the copyright holders opening a
>>> little bit more?  The C++ standard seems to be more open (it has a public git
>>> repository with the source of the drafts) [1].  Maybe POSIX could do something
>>> similar? It would make contributions to the man-pages-posix project easier,
>>> as contributors would be able to test the script with the original sources;
>>> instead of just blindly trying something, and asking the maintainer to try it
>>> with the secret sources.
>>>
>>> [1]:  <https://github.com/cplusplus/draft>

>> Perhaps you could request terms allowing you to maintain your own downstream
>> repo(s) of the *generated* man pages,

> This does exist: <https://git.kernel.org/pub/scm/docs/man-pages/man-pages-posix.git/>
> Although it would be nice to have the terms be explicitly stated in the repository.

Already there in POSIX-COPYRIGHT?

>> as you do of the linux man pages @ alejandro-colomar.es & git.kernel.org?

> And I have a clone at <http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages-posix.git/>

>> There would need to be a COPYRIGHT/COLOPHON disclaimer about content issues to
>> be addressed to the Austin group, and man page formatting issues to a posix-man
>> list, if they are or you want to keep them separate, and kernel.org is agreeable
>> to hosting a vger./lore.kernel.org posix-man list and git.kernel.org repo?

> This section also exists:
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages-posix.git/tree/man-pages-posix-2017/man3p/printf.3p#n24>

>> There are unlikely to be man page changes issued between releases (or released
>> between issues?).

> But I don't want to maintain the generated man(7) pages.  I want to be able to:
> 
> -  Contribute directly to the POSIX source code.

The Austin group has their own mailing list, bug tracker, process for tracking 
defect reports, handling their formatting and content issues, and a sometimes 
prolonged timeframe for doing so.

You can only be responsible for formatting POSIX/SUS/Open Group content in a 
compatible manner.

> -  Maintain the translation script.
> 
>     Alternatively, I'd like to make groff(1) be able to translate files written
>     in any macro package into roff(7), but that's either hard or impossible.
>     Branden, do you regard it as hard or as impossible?  Is the same answer true
>     for a groff(1)-like program written from scratch with this in mind?  :)
> 
> -  Remove the man(7) generated pages from the repo.  One should build the pages
>     with make(1), but they should not be part of any repository.

If there are any formatting issues, that is what you have to maintain.

>     I'd like to include the POSIX source code as a git submodule, or something
>     similar.  Or maybe have the man-pages-posix repo be a fork of it.

That may be a good way to access the upstream, but the file names look to me 
like SCCS edit temp files, so perhaps a strictly POSIX system using only 
strictly POSIX tools, on which they can "eat their own dog food"?

As your upstream content appears from the sample shown by Eric and the 
conversion in posix.py to possibly be a mix of mm and mdoc macros and variants, 
it might be easier to generate POSIX pages in mandoc/groff_mdoc format, if you 
could live with that, and maintain those.

[That is how the other main genre of (BSD) distros do man pages, and most 
systems have a mix from BSD derived packages (and those who prefer mandoc to 
man) e.g. dash(1), dejagnu(1), etc.]

-- 
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