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/