[sword-devel] UnlockInfo .conf entry

Jaak Ristioja jaak at ristioja.ee
Sat Dec 29 17:39:03 MST 2018

I like the idea, because it is useful information for the users. Here
are some of the thoughts I gathered for this:

<brainstorm xmlns="https://en.wikipedia.org/wiki/Brainstorming">

Why can't the About= entry contain this information?

I'm unsure whether "UnlockInfo" is the best name.

Is it safe to assume that this entry will only be relevant for modules
with a CipherKey= entry?

Using HTML might be a can of worms:
* What version of HTML is permitted?
* How do we ensure future-compatibility?
* If the contents for the UnlockInfo field are to contain a segment of
HTML (and not a whole HTML document), what is the content model?
  * For example, would it be safe to embed the contents of the
UnlockInfo field directly inside a <td> element or should it be a <p>?
  * Can UnlockInfo= contain
<img>/<audio>/<video>/<object>/<embed>/<script> etc elements?
  * How about attributes, e.g. <strong
style='background:url("http://track.me/I_consent")'> or <span

Modules can originate from untrusted sources. I think it might be a bit
too much to assume that all frontends can properly sanitize the HTML
value, unless we only allow a very restricted subset of the HTML syntax,
e.g. only plain text, HTML entities and <a> elements only one allowed
and mandatory href attribute. Note that <b> and <i> etc are discouraged
in HTML5, <u> was completely redefined. Will <a> ("anchor") still be
valid in HTML6 or will <link> be repurposed for hyperlinks as well?

Hence I suggest to use a simple URL (or URI, RFC 3986) instead of HTML.
Simple documents (including HTML pages, PDF or any other types of files)
could be embedded using the data: URI scheme (RFC 2397). Frontends could
pass the URI to the OS/desktop/browser to be opened or attempt to
display the information inline (e.g. show a web view widget for
HTTP/HTTPS URIs or similar). Optionally, frontends can display a
warning/confirmation dialog to the user before opening the URI.

Perhaps it would be wiser to have two fields: one for the URI and
another for plain text? I currently have no suggestions for the exact
semantics of naming of such entries, but both of these could be
displayed by frontends. The plain text could be a description of the
URI, or contain full information about obtaining the key. One or both of
the entries could be optional. Frontends could opt to detect URLs in the
plain text as well and render these as hyperlinks.

Or perhaps we should use a subset of markdown or similar instead?
However, other markup languages could suffer from problems similar to HTML.



On 30.12.18 00:02, Troy A. Griffitts wrote:
> Dear Frontend Developers,
> In an effort to gain more publishers-- even those who desire to lock and
> sell some of their modules, I would like to add a new .conf entry:
> UnlockInfo
> Up until now, we've relied on the About entry containing something that
> lets the user know how to obtain unlock codes from publishers selling
> codes to unlock their modules.  This entry would isolate just those
> instructions to a specific entry and would allow a frontend to do
> something like:
> If (moduleToInstall.getConfEntry("UnlockInfo")) {
>   showDialog("<p>The publisher of this modules requires for you to
> obtain an unlock code.  This code can be entered below, instructions
> from the publisher are as follows:</p>" +
> moduleToInstall.getConfEntry("UnlockInfo"));
> }
> Like many of our entries, this new UnlockInfo entry will allow HTML
> links and will likely contain a direct link from the publisher to their
> store entry to purchase an unlock code.
> An example would be something like:
> UnlockInfo=An unlock code for the Larry Fitzgerald NFL HOF Edition of
> the New Testament, with memorable career moments encouraging the
> believer to press on when those around fall short, may be obtained
> directly from the NFL store here: <a target="_blank"
> href="https://nfl.com/shop/lf-nfl-hof-nt-sword-module">Larry Fitzgerald
> NFL HOF Edition of the New Testament - SWORD Module</a>
> Let me know if you have any comments or ideas,
> Troy
> _______________________________________________
> 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

More information about the sword-devel mailing list