Re: Reference manual bug

[Gary Houston]

> From: Mikael Djurfeldt <address@hidden>
> Date: Fri, 23 Feb 2001 09:28:35 -0500
> 
> The node "C Port Interface" in the reference manual contains the
> following paragraph:
> 
>   Port basics
> -----------  
>   
>   There are two main data structures.  A port type object (ptob) is of
>   type `scm_ptob_descriptor'.  A port instance is of type `scm_port'.
>   Given an `SCM' variable which points to a port, the corresponding C
>   port object can be obtained using the `SCM_PTAB_ENTRY' macro.  The ptob
>   can be obtained by using `SCM_PTOBNUM' to give an index into the
>   `scm_ptobs' global array.
> 
> I think I can call me a "Guile veteran".  However, I have to confess
> that I hardly understand this text.

It's the sort of pseudo-documentation you get when the author doesn't
want to spend more than 10 minutes or so and thinks (maybe
incorrectly) that it's better than nothing.  Yes, I did write it.

> There are too many concept labels here: "port type object", "ptob",
> "port type object type", "scm_ptob_descriptor", "port instance", "port
> instance type", "scm_port", "port" and "port object".
> 
> It seems like one can use fewer labels.  For example, why introduce
> the notion of a port type object at all?  Why not just call it a
> scm_ptob_descriptor?

I don't follow: it's an attempt to document the concept of ptob: "port
type object" is actually the explanation of what it is.  It would be
better if expanded a bit.

> (Or, maybe we should just rename scm_ptob_decriptor into scm_port_type
> in the source?  If so, we should probably rename scm_ptobs to
> scm_port_types.)

Probably not worth it at present: the current ptob system may need to
be replaced with something more flexible, if such a thing can be
devised.