DocBook Editor

[Amy Stephen]

What is recommended (or what are folks using) for DocBook Editors?

http://www.docbook.org/docs/howto/#editors

Thanks!

[Andrew Eddie]

On 24 March 2012 04:59, Amy Stephen <amyst...@gmail.com> wrote:
> What is recommended (or what are folks using) for DocBook Editors?
>
> http://www.docbook.org/docs/howto/#editors

I use the XML Editor from xmlmind.com

In the save properties I set indentation to "2" and max line length to "130".

It's a bit quirky (well, that's docbook actually). I should probably
do an G+ hangout on it sometime.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers

[Chris Davenport]

At the risk of going off-topic, Amy's question reminded me of DITA and the DITAStorm editor.  This is something I was looking at some years back, when we were evaluating tools for producing the documentation and we eventually settled on using MediaWiki as the "source repository".  Back then, DITA was still quite young and there wasn't much in the way of tool support, but it was a seriously interesting project that I only reluctantly put on the back-burner to focus on building the documentation wiki.  The primary reason for not using it then was its relative immaturity and the difficulty that ordinary users would have in maintaining XML-based documentation.  The DITAStorm editor looked good, but it still had plenty of rough edges.

I had almost forgotten about it until Amy's question reminded me, so I've just had a quick peek at DITA again and it looks like the technology has come on leaps and bounds and could now be a serious contender for producing some of our standalone documents such as the Platform Manual, Administrators Manual and so on.

Some of the goodies available include XMLBuddy for editing DITA XML inside Eclipse (although any XML editor, including the native Eclipse XML editor could be used).  And the DITA Open Toolkit now also supports output in Eclipse Help format.  It would not be hard to grab wiki pages via the API and translate them into DITA topics either.

Definitely something worth further investigation IMHO.

Chris.

--
Chris Davenport
Joomla Leadership Team - Production Working Group
Joomla Documentation Coordinator

[Niels Braczek]

Am 24.03.2012 12:03, schrieb Chris Davenport:

> [DITA is] Definitely something worth further investigation IMHO.

Agree - I've worked with DITA a bit lately, and it seems to be a
superior document format, getting more and more support from many other
major projects/products. Online help, tutorials, manuals could all be
produced from the very same source. Be it as PDF, HTML, e-book or whatever.

Regards,
Niels

--
| http://barcamp-wk.de · 1. Barcamp Westküste 30./31. März 2012 |
| http://www.bsds.de · BSDS Braczek Software- und DatenSysteme |
| Webdesign · Webhosting · e-Commerce · Joomla! Content Management |
------------------------------------------------------------------

[Andrew Eddie]

What's the advantage of DITA over DocBook and are they significant
enough to warrant refactoring the existing files and tool chain?

[Amy Stephen]

First, thanks to all for your feedback.

Next, dumb question (I guess :-P ) but does it matter what tool you use? Shouldn't it output the same DocBook 5?

Asking because I am looking at Serna Free http://www.syntext.com/products/serna-free/ as I have not yet been able to download XMLeditor - keeps timing out. Seems nice, but if it's going to produce different output then I better not use it.

[Chris Davenport]

DocBook is more geared towards large monolithic "print" documents, whereas DITA is topic-orientated and more suitable for "online" formats such as HTML Help.  DITA is more closely aligned with the idea of single-source, modular documentation which promotes re-use of documentation "chunks" in different contexts and for different audiences.

There's a good introduction to DITA here: http://www.rockley.com/articles/The%20Rockley%20Group%20-%20DITA%20-%20What%20you%20need%20to%20know.pdf

I don't think it would take much effort to refactor the current Platform Manual at this stage in its development.  Not sure about how much work would be involved in switching tool chains.

Is it worth switching to DITA?  Yes, I think it probably is, although it rather depends on availability of labour.

Chris.

[Chris Davenport]

It doesn't matter which XML editor you use.  You simply load different DTD's depending on whether you are using DITA or DocBook.  You can even use a simple text editor if you're not bothered about real-time validation.

Chris.

[Niels Braczek]

Am 24.03.2012 22:27, schrieb Andrew Eddie:

> What's the advantage of DITA over DocBook and are they significant
> enough to warrant refactoring the existing files and tool chain?

Roughly said, DITA is topic oriented, while DocBook is document
oriented. Quote from Wikipedia[1]: "DITA content is created as small
topic items, rather than long books or chapters. A DITA map contains
links to topics, organized in the sequence (which may be hierarchical)
in which they are intended to appear in finished documents. A DITA map
defines the table of contents for deliverables. Relationship tables in
DITA maps can also specify which topics link to each other."

Taken from "DITA and DocBook: An Overview"[2]:
"*Concept topics* answer ″What is...″ questions. They include a
body-level element with a basic topic structure, including sections and
examples.
*Task topics* answer ″How do I?″ questions. They have a well-defined
structure that describes how to complete a procedure to accomplish a
specific goal.
*Reference topics* describe regular features of a subject or product,
such as commands in a programming language.
*Audience attribute*: The type, job, experience level, and other
characteristics of the reader for the topic. The audience element can
elaborate values used by audience attributes.
*Category element*: A classification of the topic content, equivalent to
both Dublin Core Coverage and Dublin Core Subject.

DITA's metadata attributes and elements can be used to create audience-
or subject-specific document subsets from a given document set."

Here are some comparisions:
- "DocBook versus DITA: Will the Real Standard Please Stand Up?"[3]
- "Modular Docs Part 2: DITA vs. DocBook"[4]

Both are from 2008. DITA has evolved a lot since then.

[1] http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
[2] http://www.criticism.com/dita/dita_docbook.html
[3] http://www.dclab.com/dita_docbook.asp
[4] https://blogs.oracle.com/coolstuff/entry/modular_docs_part_2_dita

HTH,

[Andrew Eddie]

On 25 March 2012 10:29, Chris Davenport <chris.d...@joomla.org> wrote:
> DocBook is more geared towards large monolithic "print" documents, whereas
> DITA is topic-orientated and more suitable for "online" formats such as HTML
> Help.

In that case I'd err on the side of DocBook because a realistic future
goal would be to get Pearson to run a print version and/or free
digital version.

[piotr_cz]

Another dumb question..
I'd like to update docs about JHttp class (part of my pull request
#1101). Sure, I could do it in any editor, but would prefer to have a
preview of how the docbook output looks like.
How do you guys do it? Is it possible without compiling to html/pdf (I
didn't succeed anyway) I'm reluctant to install full-blown editor like
XMLmind (I'd prefer some light viewer), but it seems like only way.


On Mar 26, 12:26 am, Andrew Eddie <mambob...@gmail.com> wrote:

> On 25 March 2012 10:29, Chris Davenport <chris.davenp...@joomla.org> wrote:
>
> > DocBook is more geared towards large monolithic "print" documents, whereas
> > DITA is topic-orientated and more suitable for "online" formats such as HTML
> > Help.
>
> In that case I'd err on the side of DocBook because a realistic future
> goal would be to get Pearson to run a print version and/or free
> digital version.
>
> Regards,

> Andrew Eddiehttp://learn.theartofjoomla.com- training videos for Joomla developers

[Andrew Eddie]

On 3 April 2012 06:01, piotr_cz <pkoni...@hotmail.com> wrote:
> Another dumb question..
> I'd like to update docs about JHttp class (part of my pull request
> #1101). Sure, I could do it in any editor, but would prefer to have a
> preview of how the docbook output looks like.
> How do you guys do it? Is it possible without compiling to html/pdf (I
> didn't succeed anyway) I'm reluctant to install full-blown editor like
> XMLmind (I'd prefer some light viewer), but it seems like only way.

The reality is you need a "full blown something" to render these sorts
of things. There are probably ways to load it in a browser given the
right XSL, but I'd say you'd waste a lot of time getting it to work.

And, by the way, I forgot to wire the HTTP package into the document
so hopefully you noticed that :)

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla developers