Bradley M. Small wrote:
Hi!
> At the risk of getting myself in hot water here, perhaps
> these should be rethought. It matters not how readable
> code used by the computer is to the human if and only if
> it is readable somewhere else and merely generates the
> ugly computer code.
Agree. Though I admit that I also prefer readable computer
code.
> The documentation could be kept, maintained in some other
> format more easily developed in by technical writers and
> such, but then "compiled" into the modules that go into
> the program.
Agree. There's currently just no such infrastructure.
> Certainly this can be as simple as maintaining it in XML
> and using an XSLT that makes it do its thing, however,
> perhaps a simpler more "freeform" format with minor
> scripted place holders could work.
Well, frankly the "tcl" code used for the docs today is a
very stripped down version of html. So to say it is not a
difficult format as such.
One can do it in xml, I've no problem with xml, but to tell
you the truth, this would currently rise complexity of these
type of files. You may have a look at help.tcl to see what I
mean.
> This way, the data can be easily read and kept current by
> using simple emacs, vi, notepad etc... then run through a
> python or whatever script to reformat it into TCL modules.
As I say, the tcl is not the main problem. Basically, I
think one real problem is to find a framework that allows
to move changes from one master file (english) on to the
about 25 other languages for translation. Ie. how to notify
that there was a change that needs translation.
But, today, the major problem is, that there are huge
amounts of functions that do not have a single line of
documentation. E.g. at the moment I'm rewriting "Opening
Trainer" in a usable fashion. You may look up the current
help and then try to get it working. Tomorrow, I'll tell you
that you need a repertoir database where each line to train
is of a specific form and that you have to set the type of
this database to the proper value (ie. Openings for Black or
whatever you want to train). In the current version you'll
not find a word about all this in the documentation. There
is however some discussion of it here on the list.
Somewhere...
> I am probably speaking out of turn here, and not offering
> a substantial solution but it is a thought.
No problem with that. Still I see a major problem in the
simple fact that there is in large parts of "Scid beyond
3.6.1" just nothing available that is stored in any format
to be converted.
> I will try and work some time out to help if I can, but
> like everyone else there is just never enough time...
Jepp. This is a general problem, and I fear the main reason
why the docs are in such a bad shape. Its no fun to write
documentation...
--
Kind regards, / War is Peace.
| Freedom is Slavery.
Alexander Wagner | Ignorance is Strength.
|
| Theory : G. Orwell, "1984"
/ In practice: USA, since 2001
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Scid-users mailing list
Scid-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/scid-users
