Show Posts
1
Suggestions and Requests / Re: DocBook support in Enterprise Architect
« 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:
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:
By copying and pasting the above into the scenario text area, instead of the more convenient
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?
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 likeCode: [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 withCode: [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?
