Jump to content

Please read the Forum Rules before posting.

Photo
* * * * * 3 votes

e-Sword Module Creation Guidelines


  • Please log in to reply
50 replies to this topic

#1 Josh Bond

Josh Bond

    Administrator

  • Administrators
  • PipPipPipPipPip
  • 2,890 posts
  • LocationGallatin, TN
Offline

Posted 03 January 2012 - 12:58 PM

*
POPULAR

This document describes the "best practices" for e-Sword module making based on my experience, my observations of Rick Meyers' officical resources, and my observations of Dr. Dave's resources.

Presentation Matters
I've seen numerous made for e-Sword and other Bible software packages that would receive an F if turned into a college professor for formatting alone. This post cannot possibly anticipate every bad formatting decision. I do attempt to point out the most common situations that arise.

But there is no substitute for "common sense" formatting. What do I mean by common sense? Example: I can tell you not to walk across the street when traffic is coming. But I can't anticipate every other situation that may arise that you should not do. You have to use common sense, right? Of course, that's apart of life.

The same applies to formatting. I can give examples, but I can't anticipate every single possibility that "looks bad". Learn to see what "looks bad" so you can strive for what "looks good". Learn what common sense formatting looks like. :)

But, But, This Takes Time!
Yes dear friend, GOOD module making DOES take time and is rarely done in a day. There are exceptions, but they are rare. Right now, for example, I'm spending quite a few extra hours on a resource to make it more usable in e-Sword, and to make the formatting easy to read. I know if I don't make these structural changes, people will not use it.

That's why making publishable quality e-Sword module is not for everyone. It requires time, patience, and persistence. Increasingly, I just dislike modules that have been "sloppily made".

But I just want to copy/paste and be done!
(I don't want to tooltip text. I don't want to convert roman numeral verse references to digits. I don't want to take time to proofread or proofscan....) Then, e-Sword module making is not for you. Poorly formatted e-Sword modules reflect poorly on e-Sword and BibleSupport.com. And poorly formatted text yields precious few users. If no one uses the text, then what have you accomplished? A digit increase on our upload numbers? That's not why we're dong this...

No one wants to read a module with...
OCR Errors
Text taken directly from an OCR provider should be cleaned. Seriously, no one wants to read:

HOAV GREAT IS <3©H> COMPARED WITH %3RTAL MAN.
  • Delete page headers/footers and page numbers that interfere with the text in e-Sword.
  • Correct spelling issues.
  • Remove odd line breaks. Notice how distracting it is if I, in mid sentence, just
  • switch to the next line for no reason. Text Flow should be consistent across monitor sizes and resolutions -- If you use manual line breaks, it may look great on your monitor--but no one elses!
Poor Paragraph Spacing
Create space between paragraphs.

EXAMPLE: Which screenshot below do you think is easier to read?

Attached File  good space.png   66.17K   44 downloads

Attached File  bad space.png   64.8K   25 downloads

If you picked the last screenshot, please re-think your decision to make e-Sword modules.

EXAMPLE: Similarly, does this look good? Notice that some paragraphs have too much space. Others have less. It's inconsistent. There's too many line breaks for some paragraphs. This doesn't look good.

Attached File  inconsistent spacing.png   56.25K   14 downloads

Poor Line Spacing
Line spacing should be set (in T3 or Microsoft Word) to 1 - 1.15.

EXAMPLE: Does line spacing look good when it's too cramped?

Attached File  bad line spacing.png   63.77K   11 downloads

EXAMPLE: Does line spacing look good when it's too spread?

Attached File  bad line spacing2.png   31.3K   8 downloads

Inconsistent Font Sizes or Font Sizes too small or large
This is annoying. If the reader wants to enlarge the text control, they can. You need not make resources with font size problems, as most of our readers do not have vision problems. Those that do can enlarge the text control within e-Sword.

EXAMPLE:

Attached File  font too large.png   51.05K   10 downloads

EXAMPLE: This is equally annoying:

Attached File  inconsistent fonts.png   50.61K   11 downloads

You Must ToolTip Scripture References and Strongs Numbers.
Remember, e-Sword didn't invent the electronic document. People can read text on the Internet, in Kindles, in printed books, and numerous other places offline and online. They don't have to use e-Sword. And they won't use e-Sword if you don't tooltip scripture references!

Topic files that are not tooltipped have zero use for many people. Why? If they have lookup a verse reference manually, what's the point of using e-Sword? You might as well read the material on Kindle for the PC. Or in your internet browser.

Commentaries and dictionaries still have value if they aren't tooltipped. But Brent Hildebrand has made tooltipping so easy, there's no excuse for not tooltipping your scripture references.

But Brent and Tooltip can't help you if you didn't bother to convert roman numeral scripture references to digits. We have macros for that, but in some cases, you will still need to convert some references manually.

Strong's Numbers, at an absolute minimum, should have an H or G preceding the number. If you wanted to go the "extra mile" format that number with the Tooltip color and underline it, so users know they can click it and see the definition in the dictionary window.

English Fonts

Topics
For topics, e-Sword uses the module maker's font choice. You should use Georgia (size 11 or 12--I prefer 11) or Times New Roman (size 12). Based on the way e-Sword renders text, this is seems to appeal to the broadest audience. The text size is consistent with official e-Sword modules. Headings and such can be slightly larger.

Commentaries, Dictionaries, Bibles, Devotionals, etc
For most commentaries, dictionaries, Bibles, devotionals, etc, e-Sword will override your font choice and size with the user's e-Sword selected font.
  • Please avoid constructing Bibles in a way that overrides the user's e-Sword selected font size. If you specify a font size in the RTF code for Bible text, the text will likely appear larger or smaller than the other Bible text for any given e-Sword user. Let e-Sword decide the size of the text for Bibles. Not doing so creates a poor experience for the end-user and your material is less likely to be used.
  • For all other resources, if you override the font, please use a reasonable font like Georgia or Times New Roman. Please use a reasonable font size of 10-12 (I prefer 11 for Georgia and 12 for Times New Roman). Please avoid overly large font sizes--it's annoying for the end-user and your resource is less likely to be used.

    I opened a devotional recently and the font size was so large, the resource was just unusable. The end user does not want to, and should not have to, resize the text control because your text does not conform to the rest of their e-Sword resources.
Don't Be Afraid to Make Necessary Changes
While I strongly urge you to create resources that respect the original layout and style of the original printed resource, sometimes changes are simply necessary.
  • Printed resources may have sacrificed vertical white space (paragraph and line spacing) to make publishing affordable. You are under no such constraints. Add line breaks and create white space as necessary to make the resource usable and readable. Bold headings if necessary. Don't be afraid to search replace a style/repetition of text to make it bold or a different color for easier reading--if it looks good. (Compare the Lange's test module with the website text, in this post for an example.
  • Restructure a resource if necessary. I urge caution here--we don't want to change the author's meaning or intent. But on occasion, this can be necessary. For example, the project I am currently working on--the printed edition should have been published all together. But it wasn't--it was published as it was written. When you attempt to combine 12 volumes in the exact organizational structure originally used in the printed edition, it does not work well in e-Sword. In this case, to make finding material easier, I am combining like sections in each volume (having 1 Expository Outlines for the OT section instead of 12 different ones). And in other sections, I'm reorganizing some material according to the Biblical canon order (instead of a random order or the order of publication). This way, readers can find what they're looking for easier. Use good sense here. Don't change the meaning.
Do Something With Footnotes
I have a macro that converts end of the page footnotes to in-line footnotes, commonly found in Microsoft Word documents. Do something with footnotes. Make them in-line. Put them at the end of each section. Put them at the end of each paragraph where used.

Don't leave them a garbled mess in the original text. Think twice before just removing them entirely. Footnotes are valuable!


Greek/Hebrew Text

Unicode
Ideally, Hebrew and Greek text should be in unicode format. That means, for every character displayed on screen, the RTF text contains the unicode equivalent. Many times, when you paste Greek or Hebrew text from other sources, the unicode is present in the RTF code. If you use Tooltip3's Greek keyboard (or a third party Greek or Hebrew keyboard that supports unicode), you can simply copy/paste the Greek and Hebrew symbols into the text. The proper unicode copied, behind the scenes, into the RTF code. NOTE: T3's keyboard does not support Greek vowel accents and so I do not sure it.

Greek/Hebrew Font Choice in T3
When using Tooltip, Greek and Hebrew should be changed to the font: TITUS Cyberbit Basic, the text enlarged to font size 12-14, and the text colored blue (RGB - Red: 0, Green: 0, Blue: 255). This is essentially Rick Meyers' standard he uses for his modules.

The blue font color is purely for aesthetic reasons. But It helps break up the text and it helps the reader immediately recognize the foreign language. I highly recommend it and doing so can almost always be automated if your preparing the module in Microsoft Word.

Making Final Adjustments to Greek/Hebrew using T4 - Commentaries & Dictionaries, NOT Topics.
ToolTip NT includes the ability to make Hebrew and Greek unicode characters display properly in e-Sword. Click Tools > Greek Unicode Fixup and Click Tools > Hebrew Unicode Fixup

Another example of formatting do's and don'ts. Which looks better?

Don't:
Attached File  formatting-dont.png   61.37K   19 downloads

Do:
Attached File  formatting-do.png   42.16K   13 downloads


Use Modern Tools
Would you write a sermon, or a term paper, or a speech, with a typewriter? You could. But would you? Would you ride horse and buggy on a 300 mile trip? You could. But would you?

If you need my assistance (which I'm more than happy to give you), please use modern tools. I've had to correct the course of a few would-be module makers who read on the forums how others code RTF by hand and manually edit databases. It's not necessary and consumes too much time in most cases.

Please use a word processor and Tooltip 4 (or some other module creation tool). It saves tremendous time. And it enables me to help you. I can't teach you the syntax for RTF easily and it's unnecessary.

Look at people who produce the best modules for e-Sword. What do they use? When taking advice from other people on module making, filter that advice by asking yourself: what modules have they uploaded? Productive module makers use productive tools and that helps me help you!

I will personally tutor or mentor anyone who needs help! I do so all the time. Don't be afraid to ask for help! Remember: a Microsoft Word macro can do the work of many man hours in seconds!

ToolTip 4 Download Link: http://www.biblesupp...ooltip-tool-nt/

#2 BaptizedBeliever

BaptizedBeliever

    Christian

  • Members (T)
  • PipPipPipPipPip
  • 924 posts
Offline

Posted 03 January 2012 - 01:25 PM

Regarding Roman numeral verses, highlight them, click "edit" in T3 and select which style of Roman numerals they are. T3 will automatically convert them to standard numbers for you. At least, it did for me this afternoon.

Brad

#3 DoctorDaveT

DoctorDaveT

    e-Sword Fanatic

  • Members (T)
  • PipPipPipPipPip
  • 426 posts
Offline

Posted 03 January 2012 - 01:59 PM

Josh,

can I "really!" like your post somehow?!

Dave
visit www.DoctorDaveT.com for eSword modules, software tips, & more


#4 BaptizedBeliever

BaptizedBeliever

    Christian

  • Members (T)
  • PipPipPipPipPip
  • 924 posts
Offline

Posted 03 January 2012 - 02:53 PM

One question I have regarding "preferable" formatting for commentaries is this:

What about the commentaries that have paragraphs that make the apostle Paul's sentences seem simple? In the College Press commentary, I've run across paragraphs that run at least three whole pages... And considering that most people probably don't maximize the Commentary Window when using e-Sword (at least, I don't), that will make for some very bleary sights for the eyes.

Brad

#5 Josh Bond

Josh Bond

    Administrator

  • Administrators
  • PipPipPipPipPip
  • 2,890 posts
  • LocationGallatin, TN
Offline

Posted 03 January 2012 - 03:02 PM

One question I have regarding "preferable" formatting for commentaries is this:

What about the commentaries that have paragraphs that make the apostle Paul's sentences seem simple? In the College Press commentary, I've run across paragraphs that run at least three whole pages... And considering that most people probably don't maximize the Commentary Window when using e-Sword (at least, I don't), that will make for some very bleary sights for the eyes.

Brad


I struggle with that a lot. I have inserted paragraph breaks for long paragraphs before, where a modern author would have inserted them. We use a lot more paragraph breaks today than even 30 or 40 years ago. My first question for that particular resource would be: are you sure the original PDF has one long paragraph? Or did the OCR process make it one long paragraph?

If it's too time consuming to insert good paragraph breaks then, I would say leave it like the original author intended, long paragraphs and all. When making copyrighted resources, that's usually a requirement--that you not alter the resource so long paragraphs stay as they are.

#6 DSaw

DSaw

    Resource Builder

  • Members (T)
  • PipPipPipPipPip
  • 1,159 posts
  • LocationEast Coast
Offline

Posted 03 January 2012 - 04:16 PM

JOsh Thanks FoR <THIS>

All joking aside Thank You very much I appreciate the work you do and the time you put in

May God change our hearts to what the truth is

2Ti_2:15 Study to shew thyself approved unto God, a workman that needeth not to be ashamed, rightly dividing the word of truth.

Rom_9:16 So then it is not of him that willeth, nor of him that runneth, but of God that sheweth mercy.

2Ti 2:24-25  And the servant of the Lord must not strive; but be gentle unto all men, apt to teach, patient, In meekness instructing those that oppose themselves; if God peradventure will give them repentance to the acknowledging of the truth; 
 

 

 


#7 Josh Bond

Josh Bond

    Administrator

  • Administrators
  • PipPipPipPipPip
  • 2,890 posts
  • LocationGallatin, TN
Offline

Posted 31 August 2012 - 10:39 AM

I've updated this thread for ToolTip NT and removed some of the conversational responses to avoid clutter.

I'm going to sticky this and maybe place it prominently in a new module creation area, to help new module makers get up to speed on what we expect for quality.

I'm thinking of a How to Create e-Sword Modules area. And thinking about how to feature it more prominently. The problem has been people do not know where to find this information. I want us to avoid the sloppy, "pump and dump" modules that make e-Sword look bad.

I also really appreciate those of you who are remaking the older e-Sword modules that are riddled with these issues!

#8 APsit190

APsit190

    e-Sword Tools Developer

  • Members (T)
  • PipPipPipPipPip
  • 2,861 posts
  • LocationLand of the Long White Cloud (AKA New Zealand)
Offline

Posted 31 August 2012 - 06:40 PM

I'm going to sticky this and maybe place it prominently in a new module creation area, to help new module makers get up to speed on what we expect for quality.

I'm thinking of a How to Create e-Sword Modules area. And thinking about how to feature it more prominently. The problem has been people do not know where to find this information. I want us to avoid the sloppy, "pump and dump" modules that make e-Sword look bad.


Hi Josh,
I think that, without a doubt, your idea of having a (what I call) a separate zone for new module makers is a really great idea. Fact is I tend to think that some us older hands could also take a leaf or two out of that proverbial book and learn some new skills in how to make things look better or great. So on this you've got a great big thumbs up from me.

Blessings,
Autograph.png
X (formerly Twitter)

 


#9 jonathon

jonathon

    e-Sword Fanatic

  • Contributors
  • PipPipPipPipPip
  • 753 posts
Offline

Posted 01 September 2012 - 10:25 AM

Commentaries and dictionaries still have value if they aren't tooltipped.


IMNSHO, commentaries and dictionaries that are not tooltipped are even more useless than topical files that aren't tooltipped.

Map resources that are not tooltipped can be used, but, even there, tooltipping is helpful.  

Strong's Numbers, at an absolute minimum, should have an H or G preceding the number.


+1

I'd go further and say that including the prefix is mandatory.  
Likewise, when A numbers or Z-Numbers, or any of the other variants are used, they must have the appropriate prefix.

format that number with the Tooltip color and underline it, so users know they can click it and see the definition in the dictionary window.


Won't T3 or NT4 automatically do that?

The end user does not want to, and should not have to, resize the text control because your text does not conform to the rest of their e-Sword resources.


reorganizing some material according to the Biblical canon order (instead of a random order or the order of publication).


I'm guessing that the English KJV order is being referred to here.

Whilst there are are more than 200 versification schemes out there, utilizing the one that e-Sword recognizes, makes it much easier for people to locate material. {Granted, Greek Esther, Hymn of the Three Young Men, and Prayer of Azariah are going to remain a mess, until Rick fixes the way e-Sword handles them.  IMNSHO, create Greek-Estheras a new book, distinct from Hebrew-Esther, and create Prayer of Azariah as a new, separate book.}

###
When was b-code dropped, in favour of HTML, for marking up responses on this board?
jonathon

#10 goswazi

goswazi

    New to Bible Support

  • Veterans
  • Pip
  • 1 posts
Offline

Posted 25 December 2012 - 09:20 AM

I need help with a translation project where I am translating the NT and later the OT. I am using e-sword 8x as my tool, because all my resources are there, but may be willing to update if necessary. I am presently handwriting my text but it would be nice if I was producing a module at the same time. How is a module produced? What I would like is to have is an open/editable working template where I can type in my work,(and perhaps deleting the previous work if one is pre-written) so that when it is done it is a working module. And too, I use a strong’s dictionary module for reference and I would like to be able to add my translation notes directly into it. When it is done, I would prefer the text to be parsed, tooltipped, and linked to this updated/modified strong’s-based dictionary (and others).

  1. Where can I find an editable public domain platform-template, preferably parsed with strong's,  Bible?
  2. And the linked editable strongs?
  3. I assume these sources would be public domain, but the result may be copyrighted.
  4. Can you or anyone direct me to these resources or perhaps to someone who may know. Thanks
  5. I believe this work, since it keeps the raw prepositional form, consistency of words and the etiological exegesis, an exposure of the original language as an attempt at a true literal translation and not an eisegetic interpretation, word of thought, modernized or a paraphrased work, that I believe many might find as a useful tool.





0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users




Similar Topics



Latest Blogs