Date: Mon, 29 Nov 2004 06:03:20 +0000 From: Nik Clayton <nik@FreeBSD.org> To: "Simon L. Nielsen" <simon@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Doc BoF at EuroBSDCon Message-ID: <20041129060320.GA26868@clan.nothing-going-on.org> In-Reply-To: <20041128202656.GL750@zaphod.nitro.dk> References: <20041128202656.GL750@zaphod.nitro.dk>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --]
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.
>
> - With SGML -> XML conversion we will loose the "IGNORE"
> functionality from SGML, but it is not widely used, and where such
> functionality is needed it can e.g. be handled in other ways.
> This is used to be able to build sub directories in the Handbook,
> but this has been broken for a while and nobody has complained
> about that yet...
In case you're not aware, 'xml' is a supported output FORMAT. You
should be able to do
make FORMAT=xml
in any of the document directories and get book.xml or article.xml
generated as appropriate.
I strongly recommend that you do this and experiment with getting an
XML/XSL toolchain in place *before* doing a full cutover to XML.
You are also aware of doc/share/xsl, right? And that you can do:
make STYLESHEET_TYPE=xsl ...
?
> - 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..
Don't do that. The point of the subdirectories is so that all the files
associated with a chapter (images, example files, and so on) are kept
together with that chapter.
Otherwise you'll end up down the road with filenames like
vinum-foo.png
vinum-bar.png
x11-foo.png
x11-bar.png
and so on. All you've done is swapped the '/' for a '-'.
It also lets you split up the chapter.sgml files in to smaller files,
with a single chapter.sgml 'driver' file (in the same way that things
like book.sgml include all the chapter.sgml files).
> - Redoing the build system (make files), because it clearly shows its
> age and several things are broken, e.g. OBJDIR.
Makes sense. I'd be happier seeing a comprehensive list of the things
that are broken though, so we can measure the replacement and make sure
it solves the problems.
> - To be as little disruptive as possible to normal doc work it was
> suggested to branch the doc/ tree for the work, and do the work in a
> separate branch, to be merged into the main branch later again.
Rather than branch it in CVS I'd say use Perforce for this work.
> - Handling multiple FreeBSD release branches (4.X/5.X/6.X) in Handbook
> to get rid of notes about "For 4.X do....". There should be
> multiple build Handbook versions on website, and perhaps one
> complete one with "This section is for 4.X only..." and so on
> automatically added.
>
> - It was suggested to handle this with (SG|X)ML attributes on like
> done in the release documentation for different architectures.
> simon was volunteered to implement this.
The DocBook XSL stylesheets call this 'profiling'. See
http://docbook.sourceforge.net/release/xsl/current/doc/html/rn19.html
for more details.
All the changes discussed so far will also require updates to the
Primer. Who volunteered to keep that up to date?
N
--
FreeBSD: The Power to Serve http://www.freebsd.org/ (__)
FreeBSD Documentation Project http://www.freebsd.org/docproj/ \\\'',)
\/ \ ^
--- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- .\._/_)
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (FreeBSD)
iD8DBQFBqruok6gHZCw343URAuQ5AKCLidW7gEoC3ijYNdWIjlLUmJ4DNwCfV4sG
8LxdoH2LQjTBddtZNbd+ANk=
=TYLg
-----END PGP SIGNATURE-----
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041129060320.GA26868>