Date: Tue, 16 Jan 2001 16:21:29 -0800 From: Brooks Davis <brooks@one-eyed-alien.net> To: Rich Morin <rdm@cfcl.com> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: man, TOC, xml... Message-ID: <20010116162129.A14539@Odin.AC.HMC.Edu> In-Reply-To: <p05001941b68a80360470@[192.168.168.205]>; from rdm@cfcl.com on Tue, Jan 16, 2001 at 03:36:54PM -0800 References: <Pine.BSF.4.30.0101161434550.25916-100000@k2.vol.cz> <20010116172751.A3414@canyon.nothing-going-on.org> <20010116095547.A13543@Odin.AC.HMC.Edu> <20010116182434.A7327@canyon.nothing-going-on.org> <p05001941b68a80360470@[192.168.168.205]>
index | next in thread | previous in thread | raw e-mail
On Tue, Jan 16, 2001 at 03:36:54PM -0800, Rich Morin wrote: > The bad news, of course, is that the effort involved in turning a > man page into high-quality SGML is substantial. Semantic mark-up > is tricky; humans have a hard time with it and I don't know of any > programs that do it yet. In short, it requires Real Work (TM). This is defiantly true. It took Sun years to do it. This is a very good argument for the sman* hierarchy they used. > An interesting question, which I have raised offline, is whether the > current PR system is well equipped to handle LARGE numbers of bug > reports. An automated analysis of the man page cross-references, for > instance, could generate hundreds or even thousands of PRs (consider > the implications of a 10% "hit rate"). > > Generating the patch files for the affected man pages is a lot harder- > looking (to me, at least) than simply reporting an error or omission. > OTOH, if the man pages were actually stored as XML, the changes should > be easier for an automated system to generate than they are now... I think you're looking at a nonexistent problem here. It's true that the PR system isn't likely to be very happy with hundreds of little submissions about missing xrefs, but I don't think it matters. SGML isn't really going to increase the number of user problems reports after the formatting issues have been dealt with, because the average user couldn't care less how the docs are marked up. As to results from automated tools, a single PR can be used to submit the whole reported output or better yet the CVS generated diff. It's really not very hard to take a list of missing SEE ALSO references and convert them into a diff. Mostly, it's boring. With good markup and consistent XML style, you could probably even automate it if the job were sufficiently large to make it worthwhile. -- Brooks -- Any statement of the form "X is the one, true Y" is FALSE. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the messagehome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010116162129.A14539>