Date: Fri, 6 Mar 1998 19:12:29 +1030 From: Greg Lehey <grog@lemis.com> To: Jeremy Lea <reg@shale.csir.co.za>, doc@FreeBSD.ORG Subject: Re: ps2pdf (was: newbies mailing list) Message-ID: <19980306191229.06394@freebie.lemis.com> In-Reply-To: <19980304131036.44077@shale.csir.co.za>; from Jeremy Lea on Wed, Mar 04, 1998 at 01:10:36PM %2B0200 References: <199803030441.VAA11558@const.> <34FBE0CB.C1697F2D@internationalschool.co.uk> <19980304102052.13296@freebie.lemis.com> <19980304131036.44077@shale.csir.co.za>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 4 March 1998 at 13:10:36 +0200, Jeremy Lea wrote: > Hi... > > This is going to sound really nasty, but it's not meant that way... Go for it. > On Wed, Mar 04, 1998 at 10:20:52AM +1030, Greg Lehey wrote: >> 2. The ASCII (latin1) version of the handbook doesn't contain any >> high-bit-set characters. The only unusual character it contains >> is a ^H (backspace), which even on DOS impact printers will create >> a bolder impression. In UNIX, you can (and I do) remove it with >> sed 's:.^H::g'. I suppose it would make sense to include a >> stripped version on the next CD-ROM, like I'm planning to put an >> ASCII version of "The Complete FreeBSD". > > The thing is that maybe 80% of newbies are starting from a Win95 > environment... They dont have a clue what sed is and they dont have impact > printers. They want documents that are easy to print using the stuff that > comes with Win95. If the install docs dont work then the OS is obviously a > load of junk... I think you misunderstand me. Obviously the work with sed has to be done before making the CD. >> 4. It is possible to install groff on DOS. I've never done it, and I >> have no intention of introducing Microsoft to my workspace, but >> people should at least be made aware of the possibility. > > I once tried to install TeX on DOS, found I needed some other arcane Unix > utility, found I had to compile it from source, found it wouldn't work in > Borland C, needed DJGPP and so on, until I ran out of disk space. I gave up. > Telling people to install groff to read your docs is only going to chase > them away. TeX is a can of worms. It used to drive me to distraction. Again, though, I'm not suggesting that anybody install it on DOS. You've got me somewhat out of context here. >> 5. I think HTML stinks as a documentation format. It's barely >> acceptable as a web format, and the attempts I've made to use it >> for Real Documents have been painful. Compare >> http://www.lemis.com/errata-2.html and >> ftp://ftp.lemis.com/pub/cfbsd/errata-2.ps, both of which >> ostensibly are the same document. About the only advantage it has >> is that just about everybody has a reader. > > Your opinion doesn't count. Yes it does! > Only that of a clueless newbie, armed with Win95 and a problem. The > documentation, especially the stuff needed to explain the install, > must be visible and easy to get, [print], and read. The choices are > HTML, PDF and RTF. All can be generated from the current SGML. We > need to make all of these available. With the latin1, ascii and ps > versions. No problems there. My problem is that there has to be something better than the current html, which, as other people have observed, is difficult to handle. While writing my book, I spent a lot of time reading the handbook, initially the HTML version. It wasn't until I went to reading the ASCII version that I discovered a whole lot of stuff that I hadn't found in the HTML. This is more a problem of the handbook than the medium, but the medium encourages it: excellent random access and appalling sequential access. I'd suggest that we try to reduce the number of pages and increase their size (and still keep the links, of course). One page per chapter sounds reasonable. > I started using FreeBSD out of frustration with Win95 and people > always telling me to buy stuff (like Word, like Borland C). I saw a > powerful, free operating system, with a ton of other free software, > and dived in. I printed the INSTALL.TXT file, read it, was > lost... read most of the handbook... still didn't tell me the > basics. I didn't have the man pages to read yet... It took me a > week of evenings before I was even willing to boot the install disk. I see the problem. > The thing which I really dont like about the Unix world is that it > sucks you in... This package depends on that package, which is > really doing the same job as another package, which you need for > something else... you can't ever talk of a minimum install. Sounds like your description of Win95 in the previous paragraph. > Anyhow, enough whining, I guess my real point (and you should know > this better than anyone else ;) is that the docs are not written for > the authors, but for the users, especially the clueless ones. Sure. I think you've misunderstood my comments. I'm trying to make it easier for the newbie, too. But I don't want to make it more difficult for other people, and we should understand that even newbies have difficulty with HTML. Just because it's familiar doesn't mean that they can use it effectively. Greg 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?19980306191229.06394>