Messages in this thread | | | From | Rick Hohensee <> | Subject | Re: Linux 2.2.11pre4 (docs issues) | Date | Wed, 4 Aug 1999 15:23:45 -0400 (EDT) |
| |
>Frank Sweetser <rasmusin@WPI.EDU> >torvalds> The "info" interface makes sense only to people who grok GNU >torvalds> emacs, and if you actually want to be user-friendly you either >torvalds> use "man" (because that's how everything else is documented and >torvalds> then you could actually just tell people to use man everywhere) >torvalds> or you use HTML (because that's a _useful_ format that even >torvalds> non-emacsheads can understand). > >the info2www program works pretty nice - it's a cgi bin that converts and >displays info->html on the fly. i've got src/i386 5.2 rpms floating >around if anyone's interested...
I picked up this thread at a remark about "the obvious solution". To what problem? It just so happens I do a small distro with a very distinct approach to docs, that addresses what I see as several problems.
GNU info is fugly. The *content* of the .info's is pure gold, and absolutely indispensible. GNU thinks or used to think manpages are obsolete. There's a tendency in open source software to put out the software for free in hopes that you buy the book. That's fine and natural and proper until it effects the online docs adversely. The main reason people don't RTFM is they can't FIND TFM. Manpages are formatted for paper. Local On-line docs are the most important. Hyperlinks are wonderful for docs. The base format for docs should be ascii text.
etc. etc.
The license of cLIeNUX-originated material is not quite OSI OSD so that the OPEN SOURCE wares themselves can be encumbered just enough to have some economic value without hoping a paper dongle will sell.
A paid membership model is proposed so that authors of open source wares can be compensated for the wares directly. Compensation is based on raw amount of content, to emphasize the value of documentation vis-a-vis code.
The "Well where IS TFM?!?!" problem is addressed by a /help directory in / with most docs in it.
*roff manpages *are* obsolete for electronic documentation. A flat help-topic namespace will never be obsolete. html hyperlinks are VERY nice. The cLIeNUX /help/see directory contains all the "seedocs" for cLIeNUX, in one directory, in filenames of the form topic.sec.html . Flat namespace, flat directory. Simple. They were mostly generated from the GNU man2html program modified by me to A: run as a standalone one-shot instead of as a plugin to man B: make all symlinks relative to /help/see The sourcecode for the modified man3html is in ftp://linux01.gwdg.de/pub/cLIeNUX/GPLrequired du /help in cLIeNUX is now about 6 meg. As a wild guess I'd say about a half a meg of that is original to me. That's the part that in most cases isn't GPL. That's all the stock stuff for a smallish no-X distro, but without section 3 of the manpages, and just the PnP HOWTO. It bears mention that the Bash docs in 2.02 include html versions in the GNU distributions, the sight of which almost brought tears to my eyes.
ftp://linux01.gwdg.de/pub/cLIeNUX/packages contains cLIeNUX's first "package", which is gnu.info.html.tgz, which is all the GNU infos that pertain to cLIeNUX Core converted to html with texi2html. There are two versions of that floating around and the more recent one works, nicely. Hyperlinks, the whole bit.
Having all your manpages in cross-linked html kicks major ass. cLIeNUX doesn't have the infos or HOWTOs or kernel docs or app docs cross-linked. Submissions welcome :o) My stuff is encumbered such that it must be redistributed as a whole with the rest of cLIeNUX. That's just MY stuff. I can of course have no effect on the licenses of others. I do suggest however that DLing my distro is worth it at this point just to yank out the /help directory FOR PERSONAL USE.
Several people I have a lot of respect for are at this point rolling around on thier respective floors in a blind rage over this post. Sorry. There are several results of the above factors that bear some thought by most of the readers of this list.
Be thinking about the proper way to divvy up a big royalty check for a piece of open source software.
Put your copyrights in docs in a place that persists through format conversions.
We are all in a race between your_name_here/rt/Linux/GNU/unix/multics getting user-friendly, and Wintendo getting useable.
Think of me when your hear about great new market paradigms from the big guys, and think about how interested you are in preserving the value of intellectual property.
Rick Hohensee $ cLIeNUX0 /dev/tty3 r 13:31:44 / $ls -F / ABOUT boot/ floppy/ lost+found/ source/ ABOUT.kernel command/ help/ mount/ subroutine/ CD/ configure/ kernel/ owner/ suite/ COPYING dev/ log/ scratch/ user/ $ cLIeNUX0 /dev/tty3 r 15:18:10 / $
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
| |