[cgi-wiki-dev] Formatter API change proposal
Mon, 24 Jan 2005 23:56:07 +0100
OK, continuing the tradition of following up on myself, I've thought
some more about this and...
> 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
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
------ 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.
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.
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.
=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... :-)
email@example.com firstname.lastname@example.org email@example.com
Homepage: http://www.kjetil.kjernsmo.net/ OpenPGP KeyID: 6A6A0BBC