Re: How do people do this?

[Pat Costello <Patrick Costello Sun COM>]

I use XMetaL to create xml documents. XMetaL is a commercial application, so I 
had to fork out some euros. The investment was largely worthwhile, as the 
application takes the worry out of tag insertion, and allows you to crank out 
content. There is also a validation tool with the application, although this 
does not preclude xmllint. 

Pat


> Delivered-To: gnome-doc-list gnome org
> To: gnome-doc-list gnome org
> Subject: How do people do this?
> Mail-Followup-To: gnome-doc-list gnome org
> Mime-Version: 1.0
> Content-Disposition: inline
> User-Agent: Mutt/1.2.5.1i
> X-BeenThere: gnome-doc-list gnome org
> X-Loop: gnome-doc-list gnome org
> X-Mailman-Version: 2.0.12
> List-Help: <mailto:gnome-doc-list-request gnome org?subject=help>
> List-Post: <mailto:gnome-doc-list gnome org>
> List-Subscribe: <http://mail.gnome.org/mailman/listinfo/gnome-doc-list>, 
<mailto:gnome-doc-list-request gnome org?subject=subscribe>
> List-Id: GNOME documentation issues <gnome-doc-list.gnome.org>
> List-Unsubscribe: <http://mail.gnome.org/mailman/listinfo/gnome-doc-list>, 
<mailto:gnome-doc-list-request gnome org?subject=unsubscribe>
> List-Archive: <http://mail.gnome.org/archives/gnome-doc-list/>
> 
> I am wondering how people approach writing their GNOME documents (and
> anything else they do involving Docbook style markup). This is more idle
> curiosity than anything else.
> 
> Currently, I am finding it most convenient to write my documents once in
> plain text and then, after correcting that draft, mark it up and then do
> another editing pass to correct any stylistic problems that result from
> the markup. Of course, the editing passes are usually multiple passes
> and even after publishing things I will notice places that need
> correction.
> 
> I have also tried doing the markup as I go along the first time (which I
> tend to do for short documents anyway), since I have a fairly hefty set
> of vim macros setup to make adding tags flow fairly naturally into my
> typing. This way feels a bit awkward, though (the macros aren't entirely
> natural constructs, since otherwise they would be triggered by normal
> typing of English), and I find that I often lose the thread of what I am
> trying to say whilst adding the tag soup.
> 
> However, the current technique is not perfect, either. The main problem
> I find is that I tend to write with a mental image of what bits will end
> up at what presntational level (sect1, sect2, tip, callout, etc) and
> sometimes that information gets lost between the plain text version and
> the markup phase.
> 
> Also, I find the markup phase to be mind-numbingly boring. Honestly, I
> would rather clean my apartment than markup documents sometimes and I
> suspect that this stops me writing more than I do (this is _not_ a quiet
> plea for help, since I don't think anybody would _enjoy_ doing the
> markup).
> 
> Looking at my behaviour lately (where I have been doing a lot of writing
> both for GNOME and for work), I seem to have developed some kind of
> simplistic markup language that is sort of Wiki-inspired or perhaps
> sub-consciously taken from the Python markup conventions. This just
> gives me a shorthand way of recording what tags I want to put around
> various things so that I remember when it's markup time.
> 
> What do other people do? Does the final editing process just suck for
> everybody, or am I missing some cool technique?
> 
> Malcolm
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list