On Fri, 21 Jul 2000, erik wrote:
> Kdevelope is an IDE, primarily targeted at C++ and qt ...it really only > runs well in kde - and it needs kdelibs anyway. Its a nice piece of work. > The relevant thing is that there is a module in it that creates seven > pages: > 1. index - already has the name of your program and email and misc. > 2. introduction with some default info on installing, etc I think we could make the "index" page contain the introduction and make a separate page on installlig, huh? > 3. usage > 4. "Another Section" - I like that one. > 5. questions and answers This section is what, I think, we should avoid :). > 6. Copyright - again, already filled in with package name, email, and a > brief note about the GPL. > > It does all this automatically when you start a new project. I am > looking at the code - I am learning C++ so it might take me a little bit > but I think that the doc-module could be adapted to parse the output of > dpkg-deb and generate the same ( or modified ) set of pages. I would have > to find out from the kdevelop team if this part of their code is pure GPL > or if it is qt derived ... always this silly license stuff - I wish they > would just make everything free and go to a service based economy, > grumble, grumble, gripe, moan .... :). I really consider those large licences time-eaters. > At any rate, it wouldn't be that huge a project to put together in shell > or perl, there are alot of modules around. But I think the templates could > be a little more complete than the kdevelope ones -perhaps each page could > have a default content explaining the purpose of the page and how to fill > in the gaps ? sort of a tutorial for the tutorial. Would we not better create an (OS/architecture/distribution/etc.)-independant application, and then add distribution specific modules (like a few awk/perl/etc. wrappers to auto-fill some fields. This way anyone would be free to create and install a little filter for their own distribution/OS. And about the default content -- I think it is a great idea. > Ahh, good thinking - different sets of templates for different classes of > software ? This deserves some thought ... mmm, how many classes of > software can we define? I guess we would not be able to list them all until we start using it in practice. Therefore, it might not be a bad idea to provide a way to add a custom application-class template. > Hmmm, I agree with the notion of keeping it compact, elegance is always > easier to work with. But I do think that HTML is a reasonable default > these days - it is intuitive for people to browse and easy to move around > in. Its also pretty easy to build and modify. If we would like the average > learning (hopefully) user to be able to contribute, HTML is a much more > familiar interface than, say; texinfo. Its also generally familiar to > people migrating from other OS's where that's the only thing they have > ever seen. I think you have to let people in _somewhere_, and I really > don't mind making that a little bit easier for them ;). To tell the truth, I am not really familiar with tex, I am now reading the docs. > The searching could be added much later and does not have to be very > deep - just enough to give someone a direction to go in. I have always > hated huge search results ... a database of page titles should really be > sufficiant, if they are well titled. For the titling> Recall my idea of structuring the text itself? I offered to make each paragraph start with a sentence describing what the paragraph is explaining in detail. Now, if we want a summary (e.g. a short description), we could get all the starting sentences and put them in one paragraph. This way we could get a short description about every section. Then we could ask the user to describe each section description by just one sentence, and putting them together we would have a short description on the whole application -- which has obvious uses. Then, repeating the iteration, we would have a one-sentence-desctiprion of the whole application, and extracting the keywords from it we could get a sensible title. I guess we could apply something similar to get good titles. > Actually, I looked at debian-doc and its a very low volume list ( good > for my spastic email account ) maybe we should move this to there ? Might > even find more interest - doesn't seem to be much going on over there at > present. Fine, I have just subscribed to it. Pavel
