# [rescue] My Best Rescue to Date.. Ever

velociraptor velociraptor at gmail.com
Thu Jan 19 23:23:36 CST 2006

On 1/19/06, Richard <legalize at xmission.com> wrote:
> In article <b9ce685f0601191104j2ad15b7fsf0ee66d8dafaab54 at mail.gmail.com>,
>     velociraptor <velociraptor at gmail.com>  writes:
>
> > On 1/19/06, der Mouse <mouse at rodents.montreal.qc.ca> wrote:
> > > > [...manpages using -mandoc instead of -mdoc...]
> > > > As far as I could tell, there was no good reason for changing which
> > > > macros they were using, other than NIH.
> > >
> > > Actually, there is: all the same reasons why it's better to write (in
> > > TeX) \emphasis{...} instead of {\bf ...} when you mean emphasis, or
> > > heading, or the analogs in any other markup language.
> > >
> > > ".Op Fl x" is, similarly, better than (say) ".BR [ -x ]" (or whatever
> > > you'd use in the old paradigm - I've forgotten).
> >
> > i.e. structural/functional tagging instead of format-based tagging--
> > like the difference b/w full-blown SGML over HTML, or structural
> > document stylesheets in FrameMaker vs. whateverthehell M\$
> > Word uses.
>
> Perfectly reasonable for writing new man pages, but existing man pages
> that use the format-based tags should still work.  In other words, if
> you provide a troff clone, it should have a compatible set of an
> macros so that 'my-troff-clone -man foo.1' will work.

No arguments there, just amplifying on what der Mouse had
previously said.

Structural tags make ever so much more sense for information
*reuse*...but I oughta be careful what I say, there could be Linux
fanboys lurking about that run off and decide man pages should
be in a local database or something godawful like that. ;-)

Flat text files are perhaps a little too low-level for man pages, but
are my preferred method of documenting things on my own
systems.  If you can't get to it in a terminal session...it's in the
wrong format.