[sword-devel] OT: project issues (was: Re: single-user vs. multi-user installations, modules and packaging)
dmsmith555 at yahoo.com
Mon Sep 24 05:11:04 MST 2007
On Sep 24, 2007, at 7:10 AM, Jonathan Morgan wrote:
> On 9/24/07, Eeli Kaikkonen <eekaikko at mail.student.oulu.fi> wrote:
>> On Mon, 24 Sep 2007, Jonathan Morgan wrote:
>>>> How do I export the content of the modules so I can store it in my
>>>> own format?"
>>> Might this not need better documentation of the Sword project tools,
>>> rather than the API?
>> I think he meant that people would be more willing to write software
>> using our library. That would remove the need of conversion.
> That makes sense, though I don't think that will overcome the "I want
> to use language X, for some value of X unserved by SwigSword".
Eeli was right.
Actually, I think it *should* swerve them.
The effort to write a good Bible search and lookup library is not
trivial. Over the few years that I have participated here, I have
seen many people get started and few get very far. We need to help
people understand that we can get further together than separately.
But on another note, I work on JSword, so I know the itch to port.
I've been working at it for 3.5 years now, fairly steadily, and there
is still so much more to be done. I'm not about to stop now, but if I
had put that energy into Sword C++ it would have been well served.
>>> I think that there are a few separate issues here:
>>> 1. Documentation of the API. This should consist of
>>> documentation of
>>> what the classes are for, what the individual methods do, etc.
>>> 2. Documentation of the Sword tools. This should consist of
>>> documentation of input file formats, purpose, command line
>>> 3. Documentation for the various GUIs. This should consist
>>> largely of
>>> user manuals and similar things.
>> Exactly, but the library is for developers and frontends for end
>> Therefore their documentation projects are not related.
>>> I think that in all these areas there is some work done. I think
>>> Eeli and Karl were looking at was (1), while DM may be looking
>>> more at
>>> (2) and (3) (correct me if I'm wrong).
>> I was actually thinking of 1 and 2 though it might not be clear from
>> what I wrote.
And I was thinking of 1 and 2 also. But perhaps not 1 in the way you
were. I think you were thinking more of a Java style of documentation
where every Public method and Public class is documented as to its
purpose, parameters, products (return values) and problems (aka
exceptions) (I just had to make it all P's :) . I'm using Public
here as opposed to public to mean the interface which is part of the
published API and not one that is artificially public because of an
internal library need. That is, what one should know about as opposed
to what one can call.
Such documentation is invaluable and it should be done, but I was
thinking more of explained Snippets of code. It is more important to
know how a method works in concert with everything else and how it
helps to achieve a real goal.
As to 3, that belongs in the hands of each frontend development team.
I know that GnomeSword and BibleDesktop have current, comprehensive
and even complete documentation (That makes 3 C's :)
>>> with different audiences, I think that there is a real danger of
>>> trying to lump them together and either ending up with one source
>>> documentation which doesn't really meet any needs, or with some
>>> not being met at all. For example, (1) would be definitely targeted
>>> at developers, (2) is probably directed at module developers (though
>>> they should have some knowledge of command line tools, etc.), and
>>> should be directed at end users.
>> Number 3 is out of our scope as I mentioned. I don't see any
>> reason why
>> things should be "lumped together". Having a centralized page for
>> developer documentation is not lumping together. I don't
>> understand what
>> you mean by "one source". See how Qt documentation is consistent
>> in form
>> and style, yet very useful for their audiences.
> That was a reaction to DM's statement:
> "With regard to documentation, we
> all have the ability to provide it and make it available via the
> wiki. That's what the wiki's home page states it is for."
> I don't think that the Wiki is appropriate for the API documentation I
> was talking about, so the Wiki was the "one source" I was targeting.
>>> 1. API documentation: This should probably be kept with the
>>> source at
>>> this stage. I am aware that there are some arguments for separating
>>> this from the source for documentation of major software libraries
>>> like Mono (such as internationalisation), but I think at the moment
>>> the library is struggling to have adequate documentation in one
>>> language. From this documentation can be generated, and there is a
>>> higher chance of it being kept in sync with the code.
>> This is right and I don't see a reason why we should ever remove
>> the doc
>> from the code files. Few widespread sofware libraries have 18n'ed
>> (or am I wrong? Haven't researched lately...). Keeping the
>> up to date would be almost impossible for us.
> Which is why I said it.
I agree with this statement, but I don't think it goes far enough.
API documentation is needed for two fundamental purposes:
1) to understand a particular method so that the class to which it
belongs can be fixed or improved (i.e. for library writers)
2) to understand a particular method so that the class can be used in
another context (i.e. for library users)
The problem I have had with C/C++ is the best way to achieve this.
From the library writers' perspective, it should be in the code
file. From the library users' perspective it should be in the header
file. If it is in the header file it directly impacts compile time
(compilers are getting better with header caching and incremental
compilation, but it is a hit on a big library) My preference is to
have it only in one of these two spots, preferably the code file, and
be able to pull it from there to create library users' documentation.
The other part of this problem for me is that there is no
documentation standard for C/C++. I see quite a variety of
documentation within Sword code and headers.
Doxygen only goes so far.
That said, there is doxygen generated API documentation available in
SVN, http://www.crosswire.org/svn/sword-apidoc/trunk. Given the
revision number, I don't think this is maintained as part of each
release of Sword.
That said, I think the wiki should point to this kind of
documentation and that it should be kept current with each release as
a release activity.
But the wiki should be the home to Snippets and short but full
>>> 2. Tool documentation: Basic documentation of what individual
>>> tools do
>>> should probably be with the source. More detailed user level things
>>> like "What tools should I use to create a module?", "How do each of
>>> the tools fit into the big picture?", "How do I create an OSIS
>>> module?", etc. probably belong on the Wiki, as has been done to a
>>> reasonable extent.
>> That's true. Using wiki is practical for these kind of things.
I'll be writing it for osis2mod very soon. Nice thing about it, it is
the big picture for a Sword OSIS Bible module. It is the only needed
More information about the sword-devel