Date: Wed, 14 Apr 1999 18:30:18 +1000 From: jonathan michaels <jon@caamora.com.au> To: Nik Clayton <nik@nothing-going-on.demon.co.uk>, Greg Lehey <grog@lemis.com> Cc: FreeBSD Documenters <doc@FreeBSD.ORG>, "Robert A. Bruce" <rab@cdrom.com> Subject: Re: Publishing the FreeBSD handbook Message-ID: <19990414183018.D28429@caamora.com.au> In-Reply-To: <19990412212213.B9344@catkin.nothing-going-on.org>; from Nik Clayton on Mon, Apr 12, 1999 at 09:22:14PM %2B0100 References: <19990412125145.J2142@lemis.com> <19990412212213.B9344@catkin.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Apr 12, 1999 at 09:22:14PM +0100, Nik Clayton wrote: > How do, > > On Mon, Apr 12, 1999 at 12:51:45PM +0930, Greg Lehey wrote: > > I've been looking at the handbook for a while, and have tidied up some > > rough edges, as you may have noticed. But basically it's clear that > > the handbook isn't really ready for printing in its current form, and > > Bob Bruce has agreed to postpone the matter until it can be tidied up > > a bit. We're hoping to be able to get it in printable shape by about > > August or September, and then he's talking about having a new edition > > printed about twice a year, so the handbook would be subjected to a > > release cycle similar in nature to the software release. > > I've been thinking about this a bit, and I've got a few questions. > > 1. Does the Handbook need a 6 month release cycle? The majority of > the content doesn't change that much in 6 months. Wouldn't a > threshold of "changes made since last printing" make more sense, > perhaps with a minimum 6 month wait between prints. put anotehr way .. we just went from teh v2 style to v3 style of doing things. that is their was some significant diferences between teh way tings in general were done. wouldn't it be better of do a print after this level of change was delivered in teh body of freebsd. > 2. What's the Walnut Creek reaction been to my ideas about splitting > the Handbook up into smaller books? After "FreeBSD in 21 days" > gets done that's my next big project. If the Handbook suddenly > becomes 12 or 15 smaller handbooks in 8 or 9 months time that's > obviously going to affect whatever they're thinking of. do we really need that many handbookettes, so to speak. harking back tot eh installation guide discussion, don't we (as a group) really only need, how to install and upgrade freebsd how to trouble shoot teh various sybsystems that make up teh whole. how to care, feed and cage teh networking beasties, also you cold 'fatten' this up with various of teh already submitted tutorials. finally, how to be a successfull sysdamin on a singel user, home bedroom sized network nad with a chunk added in as 'advanced system administration' for teh survoces providors amongst us. nearly forgot .. a manpages of teh the specifically freebsd, berkeley unix pages and a selection of teh most usefull to get a broken system back onto ists hard disk and running. this is waht 3 at teh most and would also be a sort of heterogenius whole .. having dozens of books on teh desktop is a bloody nuisance at teh best of times. being able to reach fro a relevant text makes fro far easier usages and that ;satisfyingly warm fuzzy glow when you have sloved teh problem quickly elegantly and teh minimun of disruption you yor desk top boo collection. > 3. Are there plans for any additional content to be "Print version only"? > > > I've done some thinking about what needs to be done. I've > > deliberately held off while the previous discussion about the future > > of the handbook, but it now looks as if we haven't come to any > > conclusions which would affect my issues. > > See point 2 above. > > > As I see it, in order to print the handbook, we need to: > > > > 1. Remove the "to be written" sections. Maybe there's a style > > sheet option which can help here (Nik?). Otherwise it might > > make more sense to just comment out these sections and create a > > document "to be done" which describes where they are. > > SGML marked sections. Essentially, you create an entity (call it 'foo' > for the sake of argument) and put > > <!ENTITY foo "IGNORE"> > > in the DTD. Then, around content you want to ignore for this printed > version you wrap it in > > <![ %foo; [ > ... > ]]> > > If you want to include that information, you normally include "-ifoo" on > the command line of your SGML tools, otherwise they'll ignore it (the > default). > > That's a simplistic approach (in reality you'll probably have a number of > entities relating to this printing of the Handbook, turned on or off with > one other entity) but that's the basic idea. > > > 2. Update some old and mouldy sections. Some parts are so old as > > to be misleading, and if we don't update them we should > > eliminate them. If *you* have contributed in the past, now > > would be a good time to check over your contribution and > > consider whether you should update it. > > > > Of course, if you want to overhaul a contribution you didn't > > write, that's a great idea too, though I suppose it would be a > > good idea to check with the author first. > > This could well be a case of throwing $$$ at the problem. this is a noce position t be in, but throwing money at a probelm never solved teh probelm, all that this aproceh does is soakup teh available funds while they are available and tehn when teh taps are obout to be turned off the real solutions appear. > > > 3. Add an index, and generally improve the format. I'm planning to > > do this myself, but if anybody else wants to join in (or even > > take over), I'll be more than happy. > > Take a look around http://www.docbook.org/, in particular the bits that > talk about how you can automatically generate an index. automatically generated indexes are pathetically bad, it would have to be an execptionally good ai sequence or one of thse fuzzy logic implemantation that can spew out a primliminary cut. but, then a human would have to go through and check teh references and their relevance. while its noce, but do we really know on whch pages all teh 'and' words hide ... grin. cross referencing teh indvidual index entries would also make for amore usefull index, as opposed to a simple word amd it apperance type of list. i i can get my copy of teh books that came with an old ms dos platform application called framework, it had a very good spelling checker (one of teh bes i've ever seen actually) and it could generate indexes from its wordprocessor component that was very usefull .. they also explained how teh algorithm worked. framework was sold to teh dbase crowd who scuttled it eventually because it compted with their own flatfile database manager, dbase 4 et al. as yo can see indexing is a big thing with me, i use books a lot and find indexes invaluable in finding items quickly and with minium searching. this is why i dislike online/electronic documentation, unless it is in a wais accessable fromat, now thats indexing.. at work. > > 4. Remove some sections for the printed version only. For example, > > Bob suggested that most people who want to send core teams > > encrypted messages won't copy the key out of the book, they'll > > get it online, so we don't need to publish them. I also wonder > > whether we really need to publish 37 pages of contributor names > > and (possibly incorrect) mail addresses. > > Without getting in to the ins-and-outs of what to leave out, and what > to include, you use marked sections as details in point 1 to do this > at relatively fine detail. If you want to omit entire chapters, you > can do this by creating an alternative to the current top level > handbook.sgml which only includes the appropriate chapters in the > appropriate order. > > As to which sections to leave out -- I'd be loathe to remove the list of > contributors. Possibly the e-mail addresses, yes, but not the names. > 2 pages (small type, 3 columns?) of names is, I think, a small price to > pay in recognition of the effort of an awful lot of people. here here .. its a small price to pay for an effort that would other wise have not been forthcoming. > > There are a couple of things which I think we don't need to do, but > > I'm willing to listen to opinions: > > > > 1. Don't change the style. Sure, it's a hodgepodge, but that can > > be explained, and I don't think that it will concern the target > > audience too much. I do wonder about emoticons and such, but a > > real style overhaul would be a very difficult job, and I'd > > anticipate a number of clashes of viewpoint in the process. > > For emoticons, look for <!-- smiley --> in the SGML source. It was one > of the things I noted when I was going through it. I haven't decided yet > whether to remove them, or use entities: coming from my corner of teh world, i think that they are a waste of effort, and dangerious. not everybody 'understands' or pareciactes teh value of thes scratches and prush strokes. may nisunderstands can be easily avioded by l;eaving thse silly tings out. > <!ENTITY smiley.generic ":-)"> > <!ENTITY smiley.wink ";-)"> > <!ENTITY smiley.sad ":-("> > > and replace them. Then you can redefine those entities if you want to go > all corporate. > > (Yes, I am serious about this &smiley.generic;) and this is supposed to mean ... smiles are ok fr thse still in grade school learning who to read and write, tehy have littel place in a referenntial text. des it really matter of teh scsi card has a smily tacked on to its config stream ? if it had some value i'd be for keeping them, but really what value do teh serve ? beyounf higly localised varnacular (mis)interpretation. > > > 2. Don't change the overall format. I don't like it yet, but it's > > an area that Nik has been working on, and I don't want to get in > > his way. > > Seconded. Heavily. The Handbook (and soon to be the FAQ, and the > tutorials, and so on) do not contain formatting markup. The correct > approach to decide the formatting is in the stylesheets. > > I think I've grokked the solution to the main problem you've been having > (which I'll go through in a private message). If it works for you, I'll > commit it. ummm, why change sometint that most peple are familiar with and works so well, fro at least this sometimes very slow user. a few crackers for teh picnic basket regards jonathan -- =============================================================================== Jonathan Michaels PO Box 144, Rosebery, NSW 1445 Australia ===========================================================<jon@caamora.com.au> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990414183018.D28429>