Doc BoF at EuroBSDCon

[Tom Rhodes]

On Thu, 2 Dec 2004 12:29:12 -0800
Murray Stokely <murray at freebsdmall.com> wrote:

> On Thu, Dec 02, 2004 at 09:10:17PM +0100, Simon L. Nielsen wrote:
> > > >   - des agreed to make a script for the actual conversion of the files
> > > >     from SGML to XML.
> > > 
> > > What new applications do people have in mind that this enables?
> > 
> > I must admit that I don't have any specific plans.
> 
> In general I think sweeping changes like this just look like busy work
> in less you've got plans for enabling some cool new functionality with
> them.  If you don't know what such a change would gain for us, we're
> better off spending that amount of time writing new documentation.

Or trying to make the documentation look better/more professional.

> 
> > > Is the plan to phase out DSSSL at this point?  The stylesheet work
> > > should be more difficult than converting SGML files to XML, but it's
> > > not mentioned here.
> > 
> > I have not personally looked into the specific toolchain issues.  The
> > last time I chekked DSSSL was still required for print (ps/pdf/etc.)
> > output, though HTML could be done entirely with XSL.
> 
> Well, yes, the toolchain issues are where all the work needs to be
> done.  PassiveTeX can do a decent job, and RenderX allows for some
> really cool print output functionality that jade is missing.
> 
> > When you get to that point I don't think it matters much (both for
> > SGML and XML), it's mostly with regard to make(1) the diretories cause
> > problems.
> 
> Directories do not cause problems with make.  We use them all over the

That's right, it's not the directories, it's the doc build
infrastructure.

> src/ tree and have been doing so for 20 years.  A few changes were
> recently made that were not correct.  Those should be fixed or backed
> out until they can be done properly, there is no problem with make and
> subdirectories, only with a few broken commits.
> 
> > > and the directories
> > > provide a natural place for the language-specific image files for a
> > > given chapter.
> > 
> > Yes, that is a plus.  A minus IMO is when dealing patches, you very
> > often can't just "cd foo/bar/handbook ; patch </foo.patch" since the
> > patch is often relative to the chaptor subdir.  I know it's a minor
> > thing, but it still bugs me often.
> 
> Consider using the -p option to patch.

Sometimes that doesn't work too well unless you actually know
the amount of directories you need to descend to.

> 
> Your same argument could be used for collapsing many of the
> directories in src/sys and throughout the rest of the system, but I
> don't think we need to flatten our namespace like that.
> 
> > Certainly.  I just think they are more painful than useful, which is
> > why I brought it up as a possibility at the BOF.
> 
> I think you are in the minority with that opinion, but it's certainly
> good to brainstorm.

Count me in that minority, in fact, (almost) everyone that was at
the doc bof thought it might be nice to rid ourselves of the
directories since we have very few source files and just as many
Makefiles.

Your counter argument makes me wonder why we have 1 file in
src/sbin/mount, for instance "mntopts.h" that could easily be
in the include directory.  When I think about it, in src, we
have a Makefile for every utility.  A toplevel Makefile which
descends in other directories and gets even more directories
with that; but in the src case, those secondary "utility"
Makefiles actually work.

I think in this case, those chapter Makefiles should either work
or be removed.  Honestly, I don't think this issue is anywhere
near as important as other things:  FAQ, XML, handbook and
multiple versions, etc.  But still feel strongly that the
Makefiles are wasted bytes.

-- 
Tom Rhodes