Date: 25 Jun 99 03:39:07 PDT From: Jesus Monroy <jesus.monroy@usa.net> To: Mike Pritchard <mpp@mpp.pro-ns.net> Cc: doc@FreeBSD.ORG Subject: Re: [Re: Survey: online documentation 15% incorrect] Message-ID: <19990625103907.5722.qmail@nwcst314.netaddress.usa.net>
index | next in thread | raw e-mail
Mike Pritchard <mpp@mpp.pro-ns.net> wrote: > > Document: Documentation errors in FreeBSD > > Run Date: 6/17/99 > > Description: The following is a listing of incomplete, ambigous or > > failed references for FreeBSD using whatit(1) and > > man(1). > > This survey was conducted using FreeBSD 3.1. > > > > A complete Listing can be found at: > > http://www.geocities.com/SiliconValley/Hub/8031/psuedo-indicators/fbsdutils.html > > > > Score: > > directory no reference ambigous reference other total available > > /bin 0 1 1 2 32 > > /sbin 8 5 0 13 82 > > /usr/bin 42 33 0 75 394 > > /usr/sbin 8 7 2 17 183 > > ---- ---- > > total total 107 691 > > > > Final Score 107.0/691.0 = 0.1548 (15.5%) > > I took a look through this list and by my count only about 55 of > the references are bogus or incorrect or ambiguous. A number of them in > your list are producing exactly what they should be. Some others > have been fixed in -current already. > "exactly what they should be" is ambigous in itself. As this is the question I was begging. I expect a response as what you have outline. My point in doing this was to have a place to cut back files on a custom install. I didn't know where to start so I took this as the best way. I posted the results in the hopes that someone like yourself would make a decent attempt at resonding to some of the issues. Plainly many of the problems (or misusderstanding) stem for historical reason. The are many fixes I would recommend so I'll list them as you have them below. > There are a handful of man pages with links to other man pages that do > not show the links in the NAME/SYSNOPSIS section. I'm going to go fix > the easy ones right now. > Thank you. > A number of man pages/commands are links for historical names for > commands, > which have been replaced by new/GNU replacements and the man pages > reflect > the updated versions, not the historical name for the command. These > should probably be fixed, too. 'man cc' is a good example. You get > what you need - the gcc man page. I've never been sure what we should > do with these. > I have a proposal that all new man pages carry a historical section in them. I could suggest a format, but I think the matter is open for dicussion and I'll let others make suggestions. In any case, the historical section needs to be implemented for all utilities includind those depricated. This section should, of course, lead to (or mention) a section of man pages that lists the old man pages. This being there so if there is any question reference is available. Install time issues are a seperate can of worms I'll leave unopened at this time. > One interesting problem your survery points out is that > whatis/makewhatis > get confused about inetd.conf and inetd. It lists them both as section > 5 man pages, when only inetd is section 8. This is because > the inetd Makefile MLINKS inetd.8 to inetd.conf.5. There are > probably a few other commands that might be doing this. I'll have > to look at this closer. > Sounds like an uninitialized variable to me. > Then there are the commands without manual pages, which is just plain > wrong. > Yes, I was surprised to find them. 8-O -- Another suggestion I'd like to make is that apropos(1) and whatis(1) not perform similar functions. This seems to be a useless feature. apropos(1), as the word suggests, should return those that seem apporpriate; while whatis(1) should be more defined, at the very least it should return items on a scoring system, not alphabetical such as is. Most notably is perl(1) returns far to man items to be useful. -- Another point is aliased program. I think we can all recall the amazing discovery that '[' and 'test' are one and the same. However, this is not obvious even when reading the man pages. -- For both of these I would suggest new options to apropos(1). One option would be to list all aliases, as used in the file system. Another option would be to list all depricated facilities. This one absolutely needs to be done. -- The last suggestion I'll make is to add "section" definitions in the man(1). Currently, one must know (or guess) the sections. This is useful especially with fsinfo(1) and fsinfo(8). --- "I'd rather pay for my freedom than live in a bitmapped, pop-up-happy dungeon like NT." http://www.performancecomputing.com/features/9809of1.shtml ____________________________________________________________________ Get free e-mail and a permanent address at http://www.netaddress.com/?N=1 To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the messagehelp
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990625103907.5722.qmail>