Closed alejandro-colomar closed 9 months ago
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)
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. :)
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.
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.
@madler: Can you look this PR?
Only if the man pages could be automatically generated from zlib.h. I don't want to maintain documentation in two different places.
@madler Would you consider removing the docs from zlib.h and having only the manual pages (so no duplication)?
@alejandro-colomar Thank you for your offer to work on man pages, but I prefer to leave the documentation in zlib.h.
I understand. :)
Signed-off-by: Alejandro Colomar alx@nginx.com