Re: how to make the man formatting better.
On Tue, Sep 17, 2002 at 12:07:35PM -0400, Mark L. Kahnt wrote:
> On Sun, 2002-09-15 at 07:07, Colin Watson wrote:
> > On Sun, Sep 15, 2002 at 11:28:34AM +0200, martin f krafft wrote:
> > > also sprach Colin Watson <cjwatson@debian.org> [2002.09.15.0354 +0200]:
> > > > Most of Debian's man pages are written this way.
> > >
> > > So why does dh_make provide manpage.sgml.ex and even a commented
> > > docbook-to-man call in debian/rules? The message I extracted from that
> > > was "Debian really prefers you to use SGML for manpages..."
> >
> > dh_make has all kinds of weird ideas, and isn't even close to
> > authoritative ... note that it also provides manpage.1.ex, though.
>
> I would suspect that Debian does prefer SGML for manpages
Speaking as the man-db maintainer, nope, sorry, we don't. Whether we
should is a whole different argument. Actually, I think SGML is way
overkill for the average man page - the SGML example I ship in man-db is
almost three times as large as the groff example, and the source is
significantly less readable. Most man pages aren't all that much longer
than that pair of examples, and the ability of Debian developers and
documenters to write them conveniently without having to fight with
complex tools is important.
Also, it's rare for SGML man pages to come from upstream developers, and
consistency is important. There are SGML- and XML-derived standards that
are very worthwhile documentation formats, but considering how long man
pages have been around and how widely implementations are deployed I
think it's better to push those formats for other forms of
documentation.
> because SGML is more of an *officially sanctioned* standard that is
> meant to be able to produce output to a wide variety of presentation
> methods, while groff, being unstructured (and from past experiences of
> troff from my Unix days and runoff from my VMS days, not always
> absolutely consistent in output produced and features
> supported/implemented)
As far as Debian is concerned, only groff matters - we don't ship any
other [nt]roff implementations, and man-db is configured to use groff.
> leaves room for difficult to implement formatting decisions (primarily
> the errors, like forgetting to switch off bold or italics,) and
> requires translations that may not always be faithful when you want to
> draw upon viewers such as a web browser (although I salute the
> performance of man2html on this matter.)
groff's HTML device is getting better all the time, too.
Cheers,
--
Colin Watson [cjwatson@flatline.org.uk]
Reply to: