intro(3type) draft

intro(3type) draft

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1821 bytes --]

Hi Branden and Ingo!

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 used temporarily the term [sub]chapter to see how it fits.

Cheers,

Alex

---

intro(3type)                                        intro(3type)

NAME
        intro - introduction to library types

DESCRIPTION
        Subchapter  3type  of the manual describes the types pro‐
        vided by C libraries.

CAVEATS
        The separation of chapter 3 of this manual into  subchap‐
        ters  is  only  a  consequence of the organization in the
        Standard C Library.  Probably, a better design for a  li‐
        brary would be such that each header file is minimal, and
        contains  only  one or a few APIs, and the types and con‐
        stants that are intrinsic to that API.   Types  and  con‐
        stants  that  are to be used by many APIs can go in sepa‐
        rate header files that provide no APIs.   That  organiza‐
        tion  permits  writing manual pages that document exactly
        one header file per manual page, which will  improve  the
        readability of the documentation, and thereby the usabil‐
        ity of the software.

SEE ALSO
        intro(3)

Linux man‐pages (unreleased) (date)                 intro(3type)


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

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

Re: intro(3type) draft

[G. Branden Robinson]

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

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: intro(3type) draft

[G. Branden Robinson]

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

Hi Alex,

Quick thinko fix to my own material.

At 2022-11-16T18:06:48-0600, G. Branden Robinson wrote:
> are termed an API or _application program interface_.  Types and

s/program/&ming/

Regards,
Branden

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