Date: Wed, 4 Mar 1998 13:10:36 +0200 From: Jeremy Lea <reg@shale.csir.co.za> To: doc@FreeBSD.ORG Subject: Re: ps2pdf (was: newbies mailing list) Message-ID: <19980304131036.44077@shale.csir.co.za> In-Reply-To: <19980304102052.13296@freebie.lemis.com>; from Greg Lehey on Wed, Mar 04, 1998 at 10:20:52AM %2B1030 References: <199803030441.VAA11558@const.> <34FBE0CB.C1697F2D@internationalschool.co.uk> <19980304102052.13296@freebie.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi... This is going to sound really nasty, but it's not meant that way... 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... > 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. > 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. 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. 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. 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. 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. Regards, -Jeremy -- .sig.gz 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?19980304131036.44077>