OK, continuing the tradition of following up on myself, I've thought some more about this and... I wrote:
When pushed, I might even agree it is the most sensible thing to do, so that the calling application wouldn't need to care about error situations.
I figured it was a good idea to make it must return a fragment or document. I have rewritten the spec to reflect that. Also, I have moved the format-specific things and some discussion into a sub-section of its own. ------ Spec excerpt ------ This method must return the converted string. It is however free to return a document fragment or a full document based on what is most appropriate for the module. A user who needs to be sure to retrieve either must call the C<document> or C<fragment> method afterwards. =item C<document> The C<document> method may be called on the object after it has been initialized with the C<format> method. It must return a full document. In the case where an underlying helper module has no concept of full document, the method must nevertheless make a best effort to return something that can be regarded a standalone document. =item C<fragment> The C<fragment> method may be called on the object after it has been initialized with the C<format> method. It shall only return a minimal fragment of the converted text, as little as possible markup shall be added to the fragment. In the case where only a full document is available from an underlying helper module, it should make a best effort to strip down to a minimal fragment. [snip] =head2 Meaning of fragment vs. document It is to be anticipated that not all formats have a concept of full document and others not a fragment. To save the user the trouble of dealing with an error situation, the Formatter must make a best effort to return both. What is meant by a fragment and a full document varies from format to format, and must be dealt with on a per format basis. In the case where it really doesn't make sense to return either a fragment or document, the Formatter may produce a warning, but must nevertheless return a best effort fragment or document. For HTML, a full document is understood to be a complete valid, HTML document. The largest possible HTML fragment consists of the child elements of the C<body> element, excluding C<body> itself. For XML, any well-formed XML document can be a full document, and any well-balanced XML region can be a fragment. An XML fragment should not contain a Prolog or Document Type Declaration. ----- end excerpt ----- As you can see, I haven't changed the names of the methods, or redefined ->format. I feel that the only thing to win by doing it is to save a single line, and while it may not be very Lazy to have that extra line, I feel there is much to be gained in clarity and consistency by having those two extra methods. I still would like to hear your input, I would really like it if there is a common API for this kind of formatting for both our projects, and I'm very open to arguments, it is just that I have to finish this and move on by noon.... Sorry to be pushing this so hard, as I said previously, I'm not usually this stressed out and hard-hitting, it is Real World demands that does this to me... :-) Best, Kjetil -- Kjetil Kjernsmo Astrophysicist/IT Consultant/Skeptic/Ski-orienteer/Orienteer/Mountaineer kjetil@kjernsmo.net webmaster@skepsis.no editor@learn-orienteering.org Homepage: http://www.kjetil.kjernsmo.net/ OpenPGP KeyID: 6A6A0BBC