At 03:36 AM 1/23/00 -0500, Matthew Orgass wrote:
> > Disagree. Book publishers can take formatted or unformatted text in and
> > turn it into a book. They do it all the time. They don't *like* doing it,
> > but they'll do it just fine,
>
>   It's certainly possible, but I don't consider "just convert this to
>something I can use" to be "ready for publishing".  FrameMaker+SGML can
>read DocBook directly.

We may be jumping the gun here. My experience with publishers is that you 
should not assume that they use useful publishing software. O'Reilly is an 
exception, but we don't really have a publisher in line at this point.

> > particularly for a not-heavily-formatted book such as this one will be.
>
>   But it *should* be heavily formatted.  I can't think of any type of book
>that would need more formatting then technical documentation.

I look at a typical Unix installation guide and I see a very small number 
of formatting items.

> > > While SGML isn't trivial to learn,
> >
> > UNDERSTATEMENT ALERT! :-)
>
>   Maybe a little, but SGML is really not that difficult, especially from
>an authors POV (writing DTDs and stylesheets are a little more
>challenging, but most people will not be doing this).

We so severely disagree here I don't know where to begin.

> > I truly think you're overengineering the problem and will possibly drive
> > away contributors.
>
>   This type of project is *exactly* what DocBook is designed for.  pod and
>roff are nice for writing man pages (especially pod), but when you want to
>publish to multiple media you really want more markup.

And here. This project will need many folks writing and editing different 
parts. DocBook is a great tool if everyone on the project knows and 
understands it; I don't think that's a reasonable assumption here. Learning 
POD takes much less time, and the output is acceptable for the type of 
project people have been talking about so far.

> > Actually, I disagree. I think we should shoot for *after* the 1.5 release
> > so that we're sure that it is correct for 1.5. There's nothing more
> > frustrating to a novice user than to get a set of installation 
> instructions
> > that are wrong (but were supposed to be right but the darn developers
> > changed something near the end...).
>
>   Hmm... I guess you're right.  It is best to err on the side of caution
>with such a major change.  And if 2.0 is the next release after 1.5, that
>would be a great time to introduce the new documentation.

Er, no, let me try again. After 1.5 is finished, we finish the installation 
guide. We slip that onto the 1.5 CD and on the netbsd.org web site. If 
people get fritzy about changing the CD image after it is finished, we 
include the current snapshot of the guide at the time of CD freeze but say 
"there's probably much better and more accurate stuff at <URL>; try going 
there and getting the new doc before installing". This gives the 
gotta-have-it-now folks something, but points the rest of the people to 
something (hopefully) better.