Doc BoF at EuroBSDCon

[Simon L. Nielsen]

On 2004.11.28 13:28:51 -0800, Murray Stokely wrote:
> On Sun, Nov 28, 2004 at 09:26:57PM +0100, Simon L. Nielsen wrote:
> > - Changing doc from SGML to XML (yes, really do it this time)
> > 
> >   - 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.

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

> The XSL support is partly broken.

In general or just in the FreeBSD doc makefiles?

> > - It was suggested to move chapter files to the main directory e.g.
> >   en_US.ISO8859-1/books/handbook/x11/chapter.sgml ->
> >   en_US.ISO8859-1/books/handbook/x11.sgml, since there does not seem
> >   to a big point in all the sub directories, and make does not like
> >   the sub directories well..
> 
> You don't need a makefile in each subdirectory since you'll be
> removing the ability to build only a single chapter, so there is no
> make consideration here.

The consideration is that make(1) (in my experience) is much simpler
if you don't have a lot of "arbitrary" directories.  In dependencies
etc. you don't have to deal with directories.  E.g. one of the
currently broken things wrt. to OBJDIR support is the subdirectories
for IMAGES_EN, which is a pain to fix (I have tried) since the image
filenames contain a directory (it's a bit since I looked at it so I
could be remembering the details incorrectly).

> Directories aren't an issue if you just XInclude the
> <dirname>/chapter.xml from the root book.xml,

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.

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

> I don't see any need to remove the directories.  At least it seems
> unrelated to the other goals.

Certainly.  I just think they are more painful than useful, which is
why I brought it up as a possibility at the BOF.

-- 
Simon L. Nielsen
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20041202/7f7872ce/attachment.sig>