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.
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. 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. 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. I am probably speaking out of turn here, and not offering a substantial solution but it is a thought. I will try and work some time out to help if I can, but like everyone else there is just never enough time... -- Bradley -------------------------------------------------- From: "Alexander Wagner" <[EMAIL PROTECTED]> Sent: Saturday, October 11, 2008 11:54 AM To: "Benoit St-Pierre" <[EMAIL PROTECTED]> Cc: "Scid" <scid-users@lists.sourceforge.net> Subject: Re: [Scid-users] Doc: Questions / Status > Benoit St-Pierre wrote: > > Hi! > >> Here is why I stopped working on help.tcl : >> >> Almost all pages are too long. Topics need tightening. >> Information suffers from being outdated. > > Well, we just can not have 1000 features and absoultely no > comment how to use them. This is not possible. It can not be > that even me, really following the development of the app, > have no clue at all about some options, just as there is not > a word lost about them. It can not be that we refer a user > to a technical ChangeLog or to the list archive. > >> Correcting errors is very tough. > > Well, 200 lines of changelog to go. I did not say that I do > this over night ;) > > Except the fact that we've about 20 translations to handle > and no concept how to move notification of new info to all > those files. At the moment, I'm happy if we have an as > complete as possible english documentation, if that's done > I'll try to brush up the german (for what its worth, I do > not use it, but it's there and its the only other language I > could help out, my french is defitely not good enough). > >> The tcl file with pseudo-html brings no joy to the eyes. > > I do not care about joy to the eyes at all. IMHO even > text/plain would be a good thing if it contains descriptions > for all features. Currently we are far from this, this can > not be and has to be solved. Better to solve it with what is > there than not to solve it and have a fancy concept how it > could be done ;) Once the text is written it can be > transformed to almost everything. > > So, design can be done later, but we are currently about to > loose documentation for a substantial set of new functions. > And nobody will find it funny to write the letters A-K of > the Encyclopedia Britannica in a year or so. > >> Having to join the programming cycle is cumbersome. More >> importantly, there are lots of spaghetti writing there. > > Well I'll try to clean it up if I come across it, but at the > moment I'm just about to add all those things that are in > the ChangeLog using one line or the other (better being to > long than to short) and clean up things that are outdated if > I come across them. Well, chances are good that about every > second page in Scids help is getting a 3.6.26 update stamp. > >> Let's take a simple example : the About page, or the >> colophon. This is referred as > > Well, this page is the least of my concerns ;) Frankly, when > I come to that page, I'm through the hard stuff already and > we have docs for all functions at least in english and a > correctly linked index. I'm not sure about this table of > contents type thing, admitting that I hardly ever use it. > > -- > > 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 > ------------------------------------------------------------------------- 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
