Re: Debdoc
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
Reply to: