Date: Thu, 2 Dec 2004 15:58:46 -0500 From: Tom Rhodes <trhodes@FreeBSD.org> To: Murray Stokely <murray@freebsdmall.com> Cc: "Simon L. Nielsen" <simon@FreeBSD.org> Subject: Re: Doc BoF at EuroBSDCon Message-ID: <20041202155846.5e5dd3c8@localhost> In-Reply-To: <20041202202912.GC55779@freebsdmall.com> References: <20041128202656.GL750@zaphod.nitro.dk> <20041128212851.GB48499@freebsdmall.com> <20041202201016.GL753@zaphod.nitro.dk> <20041202202912.GC55779@freebsdmall.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 2 Dec 2004 12:29:12 -0800 Murray Stokely <murray@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041202155846.5e5dd3c8>