Re: how to make the man formatting better.
On Tue, 2002-09-17 at 12:28, Colin Watson wrote:
> 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.
Yes - re-reading how I'd written that, I mis-spoke myself. I suspect
that up the policy chain, from what I'd read from links to threads
reported about Debian-Doc in the Debian Weekly News, it leans more to
SGML in general for any documentation, regardless of what works best in
specific situations, in the interest of "standards and universal
portability". Having coded in troff, runoff, Script on IBM mainframes,
and SGML before spending a decade in the desktop publishing field with
PageMaker, QuarkXPress and (ick!) Ventura Publisher, I know how nice it
is to use groff for quick but multi-environmental formatting, as well as
presenting chessboards ;)
I even found that with a few macros, I could even trust print reporters
with groff! I wouldn't even consider having them work with a text editor
and an SGML template.
>
> 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.
>
I heartily concur with that sentiment - in the same way that I would not
resort to TeX for a quick TODO list for myself as it is overkill, SGML
doesn't necessarily *fit* as the best solution everywhere, particularly
if it involves porting a mass of documents that are working fine to
another system.
That really would only make sense if groff was to be judged as otherwise
unused and questionable to support/ship any further - the same as in
insisting to support traditional consumer audio cassette tapes as a
storage (or boot) medium.
> > 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.
Which makes plenty of sense, so long as nobody launches a Debian Solaris
or Debian UnixWare project ;)
>
> > 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]
>
>
> --
> To UNSUBSCRIBE, email to debian-user-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
>
--
Mark L. Kahnt, FLMI/M, ALHC, HIA, AIAA, ACS, MHP
ML Kahnt New Markets Consulting
Tel: (613) 531-8684 / (613) 539-0935
Email: kahnt@hosehead.dyndns.org
Reply to: