[sword-devel] filter <!P> patch

[Greg Hellings]

On Thu, Dec 13, 2012 at 8:31 PM, Ben Morgan <benpmorgan at gmail.com> wrote:
> G'day Ben,
>
> From the viewpoint of a frontend developer, I don't really want this change
> committed.
>
> If this change is committed, it will break existing frontends which look for
> <!P>, and it produces little or no benefit - <!P> may be invalid, but I
> think it will just get ignored.
> We already don't really have a good way to generate completely validated
> HTML as it is as too many of the existing modules have markup issues (I've
> been running across these recently...)

I disagree with this mentality. I remember learning a basic principle
of software engineering - be very rigorous about what you produce and
very lenient about what you accept. If we claim to produce HTML or
XHTML then by all means we should produce as close to that as
possible. But if we say we accept OSIS of a particular format, then we
should be as lenient as is safe and reasonable about deviations from
that. Both of these make a better experience for our users.

If a user of the engine - be that a front end developer or any other
application that might connect to SWORD - receives exactly what they
expect, then we save them the trouble and frustration of figuring out,
"What is this invalid HTML that I'm receiving? I thought this was an
HTML filter..." Likewise, if we accept modules that might have a
little bit of typos or errors in them but are "close enough" that we
can figure out how to handle it, then we give our module creators a
pleasant experience.

The import utilities are pretty snazzy about accepting a wide range of
input from the users, even if it is not exactly perfect. So that means
there might be some modules out there that don't parse exactly well
into our output targets. But that doesn't mean we ought to be lax in
what we produce. We should be very particular about only producing
what is documented. If our APIs and docs state we produce valid HTML
fragments then we should and this is a bug in either the software or
the documentation. If they state that we produce proto-HTML with
certain strings (like <!P>) that need post-processing by the client,
then the current behavior is fine.

As to the matter of breaking front-ends, library upgrades are going to
do that anyway. The current development head of BibleTime does not
even compile against the current development head of SWORD because the
API has changed - so we have to maintain a compatibility branch that
includes changes which are going to be in the next release of SWORD
(*whenever that might be). If this behavior changes, it will be
another thing that we have to keep abreast of and update. I don't
think that changing the behavior of the library and documenting that
output has changed from <!P> to <!--p--> will be such a hardship on
applications, especially if it puts us in line with our documentation.

So it really comes down to: what do we claim to produce, and does our
library produce it? If not, then this is a bug that needs to be
addressed by changing the library or changing our claims.

--Greg

>
> If it is ever a problem for anyone, I think it's easy enough to instruct
> them to do the replacement just like everyone already does.
>
> God Bless,
> Ben
> -------------------------------------------------------------
> For I have no pleasure in the death of anyone,
> declares the Lord God; so turn, and live.”
> Ezekiel 18:32 (ESV)
>
>
>
>
> On Fri, Dec 14, 2012 at 12:45 PM, <cricketc at gmail.com> wrote:
>>
>> Hello,
>>
>> I came across the following output in various filters: <!P>. A comment
>> in the code talks about this being a silent html comment that the
>> front-ends can replace if desired. However, that tag is not valid
>> (x)html (I guess it used to be a valid comment).
>>
>> I'm attaching a patch that replaces <!P> with <!--p-->, so that it's
>> valid html or xhtml output, in all the filters where I found <!P>.
>>
>> If anyone would be willing to commit this, that would be great. Or, if
>> there are changes/improvements/problems with the patch, please let me
>> know.
>>
>> Thanks,
>> -Ben
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel at crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
>
>
>
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page