[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

>   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

>  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.


Reply to: