Re: How do people do this?

[Tabatha Persad <tabatha3 attbi com>]

On Thu, 2002-09-26 at 09:56, Telsa Gwynne wrote:
> On Fri, Sep 20, 2002 at 03:09:31PM +1000 or thereabouts, Malcolm Tredinnick wrote:
> > 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.
> 
> If it's short or similar to something I've done before, I have 
> an idea of how to structure it in my head. If it's longer or
> different, I do as my teachers always told me to do in exams:
> "write an essay plan first". And draw lots of lines and big
> number 1, 2, 3 marks over what should come where. Until I
> have an idea of the structure.

I absolutely love your approach for this, Tesla.  I agree.  I start with
just a plain text file, and start making my own "TOC" - Once I can agree
with the voices in my head that the order is correct, it's usually
fairly easy to stay on topic as I write each section.  I think the
toughest part is getting things in the right order.

> I have a series of files in a directory called Templates. They
> have names like artheader.sgml and orderedlist.sgml and so on,
> so you can guess that they are empty skeletons.

That's an excellent idea too.  The LDP (see my signature for their web
site), has sample templates for books and articles using DocBook.  A
Google search on "sgml templates" can usually return some good samples
of basic markup of a book or article.

> I whack the artheader.sgml (yeah, needs fixing in its name and
> some content) into my new file, fill it in, and then just continue
> writing and marking up as I go.

As with the book or article templates, once the required basic tags are
in, it's easy to add sections or chapters and move them around.  

> Because I don't know how to do this in joe and because joe and
> gnome-terminal have cut and paste issues, I am trying to teach
> myself vim: there are many more people who use vim macros than
> there are people who write joe macros so I hope to steal madly.

I'll always be an Emacs/Xemacs fan.  It reminds me of my productive DOS
days.

> This rather clunky process imposes structure on my rather 
> unstructured thoughts. If it's just not going well, I stop 
> and work out what I'm actually trying to say. At that stage 
> I start scribbling notes on index cards and shuffling them 
> around on a table to see what is the most logical structure

Absolutely wonderful way to organize structure!  I find I've gotten to a
point where I can simply do it within Emacs.  I create the basic
required markup for my sgml/xml, and then do a text version of my TOC
(bulleted or numbered). When I feel the TOC is in the right order, I
start marking them up as sections, and remove the bullets or numbers,
since the TOC handles that.  Even though I may not have text in a
particular section, I can still create the markup for the chapter and
title and throw in some closing tags, now can't I!  The sections are
easy to cut and paste and move around, even if they just contain titles,
and the TOC tags always handle the numbering for you.  I love it.

> I think some people do, actually. I quite enjoy mindless markup
> when I don't want to think too hard. Of course, your documents
> tend to make excursions into areas where I'd have to think :) 
> (Marking up C involves a lot of recourse to references and to
> any hacker I can grab :)) 

That's when you start looking too hard at your words and adding tags
that are really not required.  For example, if I am writing about an
application it is proper to use the application tag around its name. But
unless I was going to need a tally of that information for other
purposes such as indexing or other ambiguous things, it's not ultimately
going to make a difference in the appearance of the displayed text. See
how hard I can make things? hehehe

> > What do other people do? Does the final editing process just suck for
> > everybody, or am I missing some cool technique?
> 
> The final editing process sucks for me, sure. I loathe the last
> few steps, because they never _are_ the last few steps after all.

Have you ever had a thought in typing?  That is, have you heard a word
and then spelled it in your mind by picturing yourself type the word?  I
kind of got that way with DocBook.  Once I'm past my TOC and have
itemized any sub-sections, I write easily in markup.  The tags start
becoming familiar.  I think it's constant repetition, since I spend a
lot of time at the LDP.

And as luck would have it, I love editing as much as I love writing. How
weird is that? ;)

-- 
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)