Re: [Groff] UTP markup

[Jon Snader]

On Tue, Jun 25, 2002 at 11:31:43PM -0500, Michael Hobgood wrote:
> A few questions concerning the markup of the UTP:
> 
>       1. How close to the original are we trying
> to get? For example, do we correct typos that we 
> find (typos, not out of date material)?

Now that the macros are done (err, almost done) I think it's
time to discuss this.  Personally I would like to honor the
style of the original book as much as possible, but I don't
think we have to be exact and I certainly don't think we
should be bug compatible by preserving typos.

>       2. Do we want to keep the page contents
> and the page numbers the same?  If so, what
> are the dimensions used in the original? 

I don't think the page numbers have to be exactly the same.
My guess is that it would be pretty hard anyway without the
exact macros used originally.

>       3. Given that the UTP macros don't produce
> the exact same look in some areas as the original
> (i.e Chapter etc), is it alright to forgo some of the
> boxes drawn around the example outputs?

I'm willing to work on getting the Chapter headings to look
like the original if people want to do that.  I was behind
in getting the macros out to everyone, so I decided to skip
that detail for the time being.  Same with the SS and SE
macros.  I don't think we necessarily have to reproduce those
headings, but I'll be happy to work on it if others do want
to maintain that style.  In the mean time, just use the macros
as is.  If we do change, I'll just add a special UTP chapter
format and alias it to the format_section macro in the utp
macro.  That way, nothing will have to change in the source
files.

>       4. Over the chapters I've worked with, I've
> noticed several inconsistencies in the way the
> original was formatted.  Do I attempt to match these
> or just pick one style and go with it?  Some of the
> ones I've noticed include: some example command lines
> are bolded, others aren't, some of the material that
> uses the .Ps/.Pe indentation in one place, won't have
> it in another place.
> 

This is one place I think we can ``improve'' on the original.
I think it's more important to have a consistent style than
to exactly reproduce the original.  Unfortunately, what we
really need here is an editor who can look at the work as a
whole and fix up the inconsistencies.  At the very least, we
should settle on some ground rules on the list so that everyone
can do pretty much the same thing.  Maybe the people working on
the individual chapters can inform the list of what they propose
to do, and we can thrash it out that way.

Jon Snader