Date: Tue, 30 Mar 1999 08:11:15 +0100 From: nclayton@lehman.com To: Joel Ray Holveck <joelh@gnu.org> Cc: Kris Kennaway <kkennawa@physics.adelaide.edu.au>, Nik Clayton <nik@nothing-going-on.demon.co.uk>, doc@FreeBSD.ORG Subject: Re: Handbook DocBook cutover complete Message-ID: <19990330081115.S14492@lehman.com> In-Reply-To: <86r9q7egfq.fsf@detlev.UUCP>; from Joel Ray Holveck on Mon, Mar 29, 1999 at 10:42:49PM -0600 References: <19990327162554.K3136@catkin.nothing-going-on.org> <Pine.OSF.4.10.9903281636550.2929-100000@bragg> <19990329105741.L23968@lehman.com> <86r9q7egfq.fsf@detlev.UUCP>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Mar 29, 1999 at 10:42:49PM -0600, Joel Ray Holveck wrote:
> >> Can I ask what the differences and benefits are?
> > As follows;
> > * LinuxDoc is descended from the QWERTZ DTD, and was designed to serve
> > the needs of the Linux Documentation Project.
>
> How do these needs differ from those of the FreeBSD documentation
> project?
They're not radically different. The LDP had a lot of people used to
LaTeX, and wanted something that would map to that quite easily, which
LinuxDoc does. DocBook existed then, but they didn't choose it for some
reason. Whether this was because of "not invented here" syndrome, or
something else, I don't know.
> > When processed, both those might be displayed in a monospaced font.
> > However, the DocBook version includes extra information. We don't do
> > it yet, but the DocBook Handbook will eventually include several
> > indices. One of these will be a list of each page where each filename
> > is mentioned, allowing you to quickly see all the places where (for
> > example) ppp.conf is referred to.
>
> It also means that if, later on, we decide that filenames look cleaner
> in italics instead of monospace (for instance), we can do so.
Yep. We can even do so on a 'per output format' basis. From reading
examples of other typeset documentation, I think filenames in italics for
the print version would work well. For HTML (due to the poor rendering of
italics on many screens) mono-spaced would be better.
> > * DocBook is extensible. It's relatively easy to add your own elements,
> > for things that are missing from DocBook. I've done this for the
> > Handbook, adding things like "<hostid>" and "<maketarget>". This is
> > harder to with LinuxDoc.
>
> What are you using these tags for?
<hostid>freefall</hostid> is a hostname.
<hostid role="ipaddr">127.0.0.1</hostid> is an IP address.
<hostid role="fqdn">ftp.freebsd.org</hostid> is a fully qualified domain
name.
<hostid role="mac">xx:xx:xx:xx:xx:xx</hostid> is a MAC address.
<maketarget>all</maketarget> and <maketarget>install</maketarget> are
targets in a <filename>Makefile</filename>.
<makevar>DESTDIR</makevar> is a variable that controls where files
will be installed.
See doc/share/sgml/freebsd.dtd for more information.
> > * Tools to convert DocBook to other formats are not quite as advanced
> > as the LinuxDoc tools, but are getting their rapidly.
>
> I would be interested in hearing your comments on DocBook tools, what
> you find indispensable (both in the drafing process and for finals),
> etc.
[x]emacs for all editing, in conjunction with PSGML mode. It makes writing
SGML much easier. Because DocBook contains no presentational markup you
don't need a graphical editor (or at least, I don't).
For proof-reading I tend to convert to Postscript, print it out, and
annotate it. That's mostly because most of my proof reading time is
spent on trains without a laptop, so this is the best approach for me.
Turning DocBook in to HTML, Postscript, and other formats is relatively
simple using Jade and some DSSSL stylesheets (all in the ports collection).
At the moment, doc/en/handbook/Makefile contains all the logic to do this
automatically. I'll be splitting this up in to an independent Makefile
(bsd.docbook.mk?) soon, so that converting your own documents will be as
simple as
#
# Makefile to convert foo.sgml to HTML, PS, etc
#
SRCS= foo.sgml
FORMATS= html html-split ps rtf
.include "bsd.docbook.mk"
At some point I'll port (unless someone beats me to it) the SGML Tools
package as well (which is just a set of wrappers around programs like
Jade) so you can do
docb2html foo.sgml
That's not very high on my list of priorities though.
> > As it currently stands in the repository, the DocBook Handbook can be
> > converted to HTML, Postscript, plain text, and Microsoft RTF. A bug
> > that I'll fix this week is currently preventing PDF generation.
>
> The GNU project is writing a converter to TeXinfo.
That'll be handy. Have you got any pointers to more information? I
couldn't see anything about this on www.gnu.org.
Cheers,
N
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
--+==[ Year 2000 Testing: It's about time. . . ]==+--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990330081115.S14492>