zlibVersion.3: Add manual page

[alejandro-colomar]

Signed-off-by: Alejandro Colomar alx@nginx.com

[alejandro-colomar]

Here goes a rendering of the page:

$ MANWIDTH=80 man ./zlibVersion.3 | cat
zlibVersion(3)             Library Functions Manual             zlibVersion(3)

Name
       zlibVersion - get version of the zlib runtime library

Library
       zlib compression library (zlib, -lz)

Synopsis
       #include <zlib.h>

       const char *zlibVersion(void);

       #define ZLIB_VERSION  /* ... */

Description
       zlibVersion(3)  can be called by the application to compare the version
       of the runtime library with the version of the header file used at com‐
       pilation (ZLIB_VERSION).  If the major version  (the  first  character)
       differs,  the  runtime  library is not compatible with the header file.
       This  check  is   performed   automatically   by   deflateInit(3)   and
       inflateInit(3).

Return value
       A static string similar to "1.2.13.1‐motley".

Errors
       None.

Examples
       #include <err.h>
       #include <stdio.h>
       #include <stdlib.h>

       #include <zlib.h>

       int
       main(void)
       {
            printf("zlib header version:  %s\n", ZLIB_VERSION);
            printf("zlib runtime version: %s\n", zlibVersion());

            if (ZLIB_VERSION[0] != zlibVersion()[0])
                 errx(EXIT_FAILURE, "incompatible zlib runtime version");

            exit(EXIT_SUCCESS);
       }

See also
       zlib(3).

zlib (unreleased)                   (date)                      zlibVersion(3)

[alejandro-colomar]

The page contains two placeholders, one for the version, and one for the date. In the Linux man-pages project, I fill those automatically at release time (make dist performs that automatically), and it is never added to the git history. But I see in zlib you hardcode the versions and dates, so maybe I should hardcode them to some value, following what zlib.3 does. Whatever you prefer. However, I find that a bit meh, since I don't think you'll release in xx Oct 2022. :)

[alejandro-colomar]

I used the MR macro, which is better for generating PDF or HTML versions of the manual page, but which requires a recent-enough version of groff(1), or a tweak for old versions.

That macro was introduced a few months ago in upstream groff, which will in a few weeks be released as 1.23.0. (Edit: groff-1.23.0 was released half a year ago, and is now in all mainstream distros)

The tweak to make groff-1.22.4 understand this macro is present in Debian Testing: https://sources.debian.org/patches/groff/1.22.4-10/add-groff-1.23-forward-compatibility.patch/

Since the tweak to old groff is simple, I believe this macro is good enough. There are some alternatives from which we can choose:

• Use the macro in the source, but replace it with a script at build time: s/MR \([^ ]*\) \([^ ]*\) */IR \1 (\2)/

• Do the replacement suggested above in the source. The downside is that information is lost, and this can't be undone via a script.

[alejandro-colomar]

Is there interest in having manual pages? This page is only for a trivial function, but I'd write them for more functions, if there is.

[Neustradamus]

@madler: Can you look this PR?

[madler]

Only if the man pages could be automatically generated from zlib.h. I don't want to maintain documentation in two different places.

[alejandro-colomar]

@madler Would you consider removing the docs from zlib.h and having only the manual pages (so no duplication)?

[madler]

@alejandro-colomar Thank you for your offer to work on man pages, but I prefer to leave the documentation in zlib.h.

[alejandro-colomar]

I understand. :)