[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] Re: Simplifying groff documentation
From: |
Michael(tm) Smith |
Subject: |
Re: [Groff] Re: Simplifying groff documentation |
Date: |
Thu, 4 Jan 2007 00:17:02 +0900 |
User-agent: |
Mutt/1.5.13 (2006-08-11) |
Zvezdan Petkovic <address@hidden>, 2006-12-23 15:06 -0500:
> I would classify myself as "skilled hands" too and I agree with your
> assessment of *roff and TeX (I used both extensively). However, I did
> write a 10 page technical document (34 with the appendices that simply
> include the files) in DocBook-XML. I have turned away in disgust and
> never looked back.
>
> I can be classified as "skilled hands" with both Vim and Emacs.
> I've made my own Vim filetype plugin to insert DocBook keywords easier.
I personally think it's a pretty bad idea to attempt to do any
extensive editing of DocBook (or most other forms of XML) in Vim.
I know there are people who do it, but I guess their pain
threshhold is a lot higher than mine.
I say that as someone who uses Vim exclusively for all my text
editing. Except for editing XML. (I do use Vim for doing touch-up
changes to XML documents, but not for any serious editing).
> Emacs (which I used to use for more than a decade) already has a DocBook
> support. Yet, I did not see them as an effective toolchain for a
> writer. I can't possibly imagine what could be an effective toolchain.
If you've not completely sworn off Emacs, you might want to try
nxml-mode for Emacs -- it's packaged for some distros and
downloable from here:
http://www.thaiopensource.com/nxml-mode/
It's the one thing I actually use Emacs for.
The difference between using that and using Vim to edit an XML
document is that nxml reads the actual DTD (actually, a RELAX NG
schema) for whatever document instance you're editing. So it can
give you context-sensitive completion for element and attribute
names -- and always flags, in real time, any parts of your
document that are not valid according to the schema you're using.
> One still has to select for each of these words whether they are
> command, filename, emphasis, acronym (over 100 possibilities in
> DocBook). The selection must be done through some sort of menu
> (remembering all 100+ possibilities couldn't be called comfortable I
> guess). And that is slow, very slow. It's also distracting from the
> writing. If I don't want to be distracted I could postpone the tagging
> for later. I'm afraid that then, I could simply omit a tag where I
> should have put it.
There are many other people that have tried it and run into the
same frustrations. Using a good editing application like nxml
helps a lot, but even then, for a lot of people, authoring their
source in DocBook is far from being their preferred means writing
up documentation. Though I like it just fine myself.
I'm not sure what could be done to make it easier. Any XML
vocabulary that gives you way to mark up a wide range of content
semantically rather than just presentationally is going to have
the same degree of complexity -- roughly the same number of
element and attribute names.
I know there are some mechanisms that allow you to use plain text
with simple Wiki-like markup, and generate DocBook output from
that. But the level of semantic markup they provide is really
limited.
--Mike