Date: Wed, 7 Jul 1999 11:39:22 +0100 From: Nik Clayton <nclayton@lehman.com> To: Bob Van Valzah <Bob@whitebarn.com>, nik@nothing-going-on.demon.co.uk Cc: doc@freebsd.org Subject: Re: FreeBSD Formatting Help Message-ID: <19990707113922.V15628@lehman.com> In-Reply-To: <37820C68.3998AAA@WhiteBarn.com>; from Bob Van Valzah on Tue, Jul 06, 1999 at 09:02:17AM -0500 References: <37820C68.3998AAA@WhiteBarn.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Bob,
[ I've cc'd this reply to doc@FreeBSD.org, so that it gets in to the mail
archives, and helps out any lurkers who might be wondering the same
questions you are ]
On Tue, Jul 06, 1999 at 09:02:17AM -0500, Bob Van Valzah wrote:
> Nik, Many thanks for your FDP Tutorial material. I'm currently clawing
> my way up the SGML learning curve on a FreeBSD system and your tutorial
> has moved me along farthest with the least effort.
It's good to know people are finding it useful. There are still gaps,
but I'm working on closing them.
> But I'm still a bit confused when it comes to actually formatting
> DocBook docs with FreeBSD. Stream of consciousness questions:
OK.
> * Do I still need/want the sgmlfmt command from the sgmlformat-1.7
> package?
Yes. The FAQ and a couple of the tutorials are still in LinuxDoc format,
which needs sgmlformat. When they've converted to DocBook the need for
sgmlformat disappears.
> * What about the tex-3.14159 vs teTeX-0.9.981113 packages?
You only need TeX if you want to produce Postscript or PDF output,
otherwise it's not necessary.
You should only have one of these installed. teTeX-beta is currently
recommended, as it installs all the optional TeX packages (like hyperref)
that are required by the Jade TeX macros. tex-3.14159 will probably
work, but will need some configuring by hand. I'm not a hardcore TeX
user, and can't advise on how you'd get tex-3.14159 to work for you.
> * Do I need both?
No. See above. Also, the teTeX port was recently upgraded to v1.05,
which means it's now out of beta. You should actually be able to use
the teTeX port now instead of the teTeX-beta port.
> * Why is dvips available as a port and not as a package?
Good question, don't know. The port maintainer is jmz@FreeBSD.org, who
can probably explain why.
> * Will I even need dvips?
I don't think so. I haven't needed to install it by hand, so I assume
a version of it comes with the teTeX port -- however, the version in
the ports tree might be more up to date.
In addition, if you're producing PDF output and not Postscript output
then you don't need dvips. If you are producing PS output then you
will need it (but as I say, I think it comes with teTeX).
> * What does LaTeX have to do with any of this?
It doesn't. As I understand it;
TeX is the document formatting system. It's big, forbidding, and has lots
of arcane commands to precisely control the layout of your document. You
can also write macros in TeX.
LaTeX is a commonly used macro package, that abstracts out a lot of the
TeX syntax, so that you can write one command ("Make this document have
2 columsn from this point on") instead of the multitude of TeX commands
you would otherwise need to write.
The FDP doesn't use LaTeX at all -- the SGML sources are fed through a
processor called Jade, which outputs TeX directly.
The TeX output by Jade assumes that another TeX macro package is installed.
This macro package is called JadeTeX. JadeTeX is like LaTeX in that it's
purpose is to hide some of TeX's command structure and make it easier to
use. The difference is that LaTeX is designed to be used by people,
JadeTeX is designed to handle the output from Jade.
> * How do I produce one giant .html file?
Assuming you've got the doc's installed;
% cd /path/to/doc/en/handbook
% make FORMATS=html
What's going on under the hood? The stylesheets we are using to convert
from DocBook to HTML have a configurable parameter called "nochunks".
If you tell the system to make the "html" format then it turns on this
paramter by passing the "-V nochunks" option to Jade.
This option is only understood by the stylesheets. Jade doesn't understand
what "nochunks" means, it just passes it on to the stylesheets, which do
understand what it means.
> * How do I produce a linked tree of .html files?
As above;
% cd /path/to/doc/en/handbook
% make FORMATS=html-split
The default stylesheet behaviour is to produce split files.
> * What does a Makefile look like that produces all these wonderful
> formats from a single DocBook document?
Take a look at
/path/to/doc/en/handbook/Makefile
which is the main Makefile for the Handbook. All this does is set a few
variables. The body of the work is done in
/path/to/doc/share/mk/docproj.docbook.mk
If you know make(1) then this should be relatively easy to understand. It's
heavily commented, because I expressly wanted other people to follow it
relatively easily.
The actual command lines that are run to convert the documentation to the
various formats can be found by searching for ".MAIN" in this Makefile,
and then looking at the targets below there.
>
> As you can probably tell, I'm coming at this from the point of view of a
> FreeBSD use who just wants to be able to produce PDF/PostScript/HTML
> from a single document base. Whatever the answers to these questions, I
> think they'll make valuable additions to your tutorial and perhaps to
> the DocBook FAQ as well.
This is the more interesting comment. I'm a bit torn about how this
should be done in FreeBSD.
Through the ports system you can install all the applications you need.
In particular, textproc/docproj brings in all the formatters, macro
packages, and so on.
What isn't in the system are any user friendly front-ends to make it
easier for people such as yourself to actually use the tools.
I *think* this is probably the right way to go. The FDP Makefiles
(as explained above) are specifically for the FDP internal documentation
(FAQ, Handbook, tutorials, and so on). They are not designed so that
they can be taken out of the FDP and dropped in to someone elses
documentation system, and just work.
I think this is probably a good thing -- your documentation requirements
are probably different from ours, which would mean that you would need to
customise the Makefiles anyway -- it's better to provide you with clearly
documented examples that you can cannabilise as necessary, than to try
and write a collection of Makefiles that try and encompass everyone's
requirements.
That said, I could be wrong about this.
The Linux Documentation Project came up with "sgmltools", which has since
spun off to be a separate project (<URL:http://www.sgmltools.org/>).
However, it now seems to be spinning down, as the principle architect,
Cees de Groot, has had to step back from it due to other commitments.
In a nutshell, SGMLTools is/was a collection of Python scripts that did
two things.
1. Managed the installation of the various programs necessary to convert
DocBook to different formats.
2. Provided commands (like "db2html", "db2pdf", and so on) that just
converted DocBook to one other format. All these commands do is
call the underlying Jade, TeX, and other applications for you, trying
to get the command line right.
I don't think this is appropriate for FreeBSD for a few reasons.
First, (1) above is already capably handled by the ports system. We don't
need to reinvent that particular wheel.
I'm unconvinced of the necessity of (2). In many cases the command line
for converting from (say) DocBook to something like RTF is only one or two
lines -- you can put this in a shell script yourself. And if you need
anything more complex then you're almost certainly writing your own scripts
and Makefile's anyway, so the additional layer of simplification doesn't
really buy you anything anyway.
Plus, of course, there's the fact that they're all written in Python. I've
got nothing against Python as a language (I've never used it, but I've
heard lots of good things about it[1]). But I'm not about to bring in
something for the FDP that requires a whole new programming language to
implement it.
Oh, and the name "SGMLTools" is really a bit of a misnomer -- at version
1 the name would more properly have been "LinuxDoc Tools", and at the
current version 2 it should be called "DocBook Tools".
And FWIW, I've been active on the SGML Tools mailing list for the past
year or so, and I have been keeping a close eye on what's been going on.
But as I say, I'm not convinced it's the best solution for FreeBSD.
For your particular situation, I'd recommend studying the doc/share/mk
Makefile, and work out which bits you can lift from there to suit your
purposes. You can then create your own documentation build environment,
either using make(1), as we have, or with shell scripts, or whatever.
I hope all that helps (you, and anyone else reading this). If you've
got any more questions, don't hesitate to ask -- but if you can send 'em
to doc@freebsd.org instead of direct to me, other people have a chance to
get involved too.
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?19990707113922.V15628>