[Mono-list] GNOME.NET Tutorial

[Dietmar Maurer]

On Fri, 2002-11-15 at 23:42, Mathias Hasselmann wrote:
> On 15 Nov 2002, Dietmar Maurer wrote:
> 
> > > My suggestion is to use plain HTML, and in the future, and when the
> > > documents are finished, and you have not spent days fighting docbook,
> > > you can have a volunteer with lots of time to do the conversion.  Big
> > > deal.
> > 
> > HTML --> ugly output + missing features :-( Cant see any advantage with
> > html.
> 
> 	That pure FUD. Hope you've heard about CSS and the class 
> attribute: If _strict_ HTML4 or _strict_ XHTML is used it's easily 
> possible to write XSLT stylesheets converting the docs into a reasonable 
> subset of for instance docbook.

Ok, I guess I am a bit out of Date, but good layout is difficult, and I
doubt that you can generate good layout with tools like CSS, XHTML or
docbook. Thats why I wrote HTML --> ugly output.

LateX or TeX are tools to generate a reasonable layout, because they
give reasonable control over the layout.

> 
> 	Well: What's wrong with docbook? 
> 
> 	1) to view formated docbook on the screen you'll need a 
> 	   postprocessor

no, you can use psgml mode and simply hide the tags.

> 	2) to postprocess docbook you'll need the right version of 
>            bloated sgml tool plus you'll need the proper version of 
> 	   zillions of stylesheets and dtds installed at the right place

my debian does all those things for me ;-)

> 	3) to take advantage of docbook you'll have to learn a bloated 
> 	   overcomplicated dtd

Thats simply not true. There are just a few thinks you need to learn.
But I agree, docbook has many tags for special tasks, and thats the
advantage of docbook (AFAIK thats the design idea behind dockook). But
you don't have to use all those tags. 

For example docbook defines tags for bibliography entries, so dockook
addresses all those common problems. Does XHTML provide solutions for
that?

> 	What's better with docbook?
> 
> 	1) Each computer today comes with software capable to preview HTML 
> 	   on the view -- no bloated extrasoftware needed

I normally use psgml mode or simply docbook2txt to generate a text only
version. I can view that with any text viewer. So I don't need bloated
software like an HTML viewer. To view the printable version I can use
xpdf, xdvi or gv.

> 	2) if you wish to layout HTML content based it's as easy as adding
> 	   few class attributes and writing a CSS using a bloody simple 
> 	   syntax

Interesting. Please can you provide me with an example. Maybe a simple
paragraph with grouped style and correct hyphenation. Including a short
mathematical formula like a = (b/c)/(c/d). And maybe a reference to a
footnote, and a reference to a book, which is listed at the end of the
document.

Well, I know that each tool has some advantages, and many drawbacks. I
would just like to have the following feature for my documentation:

- refer to code (structure definition and method calls) (docbook+gtkdoc)
- include pictures (html, dockook, latex)
- write mathematical formulas (docbook?, latex, xhtml?)
- include references to articles/books (docbook, latex)
- automatically generate table of contents/index/glossary (docbook,
latex, xhtml?)
- do some simple markups to emphasis text (all tools)
- solution for bibliography entries (latex, docbook)
- include references to other portions of the document/pictures (all
tools)
- nice layout for the printable version (latex).
- good on screen layout (html, xhtml, docbook)

So from my point of view docbook has most feature. Just tell me if I
missed any XHTML/CSS feature - I admit I don't know much about that. IMO
XHTML/CSS does not address most problems and thats why it looks simpler.

- Dietmar