Re: style sheets for gnome

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Mon, Jun 12, 2000 at 02:55:16PM +0200 or thereabouts, Fatih Demir wrote:
> F. Heitkamp [ Mon, Jun 12, 2000 at 07:21:28AM -0400 ] : 
> > Some times when I compile gnome applications and libraries, some of 
> > them from CVS, I get errors of undefined symbols and such from jade.

I would expect the majority of these to occur from CVS, actually, or
from packages where the maintainer didn't realise that the DTD in the
docs was a GNOME-specific one. Most package maintainers build all the
docs before putting a tarball together to avoid precisely this 
problem. 

> > I've collected nearly all the stylesheets and catalog files I can 
> > find, but I must be missing some.  Is there a repository of these 
> > specific (or not) for gnome?
> 
> would be also interesting, as my jade laso cries about these
>  ones ...

Get the GNOME-specific ones at:
	http://people.redhat.com/dcm/software.html
Specifically, you'll need these two:
	http://people.redhat.com/dcm/png-support-3.0.dtd
	http://people.redhat.com/dcm/png-support-3.1.dtd
And the stylesheet for both HTML and .ps:
	http://people.redhat.com/dcm/gdp-both.dsl

The page contains them as individual things, as a tarball of the lot, 
or as an RPM. Martin Baulig made a deb of gnome doc tools (may well
be called gnome-doc-tools) back in January or February, but I think
things got tweaked after that, and I'm not sure where it lives. One
of the more Debian-familiar GDP folks is trying to make an up to 
date version of them.

In an attempt to lay to rest some of the confusion over this, and
to explain why we had to use non-standard stuff despite the 
complications it is clearly causing, here's the summary:

GNOME documents are written in DocBook. That's a markup language
(very similar-looking to HTML; in fact they're from the same family)
which marks up the content of the document and not how it should
appear.

You take that DocBook file and by running it through different
programs you can produce an HTML version, a PostScript file, a PDF,
and so on. If you have the tools, I am told that you can convert
DocBook into practically anything, including formats which can be
read (listened to?) by people who are blind or partially-sighted or
...well, pick your format :) To decide how it appears, you look at
a stylesheet. (For HTML, it goes, "Oh, this says <para>. I'll turn that 
into a <p>. This says <filename class="directory"> I'll turn that into a 
different font so it's obvious it's a file name,,." Etc.)

The results end up as HTML: this usually goes into the 
$prefix/share/gnome/help/appname/C/ directory, which is what the help 
browser will look at, and this is all done for you in the majority
of packaged GNOME apps by the maintainer. 

There are plenty of tools which will do the conversion from DocBook,
but the ones GNOME uses are the ones lots of other free software
projects use: they are available from ftp://sourceware.cygnus.com.

Generally, to build DocBook documents you need those. 

But. But, but, but..

Like several other of the free software documentation projects, we
found problems with the stylesheets and with the version of DocBook
itself. One specific issue was that DocBook wanted GIF graphics, and
GNOME likes PNGs (patents and so on). (The KDE Documentation Project
had the same problem, I believe.) That required adding an extension
to DocBook. Another was that, um, we wanted nice white backgrounds to
the HTML results :) That required writing a new stylesheet. Those
(and some other things) are the things at the page I mentioned above,
and the stylesheets are also in CVS (gnome-docu/gdp/dsssl/ I think).

DocBook 4.0 has just come out, and it now accepts PNGs, so this issue
will Go Away soon. (We hope.) (

If in the meantime you can't build docs at all, ensure you first have
the docbook tools: the ftp://sourceware.cygnus.com site has
sgml-common, docbook, stylesheets and jade, which you need, jadetex
(which you need if you want to make .ps copies) and psgml (which is
used for editing DocBook in Emacs). Then get the stuff from the RH
site and apply that on top. This should now work. Really. 

If you don't -want- the help stuff turned into HTML and just want
to build evolution or something, you can remove "docs" or whatever
from the, um, SUBDIRS (?) section of Makefile.am. Or you can just
switch DTDs (the top two lines in angle brackets of a .sgml file)
from
<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
]>
to
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
]>

(or "book" instead of "article")

and build it accepting that it will produce broken pictures unless 
you go through and remove all the <graphic>...</graphic> sections.

You won't normally meet this, because all the big packages go out
with the docs ready-built specifically to avoid people having to
track down and install the standard tools and then the GNOME tools
and so on. But tarballs of "still in development" apps do seem to
have just the docbook files and not the HTML results in, and CVS grabs 
certainly just have the docbook.

Oh, one last thing: someone on Mandrake posted with problems about
unrecognised elements and I thought it was a lack of the GNOME DTD.
Someone else later said they had trouble with Mandrake's docbook
setup and had to mess about with it. Unfortunately, I don't know what
package version or Mandrake release that was... :( 

I suspect this has now completely confused everyone. But maybe not.

Telsa "honestly, docbook is cool. Really."