Getting started: editors, direct rendering, which DTD?

[Ian S. Worthington]

Hi.

I'm looking to learn some more about DocBook.  I've done some reading at the
main site and followed up some of the links and am at the stage where I'm
getting more confused rather than less: I believe a lot of the information I'm
reading may be somewhat out of date.

I'm looking to author small technical documents, on a Windows platform: Am I
right in thinking XmlMind seems to be the editor of choice for this, even
though its Personal Edition is not free for commercial use? Are there any
alternatives I should be seriously considering?

My strong preference is to be able to render DocBook file directly in an up to
date IE browser, rather than build and upload to a website.  Is this a
feasible objective for small documents?  Should I be looking at the Simplified
DTD to do this rather than v4 or v5?  If so, can you suggest suitable XSL
transforms and CSS style sheets that would get me up to speed quickly?

Any guidance would be much appreciated.

Thanks,

ian
...


Ian S Worthington
 
...
 
http://isw.me.uk/
 

 
Dulce et decorum est pro patria mori, sed dulcius pro patria vivere, et
dulcissimus pro patria biber. Ergo, bibiamo pro salute patriae.







---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Dave Pawson]

Ian S. Worthington wrote:
> Hi.
>
> I'm looking to learn some more about DocBook.  I've done some reading at the
> main site and followed up some of the links and am at the stage where I'm
> getting more confused rather than less: I believe a lot of the information I'm
> reading may be somewhat out of date.

Depends where you're reading. Lots hasn't changed for some time,
in some cases it's only minor changes.
Ask with specifics.


>
> I'm looking to author small technical documents, on a Windows platform: Am I
> right in thinking XmlMind seems to be the editor of choice for this, even
> though its Personal Edition is not free for commercial use? Are there any
> alternatives I should be seriously considering?

Very personal choice.
Mine is emacs or oXygen. The latter commercial but will do what you
want. Edit and apply style within a package.
oXygen will work on windows or Linux.
I've not used XMLMind.



>
> My strong preference is to be able to render DocBook file directly in an up to
> date IE browser, rather than build and upload to a website.

The latter is usually the former with an ftp transfer, so no difference.
IE? No interest. Docbook XSLT produces valid HTML which will work in
all of todays browsers. A big benefit of choosing docbook!
You don't say, but perhaps imply, that you want to transform it in the
browser?
I'd suggest you become used to working docbook xml through to html on
disk, then just refresh the browser view of the html. Makes it easier
to see what's going on, and deal with any errors.


  Is this a
> feasible objective for small documents?
Very much so.. but it will also scale to quite large document sets too.



   Should I be looking at the Simplified
> DTD to do this rather than v4 or v5?

Your choice. v5 is ready for use, if you're happy working
with namespaces and relax NG. v4.5 is stable.


  If so, can you suggest suitable XSL
> transforms and CSS style sheets that would get me up to speed quickly?

Again your choice.
I find Saxon (saxonica.com) good as an XSLT engine, though Xalan
is possibly used just as much (if you're a java user).
Others are available.
CSS? Less sure. Decide how you want your html decorating
then take a look at customization and how to get your CSS
linked into the chain.

For that I'd heartily recommend
http://www.sagehill.net/book-description.html

hth




--
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Ian S. Worthington]

Many thanks for your reply.

Thank you for your forbearance: my wording was indeed incorrect.  I wish to
*transform* the documents in the reader's browser, if this is at all possible.
 If that means using a simpler document model, that's likely to be fine.

I've started using XMLMind for now writing a simple document using DocBook 5.


As per the wiki, I've installed the EDE tools to test it, but they don't seem
to like DocBook 5, complaining about an missing DTD.  I don't know if XMLMInd
should have placed a DTD or EDE should work without it for v5.  The forum says
I need to upgrade the stylesheets to get v5 to work but docbook.sourceforge
has several different version and I have no idea which to choose, if indeed
any of them will satisfy my requirement for in-browser transformation.

If all this gives you the indication I have no idea where to go, that would be
about right!

All suggestions appreciated.

ian

------ Original Message ------
Received: Sun, 14 Oct 2007 11:46:30 AM BST
From: Dave Pawson <davep@...>
To: "Ian S. Worthington" <ianworthington@...>Cc:
docbook@...
Subject: Re: [docbook] Getting started: editors, direct rendering, which DTD?


> Ian S. Worthington wrote:
> > Hi.
> >
> > I'm looking to learn some more about DocBook.  I've done some reading at
the
> > main site and followed up some of the links and am at the stage where I'm
> > getting more confused rather than less: I believe a lot of the information
I'm
> > reading may be somewhat out of date.
>
> Depends where you're reading. Lots hasn't changed for some time,
> in some cases it's only minor changes.
> Ask with specifics.
>
>
> >
> > I'm looking to author small technical documents, on a Windows platform: Am
I

> > right in thinking XmlMind seems to be the editor of choice for this, even
> > though its Personal Edition is not free for commercial use? Are there any
> > alternatives I should be seriously considering?
>
> Very personal choice.
> Mine is emacs or oXygen. The latter commercial but will do what you
> want. Edit and apply style within a package.
> oXygen will work on windows or Linux.
> I've not used XMLMind.
>
>
>
> >
> > My strong preference is to be able to render DocBook file directly in an

up to

> > date IE browser, rather than build and upload to a website.
>
> The latter is usually the former with an ftp transfer, so no difference.
> IE? No interest. Docbook XSLT produces valid HTML which will work in
> all of todays browsers. A big benefit of choosing docbook!
> You don't say, but perhaps imply, that you want to transform it in the
> browser?
> I'd suggest you become used to working docbook xml through to html on
> disk, then just refresh the browser view of the html. Makes it easier
> to see what's going on, and deal with any errors.
>
>
>   Is this a
> > feasible objective for small documents?
> Very much so.. but it will also scale to quite large document sets too.
>
>
>
>    Should I be looking at the Simplified
> > DTD to do this rather than v4 or v5?
>
> Your choice. v5 is ready for use, if you're happy working
> with namespaces and relax NG. v4.5 is stable.
>
>
>   If so, can you suggest suitable XSL
> > transforms and CSS style sheets that would get me up to speed quickly?
>
> Again your choice.
> I find Saxon (saxonica.com) good as an XSLT engine, though Xalan
> is possibly used just as much (if you're a java user).
> Others are available.
> CSS? Less sure. Decide how you want your html decorating
> then take a look at customization and how to get your CSS
> linked into the chain.
>
> For that I'd heartily recommend
> http://www.sagehill.net/book-description.html
>
> hth
>
>
>
>
> --
> Dave Pawson
> XSLT, XSL-FO and Docbook FAQ
> http://www.dpawson.co.uk
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Dave Pawson]

Ian S. Worthington wrote:
> Many thanks for your reply.
>
> Thank you for your forbearance: my wording was indeed incorrect.  I wish to
> *transform* the documents in the reader's browser, if this is at all possible.

Until you are used to docbook, xslt then I'd suggest you try
a command line based approach - it will reduce the frustration.



I've not heard of anyone using docbook with the ms xslt engine
so I don't know if it works or not.


regards




--
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[doobs]

On Monday 15 October 2007 16:47, Dave Pawson wrote:
> Ian S. Worthington wrote:
> > Many thanks for your reply.
> >
> > Thank you for your forbearance: my wording was indeed incorrect.  I wish
> > to *transform* the documents in the reader's browser, if this is at all
> > possible.
>
> Until you are used to docbook, xslt then I'd suggest you try
> a command line based approach - it will reduce the frustration.

Umm, I don't know if this works for real, I was hoping to get around to
experimenting in the future, but I read someplace that
with a mixed content document structured as follows -

<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
          xmlns:xhtml="http://www.w3.org/1999/xhtml">

   ... main DocBook stuff ...
   ... followed by trailing xhtml script element ...
  <xhtml:script type="text/javascript" src="dbk2htmltrans.js" />
</book>

- potentially you could use javascript and the DOM model within the
browser to map the docbook into HTML and render it. I vaguely recall
that the script element had to be at the end, because it was executed
immediately after it was encountered, so otherwise the document
would not be entirely loaded.
If it actually works then possibly you could generate internal hyperlinks.

Truly a shot in the dark ...

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Dave Pawson]

doug wrote:

> On Monday 15 October 2007 16:47, Dave Pawson wrote:
>> Ian S. Worthington wrote:
>>> Many thanks for your reply.
>>>
>>> Thank you for your forbearance: my wording was indeed incorrect.  I wish
>>> to *transform* the documents in the reader's browser, if this is at all
>>> possible.
>> Until you are used to docbook, xslt then I'd suggest you try
>> a command line based approach - it will reduce the frustration.
>
> Umm, I don't know if this works for real, I was hoping to get around to
> experimenting in the future, but I read someplace that
> with a mixed content document structured as follows -
>
> <?xml version="1.0" encoding="UTF-8"?>
> <book version="5.0" xmlns="http://docbook.org/ns/docbook"
>           xmlns:xhtml="http://www.w3.org/1999/xhtml">
>
>    ... main DocBook stuff ...
>    ... followed by trailing xhtml script element ...
>   <xhtml:script type="text/javascript" src="dbk2htmltrans.js" />
> </book>
>
> - potentially you could use javascript and the DOM model within the
> browser to map the docbook into HTML and render it.

http://www.w3.org/TR/xml-stylesheet/

<?xml-stylesheet type="text/xsl" href="test.xsl"?>

Since the stylesheets are quite large, this could take quite a while


HTH




--
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Ian S. Worthington]

Thanks Dave.

Reducing the frustration sounds like a good plan: I'm getting nowhere with
this at the moment.

So, which of the stylesheets do I need to download to get v5 to work with EDE?
 

ian
...

------ Original Message ------
Received: Mon, 15 Oct 2007 07:47:32 AM BST
From: Dave Pawson <davep@...>
To: "Ian S. Worthington" <ianworthington@...>Cc:
docbook@...
Subject: Re: [docbook] Getting started: editors, direct rendering, which DTD?

> Ian S. Worthington wrote:
> > Many thanks for your reply.
> >
> > Thank you for your forbearance: my wording was indeed incorrect.  I wish
to
> > *transform* the documents in the reader's browser, if this is at all
possible.

>
> Until you are used to docbook, xslt then I'd suggest you try
> a command line based approach - it will reduce the frustration.
>
>
>
> I've not heard of anyone using docbook with the ms xslt engine
> so I don't know if it works or not.
>
>
> regards
>
>
>
>
> --
> Dave Pawson
> XSLT, XSL-FO and Docbook FAQ
> http://www.dpawson.co.uk
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Dave Pawson]

Ian S. Worthington wrote:
> Thanks Dave.
>
> Reducing the frustration sounds like a good plan: I'm getting nowhere with
> this at the moment.
>
> So, which of the stylesheets do I need to download to get v5 to work with EDE?

I don't know what EDE is.

If you want to transform v5 stylesheets into html,
http://www.docbook.org/docs/howto/ may be a good start.

http://docbook.sourceforge.net/snapshots/ will provide the xslt
stylesheets. pick either ns or not
http://docbook.sourceforge.net/snapshots/docbook-xsl-ns-snapshot.zip
is the namespaced one.

Pick up saxon (B ) from http://saxon.sourceforge.net/#F6.5.5
6.5.5 is the latest java based xslt 1.0 version.

I think it's tested with both Java 1.5 and 1.6.


Then come back with your next question(s).
I know it's not easy to get the whole thing together.


http://www.sagehill.net/docbookxsl/index.html is your friend.
Perhaps even buy a copy?


regards




--
Dave Pawson
XSLT, XSL-FO and Docbook FAQ
http://www.dpawson.co.uk


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[fmuhlenberg]

Ian S. Worthington wrote:

Any guidance would be much appreciated.

I'm relatively new to DocBook but I've managed to produce some documents (HTML/PDF) with images.

This book was of great help to me: http://www.sagehill.net/book-description.html.  I couldn't say enough good words about it as a reference.

In my environment, it was important to have a single package for installation. I found that the Velocity framework has a DocBook component http://velocity.apache.org/docbook/ and I started using it.  Twiking it to use 0.94 FOP and various docbook-xsl files was trivial.  

I prefer the command line for my document generations (that way I can include it with my builds).  Velocity fits this nicely with its Ant controlled build.

As for editors, I prefer simple text editors when dealing with markup languages.  I experimented with XmlMind but found it (personally) difficult to use.  It was a fine product but I found it easier to work lower in the weeds.

-Fred