I'll respond (in general sympathetically) to various points in Eric Raymond's "manifesto". Most of the rest is snipped.
On 22-Dec-06 Eric S. Raymond wrote: > Werner LEMBERG <[EMAIL PROTECTED]>: >> > Who is the person currently responsible for groff? Is it still you? >> >> Yep. Awaiting your commands. > > So I see from the groff project page, which I should have checked > first. Copying to Ted Harding and the groff list, which I just > subscribed to. > > I want to drastically simplify the markup used in several pieces of > groff documentation, eliminating a lot of the hairy custom macros they > presently use. > > groffer.1 > groff_out.5 > groff_tmac.5 > groff.7.gz > groff_char.7 > groff_mdoc.7 > groff_trace.7 As part of a new spproach to 'man' markup, and given the remarks about idiosyncracies of groff-specific markup, there could well be a case for this! > The hardest format to webify in the Unix world is also the most > important one -- man pages. (By way of GNUish contrast, TeXinfo is > much easier.) There are a large number of tools that attempt this > out there. In general, they do a crappy job. One needs, in my view, to distinguish between man-page markup and man-page layout. I'm of the view (though some, and especially texinfo fans, would probably not agree) that the man-page layout is very good for the user once the user is used to it. And a well-coordinated suite of man-pages (e.g. for 'groff') is the ideal reference once one has studied it and assimilated the links between individual related man-pages. Of course, this is the attitude of someone who learned Unix through the man-pages the "hard way" many years ago. > Thus, groff is my second largest source of man pages that can't > be lifted to DocBook. The largest is netpbm, and I'm working > with its maintainer to fix that now. > > So this is the answer to "why fix it?". Because the groff pages > presently do elaborate, bizarre things that doclifter can't cope > with. In this they are *unique*. I mean *unique*. Everywhere > else the problem is almost entirely broken markup, not things > people did deliberately. > > I want to fix the groff documentation so that it's no longer in > the way of automatic lifting of *everything* to HTML. (As a side > benefit, the markup in the groff documentation will become easier > to maintain.) The only downside might be a slight decrease in the > visual quality of the printed versions -- in particular, command > synopses might no longer look quite as pretty. So long as they remain as clear as they should be, and retain their overall layout, a slight aesthetic detriment should be acceptable. The important things to avoid are decrease in readability, and ioncreased difficulty in navigating them. As to HTML/DocBook/SGML, it's pretty well established that they are valuable approaches to structured and cross-linked documentation. So anything which makes it easier to produce 'groff' documentation in these markups is welcome, so long as they do not interfere with the established merits of the documentation as it stands. > The philosophical issue this raises about groff's place in the > world is simple: are we willing to accept that it's a legacy > rather than a primary format? Here's where I possibly join the bunfight. One might argue that making 'man' depend on groff is indeed a historical legacy, though I wouldn't in fact go along with that. It's certainly true that Unix documentation historically depends on groff, in that groff was invented first (for other purposes, one of which was to save the life of Unix!). Once it existed, of course, it was a logical and frutiful road to pursue, in producing Unix documentation in the form of man-pages--and also of course in the form of printed manuals. But groff at the same time began to display its strength as a general-purpose typesetting program, and it retains that strength to this day. Indeed, I'm prepared to argue that for many purposes it is as good as TeX and in some respects possibly better (though in others TeX does a better job); certainly when groff is used by skilled hands. Therefore my case for groff would not rest on man-pages. Indeed, if groff were superseded by something else for man-pages I would maintain that this would not diminsh the usefulness of groff, nor the necessity to keep it going. On the other hand, there is a "mind-set" amongst some that the purpose of groff is to format man-pages, and to such people a change to something else for man-pages could mean that there was no longer any case for groff in a Linux/Unix distribution (except for those weirdos who really want it). I'm personally not that interested in "groff for man-pages" as such (though I think that it's as good as anything else so it might as well be used), in that I would not favour the intrinsic functionality of groff being vulnerable to the demands of man-page formatting. Let groff develop as a real typesetting engine in its own right, for the production of documents of all kinds, and let 'man' take what it can from what groff has to offer. > I don't ask this question dismissively. I probably grok *roff > hackery as well as anybody who isn't Brian Kernighan -- groff > carries two tools I wrote (pic2graph and eqn2graph) and I wrote > your guide to pic. I think man macros will still have a place > as a composition format, even if nobody presents from them any > more. The classic structure of a man-page is lean flesh on a well proportioned skeleton. The art of man-page writing is to create that structure, embodying the information required in a clear and, above all, logical style (with careful logical links between related man-pages). The groff markup for this need not, in my view, be overly sophisticated. > But I think it's time to move on. This little change will help > us get to a fully-hypertexted, Web-centric documentation corpus. > Let's do it. So long, as I've argued above, as the basic structure is retained. > (And brace yourselves for the *real* political bunfight, which > is when I try to kill off GNU info...) You could have an ally ... ! Best wishes, Ted. -------------------------------------------------------------------- E-Mail: (Ted Harding) <[EMAIL PROTECTED]> Fax-to-email: +44 (0)870 094 0861 Date: 23-Dec-06 Time: 00:48:51 ------------------------------ XFMail ------------------------------ _______________________________________________ Groff mailing list Groff@gnu.org http://lists.gnu.org/mailman/listinfo/groff
