[sword-devel] Markup Options

Jonathan Morgan jonmmorgan at gmail.com
Thu Dec 2 06:13:47 MST 2010

On Thu, Dec 2, 2010 at 1:51 AM, Greg Hellings <greg.hellings at gmail.com>wrote:

> On Wed, Dec 1, 2010 at 7:40 AM, Jonathan Morgan <jonmmorgan at gmail.com>
> wrote:
> > From an application developer's point of view, I'm not convinced that per
> > module CSS is a good idea.  Here are some reasons:
> > 1. I'm not convinced of "well-defined use of HTML+CSS classes".  Some
> things
> > may be well-defined, but I know BPBible does a lot of customisation of
> the
> > SWORD generated HTML and uses a lot of custom CSS, and some or all of
> these
> > things might break CSS designed for other apps (and vice versa).  I also
> do
> > not like the idea that my changes to either the HTML generated or the CSS
> > breaks the display of a module I have never seen.
> I believe the phrase would mean the SWORD library would produce a well
> defined set of HTML elements with classes attached to help preserve
> the semantic meaning.  It would then be up to the consumer of that
> HTML - the application - to provide its own CSS.  Adding extra CSS
> classes as per an application's specific desires ought to be as easy
> as extending the filter and just adding a few extra lines of code for
> each particular case.  Extraneous CSS classes can readily be ignored
> simply by not having a corresponding definition in the app's CSS.
> BPBible does lots of customization, BibleTime does as well, and
> certainly other apps do customize to some extent.  If the filters were
> good and easily extensible (and any of the XML processing technologies
> would work in that regard), BPBible's customizations could either be
> readily incorporated to the engine to benefit others who desire them
> or maintained in BPBible directly without having to throw out the base
> filters.  And, of course, BPBible would continue to maintain its own
> stylesheets.

We use different structure, not just different classes.

> > 2. Some of the application specific styles and user choices may conflict
> > with the module styles.  For example, I know Bibletime has themes, which
> can
> > change colour of foreground text, background, ...  I have thought about
> > doing a similar thing for BPBible.  However, this isn't going to work in
> > cases like: our poor user has a dark background, and the module developer
> > has decided to mark a particular text feature in a dark purple which is
> > nearly illegible.
> I remember Jaak voicing this complaint when I brought up CSS
> stylesheets in BibleTime.  This is actually an argument FOR having
> external stylesheets.  I don't see why either of you would think our
> case is any different from a web browser in this regard.CSS was
> designed specifically to handle exactly the situation you bring up.
> In web browsers styles will cascade downwards with earlier styles
> overwriting later ones in the following order:
> 1) User-Agent stylesheet
> 2) External stylesheets
> 3) Internal stylesheets
> 4) Inline styles
> Often times a user can insert their own styles for accessibility
> reasons and I believe those are usually placed at priority 3.5 in that
> list.  Currently SWORD applications only support (1) and (4).
> BibleTime's offer of themes simply changes the values of the
> User-Agent stylesheet.  My first attempt at creating SWORD modules way
> back when I thought that (2) and (3) would be supported since the
> library documentation claimed to support ThML, but it ends up the
> entire header of the document gets thrown away during import but
> inline styles remain intact.  As a result, (3) would be difficult to
> handle in SWORD without major changes to the entire library and import
> system but (2) would be very easy to add simply by honoring a config
> option.
> Since the stylesheets within each level cascade with later ones
> overriding earlier ones, in order to maintain the specified order, the
> following in the HTML header would be all that is required:
> <link rel="stylesheet" type="text/css"
> href="/usr/share/bpbible/css/default.css" />
> <link rel="stylesheet" type="text/css"
> href="modules/ztext/mymodule/css/module.css" />
> <link rel="stylesheet" type="text/css"
> href="~/.bpbible/css/user-overrides.css" />
> That way the application provides the default appearances, the module
> can provide overrides to the default if it desires, and the user can
> provide overrides which take the highest priority.  Yes, if a module
> specifies Black background and the user has said they want all text to
> be in dark grey, that would be difficult to read.  But this can happen
> easily on the web already and somehow we are all able to manage.
> Since we are using identical technology, why can't we use its full
> power?

It seems to me a given that when you introduce more sources of styles you
introduce more potential for conflict.

The reason this is different from what is on the web is that the default
browser CSS is fairly similar across all browsers.  I know there are
differences in text size and padding levels and that some people go to the
trouble of using browser reset stylesheets, etc., etc., but that's still a
fairly small difference.  Here we have multiple applications and I don't
think it's reasonable to assume that the base CSS is fairly similar across
apps in the same way as it is across browsers.  While it is true that users
can apply custom stylesheets, I suspect the number that actually do so is
fairly minimal, so web developers just have to test on a stock-standard
browser build (and do).

If we had HTML modules then I would expect it to be exactly the same as on
the web.  Since we have higher-level constructs and more rendering options,
it is much more likely that there will be transformations that radically
affect presentation without affecting text, and module CSS can interfere
with this.  [If browsers showed as much difference between renderings of the
same text as some frontends do, I would be very worried].

Currently the only way to get styles through to the display layer are
> through number 4 - inline styles.  As it is, I can already mess with
> every one of those settings you're worried about me messing up and the
> user can do nothing about it (unless, of course, BPBible strips the
> style attribute from ThML sources).  So by providing me the ability to
> set an external stylesheet, you would actually be fixing what is
> currently a usability bug in apps.  Thus both you and Jaak are correct
> to worry about this issue, but the result of your worrying should be
> to enable external styles not disable them.

So what you are saying is that you use something that might break it more so
we should officially support something that might break it a bit less?

> 3. As well as the single verse search results Karl mentions, the parallel
> > case comes to mind.  If I have multiple books using different style
> sheets,
> > how do I manage that?  Do the parallel Bibles end up in different and
> > clashing styles?  In BPBible I think we even generate different HTML for
> > these different places, so there's not even a guarantee that these styles
> > will apply cleanly and work.  However, if any modules are created that
> rely
> > on these custom styles to look OK, then we will need to have some way of
> > making them work in all these different contexts.
> Of course, this depends on how you allow styles to be defined.  I
> think, again, this is actually an argument _for_ having external
> styles available for each module.  Currently I can only put my styles
> inline on an element.  Therefore no matter what you do, without
> stripping off the style attribute, I can easily break the display of
> your parallel Bibles.  If I were permitted an external stylesheet
> which I could apply to well defined HTML classes, then the user-agent
> could decide what to do based on its own method for parallel display.
> BibleTime, IIRC, uses a <table> with each verse in a new <tr> and each
> version displayed side-by-side within a <td>.  It is likely that
> BibleTime would simply not include the external stylesheet of either
> module at this point; alternatively they could be included in some
> deterministic order - reverse order of their addition to the display,
> for instance, that way the version which has been there longest takes
> precedence.  If a display were using a frameset or iframes, then it
> might opt to include the stylesheets.

Which bears out my original point: if the display in the CSS is ever
required to make the module look right, then it will end up broken in some
views where we can't/won't include it.

Adding support for external stylesheets actually gives the application
> and user MORE control, not less, and still allows the module creator a
> sane way of specifying styles without having to resort to inserting
> their styles as style attributes on every single ThML element they
> want stylized (and would also allow the creation of OSIS modules where
> the style is influenced by the module creator instead of only by the
> engine and user agent, provided the applications can agree on
> well-defined mapping between OSIS and HTML).

All I'm pointing out is that more control is not always a good thing, and
often doesn't come for free as much as people think/hope it will.


Of course all of this ignores BibleCS, which I personally don't mind.
> But it probably doesn't honor inline styles any more than external
> styles, so I have no interest in it. :)
> --Greg
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20101203/a6742f80/attachment.html>

More information about the sword-devel mailing list