FWD: Re: Programming / scripting languages in tech-writing

[Aahz <aahz -at- pythoncraft -dot- com>]

----- Forwarded message from Aahz <aahz -at- pythoncraft -dot- com> -----
Newsgroups: bit.listserv.techwr-l
Subject: Re: Programming / scripting languages in tech-writing
Date: 21 May 2002 17:56:25 -0400

Cedric sent me the following e-mail privately, but later said it was
fine for me to respond publicly:

On Fri, May 17, 2002, Cedric Simard wrote:
>
> What do you mean by "converting a simple structured-text document into XML"?
> 
> - Can you give me a definition for "simple structured-text"?

It's easier to give an example than to define.  Here's some simple
structured text:

    .slide
    @head Mutable Subtleties
    .bullet
    Lists embedded in tuples
    .code
    >>> a = (1, ['foo'], 's')
    >>> a[1] = {'foo': 'bar'}
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    TypeError: object doesn't support item assignment
    >>> a[1].append('bar')
    >>> a
    (1, ['foo', 'bar'], 's')
    .bullet
    Classes
    .indent
    Cannot force class immutable; it's an implied contract in code and
    documentation
    .spacer
    =height 10
    .indent
    More later in OOP section

Here's the XML output (created with a Python program I wrote):

    <slide title="Mutable Subtleties">
    <frame x="0" y="0" width="782" height="612">
    <para style="head">Mutable Subtleties</para>
    <para style="Bullet">Lists embedded in tuples</para>
    <prefmt style="code">&gt;&gt;&gt; a = (1, ['foo'], 's')
    &gt;&gt;&gt; a[1] = {'foo': 'bar'}
    Traceback (most recent call last):
      File "&lt;stdin&gt;", line 1, in ?
    TypeError: object doesn't support item assignment
    &gt;&gt;&gt; a[1].append('bar')
    &gt;&gt;&gt; a
    (1, ['foo', 'bar'], 's')</prefmt>
    <para style="Bullet">Classes</para>
    <para style="indent">Cannot force class immutable; it's an implied contract in code and
    documentation</para>
    <spacer height="10"/>
    <para style="indent">More later in OOP section
    </para>
    </frame>
    <frame x="0" y="5" width="787" height="25">
    <para style="Footer">35</para>
    </frame>
    </slide>

As I said earlier, this XML is then converted into PDF by a program I
downloaded from the Net.

> - Can you then give me more details about the working environment in
> which this takes place, and the benefit you get from doing this?

It's my personal working environment; I'm a freelance writer/trainer.
The key point is that it's much easier to enter and edit the structured
text compared to raw XML.  Obviously, I could use a WYSIWYG editor of
some kind, but that tends to be much less efficient for me than good ol'
vi.

> Another question is: How long do you think it does take to start
> writing interesting scripts in Python when you have no previous
> programming experience? For example, do you think you can start
> enjoying to play with it even if you only have 2 hours or so to give
> on week ends?

Oh, yes.  For experienced programmers, it usually takes a week or two to
become minimally proficient in Python (assuming less than full
intensity); if programming fits your brain, I'd guess it would take you
a couple of months to get to what I'd call "minimally proficient" at two
hours per weekend.  But you should be able to start using Python to
replace batch files within two or three weekends.

Here's a good starting point:

http://www.python.org/doc/Newbies.html

> Last question: Can you give me a list of applications you can use
> Python for... when you're a technical writer.

Hard to answer that, it's so general.  Basically any task you'd want to
automate would be suitable.  One trick that I didn't use in the above
example is the ability to include a reference to an external file.  This
guarantees that when I'm modifying a code example, the documentation
reflects the version I've been testing.
-- 
Aahz (aahz -at- pythoncraft -dot- com)           <*>         http://www.pythoncraft.com/

"In the end, outside of spy agencies, people are far too trusting and
willing to help."  --Ira Winkler
----- End forwarded message -----


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l

Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit http://www.raycomm.com/techwhirl/ for more resources and info.