On Sun, 23 Jan 2000, Paul Hoffman wrote:

> 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.

  Good point, though SGML's forced structural soundness would make it
possible to convert mechanincly with good results.  I guess this argument
should be "easier to publish" instead of "ready to publish". 

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

  Look under /usr/src/distrib/notes and take a look at the markup used in
the current install guide.  Also, remember that this isn't just the
install guide but the entire manpage collection.  One example of where the
additional markup provided by DocBook would be useful is structures: in
DocBook, you can individually mark up the name, values, and members and
(with appropriate tools) use this info to create a more detailed and
helpful index.

> >   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.

  Well, HTML is a SGML DTD and many people know HTML.  Unfortunatly, many
things are tolerated in HTML that are not allowed in SGML, however this at
least means that many people are generally familiar with it and just need
a little more detail on exactly what is and is not allowed (and, of
course, would need to learn DocBook elements).

> 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.

  The main problem with POD is that it is too simple.  This is good if
your goal is to get people to write manpages who wouldn't if they had to
work at it at all, but is not a good tool if your goal is to publish to a
variety of media.  Even just converting from the existing man pages to POD
would loose a large amount of markup.  IMO, the best way to deal with
contributions in other forms is to write an interactive converter that
speeds up the process of adding additional markup.

> 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.

  In that case I disagree.  Making sure that the documentation agrees with
whatever last minute changes are made is release engineering's job.

Matthew Orgass
darkstar@pgh.net