[sword-devel] Prelim draft of tutorial for Module-Making [was: Is "original input source" for modules available?]

[L.Allan-pbio]

>> Here is a link to a first draft, with only about 1/3 to 1/10 of the
> eventual
> content ... if it seems worthwhile to continue ...
> http://lcdbible.sourceforge.net/misc/CwModuleTutorial.doc
> which references a "StarterKit"
> http://lcdbible.sourceforge.net/misc/CwModuleTutorial_060208c.zip
>
> Feedback appreciated.

Greg. H. wrote:
> I only looked at the .DOC so far, and that seems like a decent start.

Thanks for the feedback. Much appreciated. I'd be the first to acknowledge 
that I'm far from the most qualified to prepare such a tutorial (except for 
the notion of authoring a "Dummy's Guide .... " <g>)

> If I
was fleshing it out I would definitely write each step more verbosely (I'm
guessing that's part of what you were talking about when you refer to the
1/3-1/10).

The 1/3 to 1/10th was more related to only mentioning a few introductory 
steps. By step 23, you are only just getting started. At that rate, the full 
thing could be hundreds of steps long. You can make something look hard that 
actually isn't that difficult.

More verbose? I'm a little concerned about insulting people's intelligence 
on some of the steps, but feel free to edit ... and it's ok to be blunt and 
direct .... proceed as if I've got a rhino hide <g>

I guess the key issue is "Who is the audience and what can we assume that 
they already know and can already do?" Your thoughts on this?

> Maybe the CwModuleTutorial includes the information, but I would
envision the module-making guide containing information specific to the
individual mark-ups.  I found that there were two main caveats in the
current module guide: 1) it didn't give much information on the markups,
some of which seemed to be rather esoteric in my opinion, and

I didn't intend to discuss "tags". It was more oriented to "HowTo create a 
VERY SIMPLE commentary / dictionary / Bible (with only a few verses ... but 
gotta be careful here to not be sacrireligious) / devotional" (and will 
probably start with "cloning" from an existing module ... or "tweaking" an 
existing one)

> 2) once it
moved past the mark-up, it didn't give much indication of the output files
of the different conversion utilities.

The draft was VERY incomplete .... I just made some notes as I was setting 
up the "StarterKit", did a few quick "sanity checks" and figured it would be 
appropriate to get feedback before proceeding.

> So I envision a module-making guide that contains the following steps:
1) A discussion of SWORD in general
2) A discussion of the different types of texts: Bible, Commentary, Lexicon,
General Book as well as the derivatives and how they are implemented, such
as the daily devotionals.
3) A discussion of the main types of markups with more than just a link to
the describing organization.  It was difficult to identify that ThML didn't
really work with Bibles while OSIS is sometimes overkill for something
simple.

Perhaps some links to existing pages. I think it is reasonable to make an 
assumption that the person reading the tutorial is quite familiar with using 
sword.exe (or equivalent on another platform), and is considering creating 
their own modules. For this draft, I didn't intend to presuppose a sword.exe 
newbie.

Perhaps more of a "M.E.O.h.W" (Moral Equivalent Of hello World :-)

> 4) Work through how to prepare the document and discuss the module
configuration file.

Hmmmm.
Maybe refer to existing info in the current
http://www.crosswire.org/sword/develop/swordmodule/

Only a few of the lines at the top are actually relevant, and I want to take 
the approach of "all you really need to know, and NOTHING MORE."

> 5) Discuss the different import utilities and what their disparate outputs
are for.  At first I was very confused when a bible spat out 4 files but a
General Book resulted in 3 very different files.

Ok.
I'm actually thinking of starting with modifying an existing module like 
SAOA (Scripture Alphabet of Animals) and going thru the steps to include 
something whimsical like "GoldFish".

Something like, "do this, this, ..... and this" and you should see 
"GoldFish" in sword.exe.

For actually creating something new, I envision "templates" like
$$$Topic 1
This is Topic 1
$$$Topic 2
This is Topic 2

$$$Matthew 1:1
This is commentary on Matthew 1:1
$$$Matthew 1:2
This is commentary on Matthew 1:2

> 6) Indicate how the files are to be stored within the preferred directory
structure for Sword.  Especially note that the configuration file for a
General Book must contain the first part of the filename in its path
argument whereas the Bibles do not contain that information.

Ok,
but I'm inclined to gloss over that and treat existing modules (and the ones 
included with the tutorial) as templates to "clone" from.

> I got the feeling that my basic outline has much in common with your list,
but I guess I was looking to combine documentation with a how-to/tutorial
because I always find that the easiest and most efficient method of learning
is to follow an example that also explains how and why everything is
happening.

Hmmmm.
I think you run a significant risk of getting "bogged down" in attempting to 
"explain how and why everything is happening".

I'd very much appreicate being able to look at what you have drafted, and 
combining efforts. I suspect I'm "re-inventing the wheel" to some extent.

Blessings,