Doc BoF at EuroBSDCon

[Len Zettel]

On Monday 06 December 2004 06:01 pm, Murray Stokely wrote:
> On Mon, Dec 06, 2004 at 12:48:16PM +0000, Len Zettel wrote:
> > So I took a stab at creating an sgml file incorporating the changes
> > (by editing the existing file for the document in question).
> > When it came time create an html file from the sgml (so I
> > could check the work) I flunked out.  The make couldn't
> > find some of the necessary boiler plate.
>
> Ok, then you either didn't have all the tools installed (the docproj
> port can help), or didn't have all stylesheets checked out from
> CVS/CVSup (the full 'doc' module), or temporarily something was
> broken.  The last possibilty is not as likely as the first two.
>
I did the docproj port.  The problem probably was that 
when I started changing things I wanted
to keep the original tree pristine, so I moved some (but not
all) stuff.
If you will excuse the criticism, this is a classic chicken-egg
problem.  I have been finding it very difficult to figure
out the ins and outs of the make system from the
existing documentation.  

It is undoubtedly all there and very clear once you know
the system.  Unfortunately, I have found using the existing
docs to learn about the system to be a real bitch.
Too much is missing about what all the parts are,
how they work together, exactly what each part
does (and doesn't), and where they are.  This leaves one
slavishly trying to copy existing recipes character
for character and then wondering what to modify
when they don't work as expected.

But I haven't totally given up yet---
  -LenZ-

> When you take another stab at it, please send out the relevant error
> messages, either to the list or to me personally, and I'll try to help
> you get it all sorted out.
>
> > Part of my ever-expanding "todo" list is to take another
> > stab at going from sgml to html.  When I am happy
> > with that I will take another crack at a PR or two.
> > That likely won't be for a while yet.
>
> That would certainly be appreciated.
>
>    - Murray