Hi Alex,
At 2022-11-17T00:13:56+0100, Alejandro Colomar wrote:
> Per the request of Branden that I should discourage programmers of
> writing their manuals with subchapters, which fundamentally means
> discouraging programmers of writing their libraries (or modules, or
> whatever a given language uses) in a way that you can't document a
> header in a single page, I wrote the following introductory page
> intro(3type).
>
> The caveat that you'll read should go either in all intro([23]\w+)
> pages. We could put it in the main section into pages too. I want to
> hear some opinions about this.
I agree with both of those suggestions.
> I used temporarily the term [sub]chapter to see how it fits.
I think the adoption of the term (sub)chapter has a potential benefit in
that it removes a terminological collision with (sub)sections as
subdivisions of individual man pages (man: SH, SS; mdoc: Sh, Ss).
If this terminological reform is adopted, I think it should be done
across all of (1) Linux man-pages, (2) groff, (3) mandoc, and (4)
man-db. If we can't speak with one voice on this then I think it's
better not to undertake that reform at all, to avoid frustrating the
discoverabilty of man pages.
Possibly the biggest barrier to this is the mnemonic and documentation
of the man(1) '-s' option. In man-db man, '-C' and '-c' are both
already in use.
Probably a good idea to loop Colin Watson in on this proposal of yours,
which is strictly speaking severable from the below.
Whatever term is settled on, I'll refer to as $SUBDIVISION below.
> intro(3type) intro(3type)
>
> NAME
> intro - introduction to library types
More information in the summary description is better for keyword
searches.
I suggest:
**snip**
introduction to data types defined by the C library
**snip**
> DESCRIPTION
> Subchapter 3type of the manual describes the types pro‐
> vided by C libraries.
Now since the description restates the summary description, you'll want
to say something more substantive here.
> CAVEATS
I wouldn't use "CAVEATS" for this, at least not as I rewrote it below.
> The separation of chapter 3 of this manual into subchap‐
> ters is only a consequence of the organization in the
> Standard C Library.
I would recast this.
**snip**
$SUBDIVISION 3 of this manual is organized into sub${SUBDIVISION}s to
reflect the complex structure of the standard C library and its many
implementations. This difficult history frequently makes it a poor
example to follow in design, implementation, and presentation.
Ideally, a library for the C language is designed such that each header
file presents the interface to a coherent software module. It furnishes
a small number of function declarations and exposes only data types and
constants that are required for use of those functions. Together, these
are termed an API or _application program interface_. Types and
constants to be shared shared among multiple APIs should be placed in
header files that declare no functions. This organization permits a C
library module to be documented concisely with one header file per man
page. Such an approach improves the readability and accessibility of
library documentation, and thereby the usability of the software.
**snip**
But maybe this material is better placed intro(3) itself, unless you
want a lot of duplication for the sake of getting the message across.
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
