Author Topic: DocBook support in Enterprise Architect  (Read 5320 times)

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
DocBook support in Enterprise Architect
« on: November 18, 2004, 04:17:06 pm »
I am interested in a DocBook (SGML as well as XML) version of the automatic documentation. DocBook is the standard in technical documentation. You should also make it possible to export the Glossary in DocBook. DocBook has special glossary tags for this.

Have a look in

http://wiki.docbook.org/topic/

and the links presented there to learn more about DocBook. In one sentence, if you have the documentation in DocBook, you can create all other formats from it - HTML, PDF, PS, TXT, RTF.
Regards

Chris Karakas
http://www.karakas-online.de

mikewhit

  • EA User
  • **
  • Posts: 608
  • Karma: +0/-0
  • Accessing ....
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #1 on: November 19, 2004, 01:22:54 am »
 ;)This will be provided in the Turing Machine release of EA ;)

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #2 on: November 23, 2004, 02:39:13 pm »
Come on, does this really look so much rocket science to you?

Well, it's not:

Enclose each paragraph in <para> and </para> tags.

Enclose each section in <sect1> and </sect1> tags. Or <sect2> and </sect2> tags. Or <sect3> and </sect3> tags, depending on whether you have the equivalent of H1, H2  or H3 headings as in HTML.

Enclose each chapter in <chapter> and </chapter> tags.

Enclose a simple list in <itemizedlist> and </itemizedlist> tags. Then enclose each item in <listitem><para> and </listitem></para> tags.

A HTML link is enclosed as in: <ulink url="http://xxx.yyy.zzz/abc.html">Some link text</ulink>

Put some author info inside <authorinfo> tags, the title inside <title> tags, the revision in <revision> tags, and all this at the start of the document.

Enclose the whole document in <article> and </article> tags.

Prepend the DOCTYPE declaration:

<!DOCTYPE article  PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

and you have it! 8)
Regards

Chris Karakas
http://www.karakas-online.de

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #3 on: November 23, 2004, 02:45:53 pm »
Let me be even more positive: if you send me the template that generates a typical documentation document, I will create the DocBook equivalent for you. Then you will only have to echo the DocBook tags you will see in the template that I will send you back and you will have the DocBook export function already done!  ;)
Regards

Chris Karakas
http://www.karakas-online.de

Bruno.Cossi

  • EA User
  • **
  • Posts: 803
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #4 on: November 23, 2004, 02:57:12 pm »
Keeping up with the positive note :-) this sounds like a very simple modification of the HTML documentation templates, or really a creation of a new style of web documentation with some tags thrown it. Chris, have a look at creating your own Web Style Templates, it seems like it could do the trick.

Bruno

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #5 on: November 23, 2004, 06:59:25 pm »
Does docbook support imagemaps?
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #6 on: November 24, 2004, 09:30:40 am »
Contrary to my own expectations, YES it does!  :o

You write a file like the following, which has been taken from the conrtrib directory of the standard Norman Walsh stylesheets:

Code: [Select]

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter>
<?dbhtml filename="index.html">
<title>Test Chapter</title>

<para>First para</para>

<graphicco>
<areaspec id="clientsidemap">
  <area id="foo" otherunits="rect" coords="8,13,141,37" label="http://nwalsh.com/">
  <area id="bar" otherunits="rect" COORDS="165,16,282,37" linkends="sfoo">
  <area id="baz" otherunits="rect" COORDS="13,55,276,81" label="http://www.oasis-open.org/docbook/">
</areaspec>
<graphic fileref="testimg.jpg"></graphic>
</graphicco>

<para>Second para</para>

<sect1><title>test1</title>
<para>test1</para>
</sect1>
<sect1 id=sfoo><title>test2</title>
<para>test2</para>
</sect1>
<sect1 id=sbar><title>test3</title>
<para>test3</para>
</sect1>

</chapter>


The DocBook tag that does the job is <graphicco", which acts as a "graphic conteiner". A graphicco can contain an areaspec, which holds the actual information for the image map. See

http://www.docbook.org/tdg/en/html/graphicco.html

http://www.docbook.org/tdg/en/html/areaspec.html
Regards

Chris Karakas
http://www.karakas-online.de

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #7 on: November 24, 2004, 11:17:52 am »
Quote
Keeping up with the positive note :-) this sounds like a very simple modification of the HTML documentation templates, or really a creation of a new style of web documentation with some tags thrown it. Chris, have a look at creating your own Web Style Templates, it seems like it could do the trick.


I've had a look and indeed, this seems to be doable. I will try it and come back to report success or failure. Expect this to take a few weeks' time. Thanks for the tip Bruno!

In the meantime, someone please tell me how to export the DocBook template once I have finished it, so that others can import it.  ;)
Regards

Chris Karakas
http://www.karakas-online.de

Bruno.Cossi

  • EA User
  • **
  • Posts: 803
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #8 on: November 24, 2004, 12:30:38 pm »
Hi Chris,

try menu Tools > Export Reference Data :-)

Bruno

Kevin Brennan

  • EA User
  • **
  • Posts: 95
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #9 on: November 24, 2004, 02:22:36 pm »
But if it's that easy to produce a new XML format for the output from EA, shouldn't it be relatively straightforward to produce WordML or the XML forms used by OpenOffice/KOffice?
Sr. Consultant at blue sands Inc. and Vice President, Body of Knowledge at the IIBA. All opinions are my own.

karakas

  • EA Novice
  • *
  • Posts: 13
  • Karma: +0/-0
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #10 on: November 24, 2004, 04:43:00 pm »
The short answer: DocBook is the way to go in technical documentation, not WordML and not OpenOffice.org XML.

Some details and rumblings on this:

I guess yes, it shoulb be easy to use the Web Style Template mechanism to export to some XML dialect, or even to LyX, my favourite editor.

But there are surely pitfalls that I haven't encountered yet in my short  endeavour into this area:


  • How are images inserted into the documentation? DocBook (and LyX and OpenOffice.org and whatever else...) requires its own tags to be inserted at the right place, so that the image will appear there, when the document will be "rendered" by the DSSSL or XML stylesheet (or just displayed by LyX and OpenOffice.org). Is this possible?

  • What about pieces of text that have been entered as such into the text areas of various forms, e.g. use case scenarios? If those are inserted verbatim, as plain text without any markup, then the SGML (XML) parser will print an error - and in case of XML it will stop parsing altogether. This is because the content must be enclosed in structural markup, in the simplest case between a <para> and a closing </para>.

    Now suppose that I manage to achieve this with something like

    Code: [Select]

    <para>
    #CONTENT#
    </para>


    where #CONTENT# is supposed to hold the plain text of the use case scenario, requirement or some other pice of information. Then, even if the content of #CONTENT# is composed of more than one paragraphs, it will all be displayed as one paragraph during document rendering.

    Why? Because in DocBook when you need a paragraph you have to close the existing and open a new one with

    Code: [Select]

    </para>
    <para>


    Even worse, I guess that newline characters inside such text will have been  automatically replaced with <br> tags by EA already, before the "Web Template" comes into play for HTML (read DocBook) export.


Of course, I can write my use cases in LyX, then export them to DocBook, then open the SGML (XML) file in vi and make the text sit all on one line (eliminating separate lines with Shift+J), then cut and paste it into the text area of the scenario in the use case dialog of EA, then export the documentation to "HTML" using my custom "DocBook" Web Template and thus (hopefully) produce DocBook for the whole document...

By the way, this would bypass the numbering, aligning and whatever other presentational problems associated with free texts in EA. This is because, for example, the steps of a use case scenario will look something like the following in the DocBook text exported from LyX:

Code: [Select]

<orderedlist>
<listitem><para>Some step</para></listitem>
<listitem><para>Another step</para></listitem>
</orderedlist>


By copying and pasting the above into the scenario text area, instead of the more convenient

Code: [Select]

1. Some step
2. Another step


and by exporting to DocBook later, I should be able to get a fully marked DocBook document. The right numbering will then be produced automatically by the stylesheets and the renderer (Openjade and DSSSL stylesheets from Norman Walsh, in case of SGML, similar tools in case of XML).

Does this idea look promising, or will I have to translate all 52 elements of the Web Template to DocBook equivalents before I can try and get the answer myself?
« Last Edit: November 24, 2004, 04:44:37 pm by karakas »
Regards

Chris Karakas
http://www.karakas-online.de

monora

  • EA Novice
  • *
  • Posts: 2
  • Karma: +0/-0
  • I love YaBB 1G - SP1!
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #11 on: September 13, 2006, 03:49:29 am »
I am also interested in docbook generation from EA, because we are not satisfied with the buildin tools. Is there any progress in this area since 2004?

«Midnight»

  • EA Guru
  • *****
  • Posts: 5651
  • Karma: +0/-0
  • That nice Mister Grey
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #12 on: September 13, 2006, 05:18:28 am »
Not much, although some months ago there was lively discussion about XML support in general - rather than any particular 'dialect' such as DocBook. Try searching the forum for those threads.

I don't know if anyone has contributed anything to the wiki or EA UG. Perhaps if you generated enought interest both here (in this forum) and in those groups you could spark (no pun intended) something.
No, you can't have it!

Paolo F Cantoni

  • EA Guru
  • *****
  • Posts: 8001
  • Karma: +211/-127
  • Inconsistently correct systems DON'T EXIST!
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #13 on: September 13, 2006, 05:42:22 am »
Quote
... and in those groups you could spark (no pun intended) something.
Aw, Dave...

I much prefer intended puns!  
;D

Paolo
Inconsistently correct systems DON'T EXIST!
... Therefore, aim for consistency; in the expectation of achieving correctness....
-Semantica-
Helsinki Principle Rules!

«Midnight»

  • EA Guru
  • *****
  • Posts: 5651
  • Karma: +0/-0
  • That nice Mister Grey
    • View Profile
Re: DocBook support in Enterprise Architect
« Reply #14 on: September 13, 2006, 02:40:27 pm »
You saw right through my disclaimer, didn't you Paolo.
No, you can't have it!