CHM-Like HTML Interface

~ · Post by ~ » Mon Apr 02, 2007 6:48 am

Please take a look at the following HTML interface to provide dinamically a collapsable tree view.

------------------------------------
http://didactos.blogsyte.com/freecode/CHMLike

Don't you think that it could be useful somehow for development documentation, to complement wiki, etc.?

ehird · Post by **ehird** » Mon Apr 02, 2007 7:14 am

I prefer manpages.

~ · Post by ~ » Mon Apr 02, 2007 7:15 am

But that won't be enough to explain all of the OS code, and that's not comparable to a wiki or a compilation of algorithms explanation...

ehird · Post by **ehird** » Mon Apr 02, 2007 7:16 am

Yes it will be enough. For more, you want a proper text formatting package like LaTeX, or troff.

~ · Post by ~ » Mon Apr 02, 2007 7:20 am

I have never seen one of those documents used by newbies, nor online, that can be used portably or that explain everything I need to know to build my own path, even including graphical diagrams and another graphical/formatting resources like the ones of HTML tables, or categorized in an intuitive way...

Combuster · Post by **Combuster** » Mon Apr 02, 2007 7:27 am

i do not think a man page for a kernel would be any good.
Consider what you want to display when the user calls:

Code: Select all

man kernel.bin

man pages are for describing usage of something, not for documenting an entire kernel's sourcecode.

some form of generated documentation would be
a) more understandable and readable
b) easier to browse

i dont do manpages for my kernel, but rather NaturalDocs

ehird · Post by **ehird** » Mon Apr 02, 2007 9:36 am

try "man syscall" or "man cfunc". This can easily be applied to kernels (maybe section -1 for your kernel stuff?)

Tyler · Post by **Tyler** » Mon Apr 02, 2007 9:37 am

ehird wrote:I prefer manpages.

i don't see how outdated manpages compare in anyway to a completely unrelated online documentation system like this...

~ · Post by ~ » Mon Apr 02, 2007 9:48 am

ehird wrote:try "man syscall" or "man cfunc". This can easily be applied to kernels (maybe section -1 for your kernel stuff?)

Please at least give an example of how it could give an extremely global view and per-gear view, and exact code relations, to a mid-level GUI... with diagrams, and everything you could expect to find in a decent, professional development book (or e-book if you like)...

Anyway, remember that it wouldn't be very agreeable to the huge quantity of newbies and new-generation individuals that join the OS/Programming community.

ehird · Post by **ehird** » Mon Apr 02, 2007 10:17 am

A development book should be seperate from references, and it should be typeset in LaTeX or similar.

~ · Post by ~ » Mon Apr 02, 2007 10:19 am

We aren't talking here about a pretty traditional (e-)book, but a more dynamical one, and it can't be denied that more simplicity is always appreciated in complex subjects...

ehird · Post by **ehird** » Mon Apr 02, 2007 10:20 am

Simplicity is manpages. There is no such thing as a dynamic book. Just make manpages for a definitive reference, and write a book manually with (La)TeX and use latex2html if you really want it to be web-based.

~ · Post by ~ » Mon Apr 02, 2007 10:23 am

It would lack a source code relation that results to be effective more than an attempt to say "it takes you here and here and here" with 1000's of branches.

I guess I will have to choose some project (Menuet?) and demonstrate what I mean with this kind of documentation. I don't seem to be fully understood here...

ehird · Post by **ehird** » Mon Apr 02, 2007 2:30 pm

They invented that a while ago, you know. It's called cross-references.

Combuster · Post by **Combuster** » Mon Apr 02, 2007 2:55 pm

I prefer manpages.

Yes it will be enough. For more, you want a proper text formatting package like LaTeX, or troff.

A development book should be seperate from references, and it should be typeset in LaTeX or similar.

Simplicity is manpages. There is no such thing as a dynamic book. Just make manpages for a definitive reference, and write a book manually with (La)TeX and use latex2html if you really want it to be web-based.

That's three wasted posts, and IMNSHO its getting annoying.

Simplicity does not imply effectiveness or feasability. The web has become popular not without reason. A little bit more work can work wonders.

----

There are many viable options for creating documentation, ranging from M$ Notepad to a diskfull of open source software. The once I like have a predictable navigation structure such as the tree ~ gave, so yes that's a viable solution.

@ ~: maybe your imaginary scheme is somewhere down here. If you comment on that we might get a better idea about what you want:
http://wiki.openttd.com/index.php/Development:Main_Page
http://www.postgresql.org/docs/8.2/inte ... index.html
http://www.tortall.net/projects/yasm/re ... files.html
http://java.sun.com/j2se/1.4.2/docs/api/