Re: Debdoc
On Sat, 22 Jul 2000, you wrote:
> I am definitely interested in developing a "debdoc". I guess we may now
> start discussing the internals?
... yep, I guess so.
> I think this is more than nice -- let the documentation be developed by
> all, just like the open sources. However, I have never seen SuSE (my
> internet connection is so narrow), neither have I seen the KDevelop (I
> intend to check this out [offer some pointers, maybe]).
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
3. usage
4. "Another Section" - I like that one.
5. questions and answers
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 ....
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.
> I think documentation for this point is application-specific. Therefore, I
> propose to define templates for:
>
> 1. Programming language libraries. -- I think this is pretty
> clear.
>
> 2. UAs. -- Here I think we should have a descriptions of all: GUI
> / ncurses-like functions, command-line options, stdin/stdout/stderr
> capabilities.
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?
>
> About dwww, dhelp, info2html:
> I think our point should be not making some huge messy documentation and
> then trying to search through it via search engines.
>
> If you are offering to use HTML as a default documentation format -- this
> is a horse of another colour.
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 ;).
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.
> > PS: I cc'd this to debian-devel , but I wonder if there is a different
> > list that this should be going to?
>
> If you find one e-mail me :).
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.
erik
Reply to: