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