intro(3type) draft

[Alejandro Colomar <alx.manpages@gmail.com>]

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