Re: Rant: Giving up on XML

["Edgar D' Souza" <edgar -dot- b -dot- dsouza -at- gmail -dot- com>]

Interesting... I hit that same DocBook learning "vertical wall" as you
so picturesquely term it, quite some time ago. For now, DocBook has
been relegated to the back burner, with the hopes that I can attack
that wall again and surmount it.

Walsh and Muellner's book seems to be the definitive *reference* work
on it, but dang if there's some book somewhere which gives you a
gentle intro to DocBook, and a sort of conceptual "equivalency" chart
from Word/FrameMaker. Like: I can do callouts/drawing shapes and
annotations atop my screenshots in both Word and Frame; can I do
something similar in DocBook? If so, how? Or am I forced to embed
markup *inside* images? (Which may be good or un-good; the point is
that I've yet to find a definite answer on how to go about it!) There
are XML tags by the thousand, seemingly, in the DocBook reference;
those will probably be useful at a later stage of evolution. I'm still
in the primordial ooze of:
a) How to phrase my content in DocBook so I can achieve similar output
to that from Word or Frame (what subset of tags do I need to
concentrate on? Is there a good editor which abstracts away the need
to know and remember all of those tags, and which can be nested in
which, and what attributes are compulsory, and... aargh! :)

b) What toolchain to use. I did find this nice utility called
DocManager, which renders DocBook to (X)HTML, PDF and other outputs.
But I;ve been spoilt by "WYSIWYG" programs like Word and Frame, which
give you a rough idea of what your doc will look like in output
format; I have yet to find a half-decent editor for DocBook that does
something similar. Is it asking too much, that the editor apply the
*same* stylesheet to the display while I'm editing, as it will apply
when I'm finally compiling into PDF or other output?
I have installed and experimented with Mandriva Linux 2006 and 2007,
Fedora Core 5 and FC6, trying to just get the source of a project
called conglomerate to compile... sighhh... I'll tell you another
thing about Open-Source projects: for some reason, they seem into some
sort of arms-race about using the absolutely latest, bleeding-edge
versions of libraries. Versions that you probably won't see in
distributions for the next 6 months.. by which time the latest version
of the package you're trying to compile is already using an even newer
library...

There are times I feel like screaming :-) and I sympathise
whole-heartedly with your complaint.

BTW, if you're only looking for a book on _XML_, I own a copy of Erik
Ray's Learning XML, O'Reilly, and it does the job of telling you about
XML. More than *I* ever wanted to know, but hey... :-)
http://www.amazon.com/Learning-XML-Erik-T-Ray/dp/0596000464
(that was the first link from a Google search; dunno if it's a
commission-to-somebody link, you may want to hit Amazon and do your
own search if you're interested in the book).

Regards,
Ed.

On 3/13/07, siliconwriter -at- comcast -dot- net <siliconwriter -at- comcast -dot- net> wrote:
> After weeks of research, reading and studying, I'm throwing in the towel on XML. I was really hoping I could use DocBook to turn the output of our code documentation software into a manual, but no such luck. The output from our software (Doxygen) is so idiosyncratic, so impossible to tweak, that I've been unable to change the page size from A4 to US letter. I tried using DocBook, only to find that the learning curve is steep, undocumented and tricky. Doxygen uses LaTeX as its output engine, and a creakier, more poorly documented, unnecessarily complicated piece of software I have never seen.
>
> So I'm actually going back to MS Word. There are not enough words in English to say how much I loathe and despise Word, but I can't justify spending weeks and weeks more trying to figure out how all the puzzle pieces of XML, DTDs, XLSTs and other alphabet soup fit together. I'm not interested in becoming a programmer in order to do my job, which is writing manuals, not coding stylesheets. My company already sprang for InDesign (which bombed big time), so I have no hope of persuading them to go to Framemaker, which I don't want to do anyway. So, it's back to Word. *head desk*
>
> Until now, I was an eager devotee of open source software. I was trying to move all our documentation into OpenOffice and other open source software. Now, not so much. I no longer trust open source, I find it extremely poorly documented from an end-user point of view, and it never, ever has all the features I need. The learning curve resembles a vertical wall.
>
> If any of you fellow tech writers who actually UNDERSTANDS XML ever gets around to documenting it so that technically savvy but non-programmer audiences can understand and/or use it, I will be very grateful.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.