In my opinion, this outline puts too much weight on the first section. I would prefer it to be made of just the basic concepts and have forward references to the apropiate sections.
For example: I wouldn't put the list of methods supported by each of the types in Section 1. Instead of this, I would point to the reference of Built-in classes. This would be a set of documents structured by class, where the user would find: - The inheritance tree of the Class - The run-time and compile-time properties that affect the behaviour of objects of this class. - The public methods and attributes of the class. - What is its value in boolean/numeric/Foo... context. For example: the reference of the Object class would explain the rw, const, etc.. properties; and the methods that any object implements. The same for the String, Number, Code, etc.. class. I imagine it could structured in something like this: Class String ------------------------------- Represents Perl String values. It is automatically constructed when you write literal strings, or string quotes (q, qq). INHERITS FROM: Object (or Scalar?) PROPERTIES: (?) CONTEXT TRANSFORMATIONS: - bool: When used in boolean context, returns true if the string has non-zero length and false otherwise. - num: Returns the number represtened by the string. If there is no possible interpretation as a number, returns 0. The interpretation of number representations is the same that when writing literal numbers. METHODS: - chars(): return the number of chars that the string is made of - bytes(): return the length of the string in bytes. This will be usually different from chars, whenever the string is in a multi-byte econding. .... --------------------------- (as you can see, my imagination is not very original indeed) I also would remove any formal explanation of operators, to avoid duplication with an Operators chapter. And I think that the right place to explain sprintf formats is the sprintf function reference. This approach would leave Section 1 with the role of introducing the basic concepts and an explanation of how to use them (with some informal examples, and pointers to right sections). A final question: I am afraid I don't know what "implementing type" and "overloading implementing type" are about. Could you explain them? Thanks. -angel
