OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: DOCBOOK-APPS: LyX 1.2 for DocBook



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.

Attachment: test.sgml
Description: generated docbook

Title: LyX 1.2 for DocBook

LyX 1.2 for DocBook

Gary Murphy

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.


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 yo! u 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 formating

navigating by tabs

lets you define tables by specifying the rows and cols and then moving around inside them to add your text, but the control-enter is no longer a forced break.

so it seems

tables are

modal

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 ha! s 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.


-- 
Gary Lawrence Murphy <garym@teledyn.com> TeleDynamics Communications Inc
Business Innovations Through Open Source Systems: http://www.teledyn.com
"Computers are useless.  They can only give you answers."(Pablo Picasso)



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC