Re: Docbook notes

Jean Jordaan wrote:

> > Well, these alternatives still require editing text in some kind of
> > special format that makes you look in the docs about the detailed
> > syntax.  None of them is WYSIWYG.
> 
> The problem is that WYS isn't WYG either ... Where *you* see two 
> headings, *Word* might see one Heading style line, and one Paragraph, 
> font size 16, font weight bold. Both look exactly the same, they're 
> meant to convey the same meaning, but they're different for 
> processing purposes. 

It's not difficult at all to use WYSIWYG in the correct way.  Just use
paragraphs with a meaningful style and use text properties like
"userinput" instead of italic.

The problem is, of course, that such a program does not appear to exist.
Even though it would be perfectly possible to create it (Oce was
creating it while I was working there, but it never hit the market).

Nevertheless, quite often you just want to make text bold and not worry
about how to name that kind of text.  Or add a line break without
starting a new paragraph (haven't figured out how to do that yet in
docbook).  Sometimes it's just the layout that matters.

> Would you regard Vim's helpfiles as requiring editing in some kind
> of special format? I certainly would, but I find the format very
> helpful and worthwhile to master, and not that exacting.

True, but it's a format that is nearly impossible to convert to HTML or
PDF, except by taking the text as-is, without reformatting.  And a
monospaced font needs to be used, otherwise columns of text are messed
up.

> Both StructuredText and reStructuredText look very like plain text,
> just with certain conventions, not more complicated than the helpfile
> format. 

Problem with these formats is it's even more difficult to mark pieces of
text to be a specific kind.  E.g., to specify that certain columns of
text are part of a table.  Especially something like:

	item1       this is a wrapped       default value
	            line explaining
		    item1 in detail
 	item2       something like that     another value

> Compare this:
>  http://docutils.sourceforge.net/spec/pep-0258.html
> and this, the reStructuredText source:
>  http://docutils.sourceforge.net/spec/pep-0258.txt
> 
> Does that txt look like a pain to write to you?

Sure, looks quite nice.  But what's the point?  It's not what works,
it's what _not_ works what matters.  I don't see a table in this
example.  Can reStructuredText do nested tables?  I need that.

I might sound a bit frustrated, it appears too difficult to find good
documentation tools that are easy to use.  Perhaps it's my next
project...

> > Using a restricted set of the docbook macros doesn't make it 
> > much simpler.
> 
> The restricted set of tags does reduce the size of the reference 
> you need to be familiar with. 

Hmm, I am currently familiar with a restricted set, but it may grow any
moment.  Why limit the growth?  If you add some new tag it's easy to
lookup what it does.  It's the other way around that's complicated:
wanting to add text in a certain structure and not knowing what tags to
use.

-- 
If they don't keep on exercising their lips, he thought, their brains
start working.
		-- Douglas Adams, "The Hitchhiker's Guide to the Galaxy"

 /// Bram Moolenaar -- [email protected] -- http://www.Moolenaar.net   \\\
///          Creator of Vim - Vi IMproved -- http://www.Vim.org          \\\
\\\              Project leader for A-A-P -- http://www.A-A-P.org        ///
 \\\  Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html  ///


-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100003ave/direct;at.aspnet_072303_01/01