Date: Mon, 28 Aug 1995 22:37:49 -0500 (EST) From: John Fieber <jfieber@grendel.csc.smith.edu> To: jkh@time.cdrom.com (Jordan K. Hubbard) Cc: doc@freebsd.org, hackers@freebsd.org Subject: Re: Argh. I think we need to do a quick reality-check on our docs.. Message-ID: <199508290337.WAA10861@fieber-john.campusview.indiana.edu> In-Reply-To: <2872.809605718@time.cdrom.com> from "Jordan K. Hubbard" at Aug 28, 95 03:28:38 am
next in thread | previous in thread | raw e-mail | index | archive | help
Jordan K. Hubbard writes: > 1. There is a lot of redundancy between the two. Yes, and as the handbook becomes more complete, so does the redundancy. I was just scanning through today and noticed at least a dozen sections that could be replaced by a simple pointer to the appropriate handbook section. I think what may need to evolve is a "FAQ interface" to the handbook; basically an alternate table of contents for the impatient. Or put another way, we do our best to make sure that the handbook provides all the correct information, and the FAQ serves as an index of sorts... > 2. We really really need a permuted index!! One approach is to wire in some indexing to the sgml mechanism. The tags are already in the DTD, they just need to be attached to processing mechanism. If someone spends a lot of time indexing, this will produce the best results. Another approach I started a couple month back but never finished was to make wais index out of it. This has the disadvantage of not shipping with system (unless wais software and an http server are added to FreeBSD...BLOAT!BLOAT!BLOAT!). Finally, I think a large number of FAQs are hardware related. To that end, we should get cracking on the hardware section of the handbook. At this point it has some commentary from Rod on PCI chipsets, and a couple notes on Digiboard and Boca multiport boards. What is envision for the hardware section is this: At the beginning of each subsection, for example, Serial ports, there should be some general information including what driver(s) in the kernel are relevant and a sample line to add to a kernel config file. After that should be notes on particular hardware that is known to work very well (recommended), work okay with some twiddling, or not work at all (not recommended). > This means that what's on the floppy will no longer be something that > comes out of /usr/src/release/sysinstall/help/..., it will be a subset > of the handbook itself! Jordan, just let me know *exactly* which sections of the handbook you want. If you answer correctly, it will be a snap to generate a subset document (though we may have to deal with some dangling cross references). ;) > sense in maintaining two versions. We also need to bring the > foreign-language versions over so that all that work isn't lost, and I > daresay that John Fieber could use some help here! I'm not writing the foreign language stuff; I have enough problems with my native language. 8) However, In the next day or so, I'll have a switch added to sgmlfmt(1) to allow selective processing of documents. (i.e. to support multiple languages, multiple editions and the like.) Also, I won't be able to do SGML tagging on the foreign texts, seing as how I wouldn't know what I was tagging.... However, don't hesitate to email me if you have any questions about the tagging. > If you take a `*'d item, please also send a note to doc@FreeBSD.org > so that work isn't unnecessarity duplicated. Please don't take > something you won't finish, since by "adopting" it you're also > essentially dissuading anyone else from doing so! And if you take `*''d item, your name will go in the handbook under that item and show up with your mail address as a mailto: URL. That will make it easy for people to send reminders. ];> -john PS: my email address will be changing in a day or two... watch this space! == jfieber@cs.smith.edu ========================================== == http://fieber-john.campusview.indiana.edu/~jfieber ============
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199508290337.WAA10861>