DOCBOOK: LyX 1.2 for DocBook

[ also set to docbook-apps -- my apologies if the cross posting is
  inappropriate ]

LyX 1.2 for DocBook

Abstract

A  quick  5-minute  review  of using LyX 1.2 for DocBook authoring. Keep in
mind  this  is  not  meant  to  be  an  exhaustive review or be any sort of
evaluation  of  LyX  on  its own merits, this is only a quick review of LyX
with  regard  to editing DocBook articles in relation to the other free XML
editing tools such as XXE and Emacs psgml-mode.

[ I don't remember if this list allows attachments; if so, the generated
  DocBook will be attached, and if not, oh well ... ]

Table of Contents

First Impressions
First Commands
    Basic Markup
    Special effects
   
   
First DocBook
    Working with Structured Docs
    Printing DocBook
   
   
Conclusions

First Impressions

The first item that appears when trying to use the new experimental branch
of  the  LyX  word  processor  for  DocBook  is  the appearance of the same
familiar  LyX  interface;  it's  not  totally  obvious that this thing does
DocBook  at  all.  The import choices list the long defunct LinuxDoc, along
with  MsWord,  but  no  DocBook.  On closer examination, though, there is a
DocBook Article template option.

Selecting  that  option,  it's  still  not totally obvious. The filename is
still  a  .lyx  file.  Highlighting text with the intention to mark it as a
literal or some other DocBook tag is also not apparently obvious, and there
are no interface objects which are obvious as DocBook markup.

First Commands

The first thing that does work as expected is to select a new section. This
produces a proper section heading, numbered as one would expect.

Selecting a subsection, though, immediate makes the current paragraph into
a subsection heading rather than opening a new heading; LyX apparently does
not use a ??mark and select?? editing model, but instead uses the more
confusing ??set mode and proceed?? model.

The issue remains, than, of how to introduce docbook markup.

Basic Markup

Adding  basic  markup like subsections follows as the usual LyX sequence of
opening  a  new  line,  selecting  the mode, and continuing to type, with a
carriage  return  to  end  that mode and return to standard text. The other
buttons, on the other hand, follow a select/op mode where text can be
selected,  and  then the font changed via ! or the little man. The semantic
meanings of these markup elements is not explained.

Entering tags

This  part  is  pretty  elusive; I'm not going to go to the manual for this
because an interface should be self-revealing, but it expect this may be a
place  where  you  need  to  actually educate yourself as to the designer's
intentions.  Ditto  for  the  buttons  which,  being  xform  based, have no
tooltips  ---  it's  anyone's  guess  what  a  ! or a little man might mean
(unless you're an old-hand at LyX). The basic philosophy, then, is ??to do
this, you got to know how?? but I always wonder if it is then true that
since you had to learn something to use it anyway, why not simply learn the
markup?

There's another button marked ??font?? with an arrow below it, but clicking
this only fills the status line with ??(Changed) (font-free)?? ... whatever
that means.
   
 ∥ you do get itemized lists
   
 ∥ which repeat for each item
   
 ∥ until you back-space over the bullet
   

and  then  you  can't type the next paragraph until you enter a bullet item
and use the style-set to change it to standard. Most of the actions of the
interface will happen from the style-select box. and this has no concept of
what  is  valid  and  what  is not; you can insert any tag inside any other
regardless  of  the  legality  of  it within the current DTD. Many of these
options also have no real meaning for DocBook (such as ??paragraph?? which
changes  the  font  rather  than introducing a paragraph break or something
tangible like that).

I  do  see  GUI buttons in the stylesheet, but I've been unable to discover
how  to  add my own; IIRC, LyX lets you insert LaTeX commands inline in the
text,  and  I  expect the DocBook way is to use this facility to insert the
special elements.

Special effects

There  are  some special effects in the style menu which may be useful, but
it's  not  obvious  what  these do or how to use them; you just have to try
them and see,

Description
    this  appears  to be a description line which probably does the same as
    an itemized or enumerated list in creating a style that is
   
repeated
    for  subsequent  lines  and  continued  until  you enter a new line and
    switch it back to the standard markup.
   

If there are hotkeys for these mode changes, there is no indication in the
interface.
   
   
    you can always read the manual.

In addition to the style settings, LyX has a menu item caled ??insert??
which contains some special objects to put into the text.[1]to return from
these  objects,  you have to move the cursor outside of the bounding box on
the GUI display.a hyperlink insert is also a bit of a break from the flow;
my biggest complaint about this mode of working is that it upsets the flow
of the writing as you have to stop, fill out some sort of box (sometimes a
modal dialog, sometimes an inline box) and then jump out of it to return to
your  prior  mode.while  you do this in the flow of the text, the formating
given by LyX in the GUI display will become skewed as the new element will
be  inserted  inline  across  the  full  width  of  the page; with the note
attached to this paragraph, the line of text just prior to the note becomes
justified  to  show  only four words on the line equally spaced. This makes
proof-reading a little difficult; I can click on the ??note?? icon to
collapse it, but that also moves my cursor to the point before the icon, so
I  have  to re-navigate back to the end of the sentence to continue. Again,
there  may  be hotkeys for all this, and I do hope there are, but there are
no clues as to what keys these might be.[2]Arrow keys appear to get you out
of  the  boxes  if you happen to be at the end of the box text. Arrows will
also  freely  navigate  within these displayed inline boxes as if they were
part of the page.

見芋芋芋芋芋豕芋芋芋芋芋豕芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋角
芍  table   芍navigating芍lets  you  define  tables by specifying the rows芍
芍formating 芍 by tabs  芍and  cols  and then moving around inside them to芍
芍          芍          芍add  your  text,  but  the  control-enter  is no芍
芍          芍          芍             longer a forced break.             芍
豆芋芋芋芋芋走芋芋芋芋芋走芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋貝
芍so      it芍tables are芍                     modal                      芍
芍  seems   芍          芍                                                芍
谷芋芋芋芋芋赤芋芋芋芋芋赤芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋芋言

First DocBook

With  a  bit  of  experimentation,  it  seems LyX saves its document in its
native  format,  but offers an export function to save the current document
as  SGML  DocBook; selecting this option flashes a brief message to say the
file has been saved with the same name but with the .sgml suffix.

Working with Structured Docs

This  is  where  LyX  has  always  shined, and 1.2 does not disappoint: The
Navigate  menu  shows  the  structure  in an outline format allowing you to
quickly move from section to section.

Printing DocBook

Producing the printout proved to be painless; the SGML produced is a little
ugly  but  not  unworkable  (and  you  could  probably use tidy to fix it);
passing  the  exported  SGML  into xsltproc --html with the xsl-stylesheets
produced  this  file as a beautifully formatted HTML rendering of a DocBook
article.

Conclusions

For  those  who  like  LyX,  I think you're going to be very happy, but for
those  who  don't,  be prepared for some oddities and frustrations. This is
not  an  XML  editor,  it  isn't  a DocBook editor, it is a structured text
editor  that  just  happens to offer a DocBook export format (no idea if it
imports DocBook).

For my own use, I don't think I will switch from psgml-mode, but I may use
it  as  a  means  to  produce  simple  documents  or to rapidly flush out a
document  which  I will later massage with Emacs psgml-mode. Just from this
cursory  look  at  the interface, it is apparent you can customize a lot of
it,  for  example,  it  is preset with CUA keybinding which I expect can be
changed to VI or Emacs (although, again, if the user can do this, the user
could handle using Emacs in the first place).

足足足足足足

[1] this is a footnote to be inserted into the text stream

and it apparently continues regardless of paragraph breaks.

[2] For the menu items, LyX lets you use Alt-key sequences to first select
the  menu  item  by  the mnemonic letter, and then select the item. I don't
know if there are any such keystrokes to select styles.