[sword-devel] Markup Options

[Greg Hellings]

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.

>
> 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?

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.

>
> 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.

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).

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