Re: GUI for Lout

[Henrik Martensson]

Hi,

Using DocBook is certainly possible, and superficially tempting. There are
some problems though:

* DocBook is huge. Writing a filter that implements even a significant
subset
  is a lot of work. On the other hand, not supporting all of DocBook would
  almost certainly leave a significant, and very vocal, percentage of the
users
  stranded.

* DocBook is updated fairly frequently by OASIS. Changes are often not
  backwards compatible. This means a lot of maintenance work
  on the part of filter developers, or the system will not remain
  DocBook compatible for long.

  OASIS controls when DocBook is updated. Thus, Steven, or whoever makes the
  filter, would loose control over when to make updates. (Provided that
  it is deemed important to keep the filter up to date, of course.)

* It won't be possible to construct a "smart" filter that converts
  elements it hasn't encountered before. For example, it is easy to
  write a filter that maps something like this:

  <lout:Diag>
    <options>
      <lout:vsize>1f</lout:vsize>
    </options>
    <block>
    <lout:Box>
      <block>Box content<block>
    </lout:Box>
    <block>
  </lout:Diag>

  to Lout, even if the filter itself doesn't know about the @Diag or @Box
  symbols. Note that I have used a namespace prefix to indicate those
  elements that directly correspond to Lout symbols. There is no
  namespace declaration in this example fragment though. there are also
  technical reasons for making vsize an element rather than an attribute
  of lout:Diag, but I won't go into them at this point. (I might be wrong
and say
  something silly. I haven't thought all design issues through yet.)

  Doing the same conversion using a DocBook filter would require the filter
  to be more complex. It also requires that the filter has explicit
information
  about both DocBook tags and Lout symbols, which makes the filter
vulnerable
  to changes in both DocBook and Lout.

* New features (topic maps), and some old ones, like Tree and Syntax
  diagrams can't be implemented until OASIS come up with a Docbook
equivalent.
  In many cases they are unlikely to do so, at least in a way that is easy
to
  convert directly.

* DocBook provides only rudimentary equation support. This is bad.
  Future revisions will probably support MathML. This is good, for
  Docbook, but awful for anyone that has to write a DcoBook to
  Lout filter. XLout filters on the other hand, would have no problems
  converting equations, because the source and target formats would be
  very similar from the start.

* Lout provides a lot of formatting control. Much of this control would be
lost
  if converting directly from DocBook to Lout.

  Using an XLout DTD, either as source, or as an intermediate step, would
retain
  all of the formatting control that Lout offers.


As for writing a Jade back end for Lout, I don't know how difficult this
would be. I suspect it would be a lot more work than setting up an
XLout->Lout process, or a DocBook->XLout->Lout process, for that matter.

XSLT, I don't trust. Lots of hype, but it just doesn't deliver. There are
two important reasons for this:

* XSLT was designed specifically for transforming XML to XSL. Though it is
  possible to output in other formats, it is surprisingly difficult.
  For example, try converting "&#x00E5;" to "@Char aring", or to convert a
  URI to a file path with XSLT. Maybe not entirely impossible, but certainly
  very messy.

* The XSLT designers made some assumptions about XML, for example, they
  assumed external entities were on the way out, so they didn't support
  it. (You will get into trouble with things like the DocBook Graphic
  element, that does use an entity reference.) This limits compatibility
  with existing DTDs.

  In my opinion, XSLT has some growing up to do before it becomes
practically
  useful. (Though I must admit, the lack of functionality doesn't seem to
  have impaired XSLT's popularity so far. I know people who have used XSLT,
  and who are very satisfied with it, even though their filters do not
actually
  work!)

A Perl or Python filter would be much more powerful (though not necessarily
as elegant from a design point of view).


To sum it up, I think that an XLout DTD would be the best solution, if XML
is the way to go at all. It requires less work and less maintenance than
writing a DocBook2Lout filter. At the same time, there would be greater
flexibility and more power.

Even if one wants to author the documents in DocBook (which may be a good
idea), it is much less work to translate to an intermediate formatting DTD
before converting to Lout, than it is to do everything in a single step.
(This way, an organisation using DocBook need to translate only the DocBook
subset they actually use, not the whole thing. Also, they have the freedom
to format their DocBook documents any way they want, rather than being
locked into a standard DocBook2Lout format.)


Kind regards,

Henrik

---
Henrik Martensson
GNOSIS-Gruppen
Technical Documentation Services
URL: http://www.gnosisgruppen.com/

----- Original Message -----
From: Tim Churches <address@hidden>
To: Henrik Martensson <address@hidden>; <address@hidden>
Sent: Tuesday, June 06, 2000 11:16 AM
Subject: RE: GUI for Lout


> Henrik,
>
> Wouldn't it be better to use an existing, well established DTD such as
DocBook
> rather than create another one specifically for Lout, and then modify
existing
> conversion filters (either DSSSL for OpenJade or XSL) to emit Lout? There
is a
> a DSSSL stylesheet for DocBook which emits LaTex - it might be a lot
quicker
> to attack this and translate Latex markup into Lout markup. DSSSL
stylesheets
> are written in a Scheme-like syntax - doesn't look too hard (famous last
> words...).
>
> However, a direct translator in Python would also be nice. But best to use
an
> existing DTD.
>
> Tim Churches
>
> >===== Original Message From "Henrik Martensson"
<address@hidden>
> =====
> >Hi,
> >
> >Why not use XML? It would be a fairly easy to map Lout commands to an XML
> >DTD (XLout?). All that is needed then is to write a filter that converts
the
> >XML documents to Lout.
> >
> >From what I've heard, Python has excellent facilities for handling XML,
so
> >it would probably be a very good choice for the filter language. (Most
XML
> >developers are very enthusiastic about using XSLT for filtering, but XSLT
is
> >very poor at character conversion, and has a number of other
shortcomings.)
> >
> >There are several advantages to using the XML2Lout approach:
> >
> >* Much quicker and easier to implement than to write a decent
> >  Lout editor.
> >
> >* It would be very easy to update the "XLout" DTD and XML2Lout
> >  filter when Lout is updated, a lot easier than
> >  updating a Lout editor. (A well designed DTD and filter would
> >  make it possible to add new commands to the DTD and have them
> >  correctly converted without changing the filter at all.
> >  Extending the editor functionality would then be a matter of
> >  updating the DTD only. Even non-programmers can learn how to
> >  do this fairly quickly.)
> >
> >* An entire range of editors would become available, from
> >  free editors like Emacs to commercial products like XMetaL,
> >  WordPerfect and ArborText Publisher, to name a few.
> >
> >* Other XML processing tools, like databases, translation tools
> >  and browsers would be available for use.
> >
> >* It would be easy to write filters that transform other kinds
> >  of XML documents to "XLout". This would make it possible to
> >  write documents that are usable in other contexts than print
> >  publishing, and still use Lout when printing.
> >
> >* It would be possible to use sophisticated linking technologies,
> >  like XLinks and Topic Maps. (An XLink-based topic Map framework
> >  for XML is under development.)
> >
> >
> >/Henrik