Re: [Groff] UTP - time to jumpstart it

[Ralph Corderoy]

Hi Larry,

I'm replying to lots of bits that have stacked up over the months...

Larry wrote:
> Progress on the UTP Transcription Project seems to have stalled out
> since I went on vacation. The UTP page[1] has the current status and
> links to marked-up source (or plain text if the markup isn't done).

I've just now supplied Larry with marked-up versions of App. C to G and
a front page section.

In using Jon's excellent utp macros I came up with a few comments.

I've been putting `.\" page 312' in the source to mark the start of a
new page in the original book as recommended by Larry.  I'd like to see
a .page macro instead that prints this number in the margin when enabled
by a command-line register setting, to ease reviewing the PostScript and
moving from our version back to the original.

If .page existed then it would be really handy if .Rn printed that page
number as well as the new page number.  Then we can look at the last
page of a chapter and see the issues together with the page number to
refer to in the original.

I tried to do

    .chapter E "Comparing \f(CBmm\fP and \f(CBms\fP" Appendix

but found it didn't work well because the string is upper-cased.  Can we
leave the case alone?

App. G isn't formatted right because I didn't know how to obtain a
paragraph with an out-dented first line, e.g.

    Kochan, Steven G. and Patrick H. Wood.  Exploring the UNIX System,
        Hasbrouck Heights, NJ:  Hayden Book Co., 1984.  A comprehensive
        introduction to the UNIX system.  (371 pp.)

It could well be there's an -ms way to do this, and it isn't a -mutp
thing.

> (But being somewhat fanatical about clean HTML, I just don't like the
> idea of converting tables to graphics. I'll live with it though.)

How can we use HTML tables in a book about tbl?  Don't we need the
precise appearance of a tbl table?

> If doclifter is all it's cracked up to be, that might be a better way
> to get decent HTML: convert to DocBook first, use Jade to transform
> that to HTML.

No, please don't do this.  If it's a book on troff then let's use troff
to write it.  HTML output would be nice, but comes after decent
PostScript, and therefore PDF, IMHO.  And we should stick to -Thtml and
report back the problems to see what Gaius and Werner think the solution
should be.  That benefits groff too by driving onwards -Thtml
development.

Jon Snader wrote:
> It's still a little vague.  Right now we're just trying to make the
> book available to groff users as a resource.  The idea, as I
> understand it, is to first make a more or less verbatim copy of the
> original, and then as a follow up project update it for groff and
> friends.

That's my understanding too.

> We're trying to create a resource, not a shrine, so I, for one,
> wouldn't insist on keeping the reference as is.  I wouldn't object to
> removing it altogether.  Really, I don't think it much matters for the
> first go around.  When and if we update the book, then we would want
> to get it right.  Of course, all that's only my opinion.  Others may
> differ and who knows what sort of loony legal requirements there are.

Here's part of a reply from Tim O'Reilly, (joint?) copyright holder of
the book.

    All of what you suggest would be terrific, and welcomed.  Consider
    permission already granted on adding details on groff extensions, as
    long as they are clearly flagged as additions to the original text
    (could be in release notes or some other kind of comments; doesn't
    have to be inline at each occurrence!)

I think we should get UTP transcribed without adding any extra stuff.
I've flagged errors in the original book with .Rn so others can agree
before I deviate.  I understand others have fixed stuff as they've found
it and that's fine.  I don't think these kind of changes fall under the
work Tim's referring to above so I'd like to see a `version 1.0' release
that builds to a finished PostScript book.  This would be of immediate
use and Tim may even link to it from the book's home page.

*When* that point's reached, it's time to start work on bringing it up
to date.  Appendices may be deleted.  And other large scale changes
could happen.  At this point we need to clearly indicate we've deviated
from Tim and Dale's work so it doesn't reflect on their reputation.  We
can point people back to version 1.0 for the original text.

If someone spots a problem with 1.0 then we can fix it on a branch
starting at that point, possibly duplicating the fix into the main work
version.

This might suggest the need for CVS to ease keeping track of who's
changed what, when, and why.

What conditions Tim would be happy with our new version being
distributed under is something we'll have to go and ask him nearer the
time.  I don't think it'll be a problem so we might as well ask first
rather than seek forgiveness afterwards.

Larry wrote:
> My thought, a couple of weeks ago, was "does the title 'Unix Text
> Processing' even apply anymore?" First, TeX and Lout exists & have
> their partisans. Second, groff has escaped the Un*x boundaries; there
> are Windows versions (both native and Cygwin) and MacOS X includes it
> (although at that point, it's really a straight Un*x app again).  ...
> But once we finish reviving the original, everything is in play as far
> as I'm concerned -- including the title.

I agree we may decide that the book should become more groff specific,
with less emphasis on shell syntax, etc.

Meg McRoberts wrote:
> I am assuming that it will be published on the web and not actually
> put into hardcover, so if we do a series of small docs, it doesn't
> matter.

I'd assumed the main use would be reading PostScript/PDF either on the
screen or paper.  HTML would be a useful secondary format for quick
reference.  As for paper printing, perhaps Rich Morin would add it to
his Dossier collection.

    http://www.ptf.com/ptf/dossier/

Meg McRoberts wrote:
> Do we have some sort of a "Style Guide" for the UTP?  If not, I'm
> going to scratch up a rough one to use for a consistency edit.
> Nothing fancy, just to specify fonts, indents, and so forth.

That would be good.  It may become material for our version of the book.
Details like getting \fIhalf\fRlife to format nicely by inserting a
sliver of space between the `f' and the `l' would be nice.

> It looks to me like the utp macros are actually putting a bit of a
> space between paragraphs which is not in the original book but I like
> it.

I don't think I do.  And it makes a row of one-line .IP's look very
`white'.  A quick scan of W. Richard Stevens and Knuth books shows they
don't use it.  Any chance it can be dropped?  The .LP/.PP distinction it
already there to help the eye find the start of a paragraph.

Cheers,


Ralph.