Re: [Groff] Groff editor.

[Clarke Echols]

Ouch!  That's painful! :-)

One of my professors from about 33 years ago said, "Engineering
is the *art* of *knowing how* to avoid difficult issues."  The
years since have clearly demonstrated to me that those are very
astute words.

I use Windows 98 with Cygwin and the Ghostgum viewer which runs
Ghostscript.  When editing, I use two bash shell windows and the
Ghostgum window.  First window runs vim to edit the *.roff file.
Second window is for keyboard commands.  I have my own macros file
in the same directory with the *.roff file, and send the PostScript
to a file I call "j.ps" (because I'm lazy and one-letter filenames
work for displaying the file I'm working on.

I type:

groff macros workingfilename.roff >j.ps

Then I open the j.ps file in Ghostgum and leave Ghostgum running.

I edit the working file some more, then type ':w'

I pop up the second bash window, press the up-arrow key to get
the previous command, then press [Enter].  When groff is finished,
I pop up the Ghostgum window and Ghostgum updates automatically
because the file has changed.

Works for me.

It's not that I can't write a shell script -- I'm just too lazy
to do it and have to change it when I change to a different file
I'm editing.  When I change files, I just retype the groff command
line to a different *.roff file and I'm running again.

Nice thing about Unix/Linux.  There are always a zillion ways to
do the same thing.  For example, to create a zero-length file:

touch filename
cp /dev/null filename
cat /dev/null >filename

The key is to understand what commands do and how they work, then
find creative ways to chain them together.

Here's a teaser:

sh script
    script reads files in a directory, and for every file, executes
    the command line:
       vi $file < vi_script_file
           vi script file contains vi keyboard commands and ends
           with 'ZZ' or ':wq'
           One of the script lines is 1G!Gsed -f sed_script_file
              sed script file contains sed commands

This allows you to automatically edit every file in a directory
in the same way, then in the middle of it all, send the modified
file to sed to do some more streaming, automated work
(damage? ;-)), then bring it back to vi to finish the job.

I did several months of dreary laborious manual vi work on 1500-2000
files that way when working on the HP-UX man pages in 1989, and got
the job finished in less than 4 hours.  It took nearly all of that
time just to get the scripts right.  And that was on a computer with
a 20 MHz Motorola 68020 processor, not a 2 GHz Pentium or Athlon!
The actual editing took only a few minutes.

BTW, if you do this, keep a backup copy of the original files until
you know you don't need them anymore. :-)  This is a powerful
strategy and makes learning sed very worth the effort.  Just
remember that sed uses a "pattern space" that can contain multiple
lines separated by a '\n' sequence.  ^ represents start of pattern
space and $ represents end of the space, not end of line.  You
can load multiple lines into the space and search across line
endings by using '\n' in the regular expresssion.  Sed also supports
internal looping of script commands, making it quite powerful.

The reason I did it was to get those many hundreds of manual pages
so the troff coding looked like it had all been done by the same
person.  I also changed the headings at top of page from uppercase
to lowercase (the cp(1) manpage had CP(1) at the top, cp in bold
in the synopsis, and Cp in italics in the body of the text if Cp
was the first word in a sentence.  I changed the header to cp(1),
the bold to Courier in the SYNOPSIS, and cp in courier at the start
of sentences in the DESCRIPTION section.  Stirred a mighty fuss
because it was "different than AT&T style", but I won the war my
opponents were trying to wage against me. :-)

And people wonder why I'm not impressed by Word and other WYSIWYG
"editors". :-)  Try the equivalent of '5yy33Gp' using Word. :-)
[That's yank five lines, go to line 33 in the file, and put the
yanked lines back in following the new current cursor line (33).
The original text from which 5 lines were yanked remains untouched.
To move the lines, use 5dd instead of 5yy -- for those not familiar
with vi/vim.]

Clarke

(Ted Harding) wrote:
> On 20-Aug-07 15:54:06, Clarke Echols wrote:
> > The short answer is "no".  The groff source file has all of the
> > embedded coding to tell the formatter what to do with the file
> > when it reads and interprets it.  Microsoft Word, for example,
> > gives the user a formatted display of the results from its own
> > internal coding.  If the user changes something, Word updates its
> > source file but the user never sees that.  That's what makes Word
> > so popular -- the user doesn't see the hard work.
> >
> > It's also the problem with Word because the user has little
> > control over how Word does what the user thinks he or she wants
> > done.  If you want direct control, which I like, you have to know
> > how to instruct the formatter correctly.
> >
> > Someone else could take the file and edit it using a plain-text
> > editor -- not Word or Word Perfect, for example -- and make
> > changes, **provided** they don't monkey around with the formatter
> > coding in the file.
> >
> > When I work on books, I usually take possession of the source file
> > and from that point on, nobody else has access to the source unless
> > they know groff.  Not every organization is willing to do that.
> >
> > Clarke
>
> I agree with Clarke!
>
> It's unlikely that there could be a successful "WYSIWYG" editor
> for groff (where the user works on the displayed formatted output
> and the editor hiddenly modifies the groff source file), except
> possibly for the most basic groff content. This is partly because
> of the extensive use of macros, definitions, and other "specials"
> whih are characteristic of less basic groff usage.
>
> I have at times tried "WYSIWYG" editors for TeX -- Lyx (Open Source)
> and Scientific Word (proprietary). I've not been specially impressed
> with either -- and I suspect that this is due to the same sort of
> issue.
>
> I append below the skeleton of a Linux script I use myself for a
> kind of "delayed WYSISYG" editor for groff. You can amend it to
> suit your own needs.
>
> It works as follows, for producing a groff file myfile.tr and a
> formatted PostScript file myfile.ps (replace "myfile" with whatever
> you like).
>
> You will have 3 files going while it is running: myfile.tr and
> myfile.ps, plus a temporary file myfile.watch
>
> The script is called "ge", and there is also a symbolic link
>
>   ge_L -> ge
>
> Invoke the script with
>
>   ge myfile     [for Portrait orientation]
>   ge_L myfile   [for Landscape oreintation]
>
> If myfile.tr does not exist, then it is created and initiated
> with the two lines
>
> .ds DATE 20 August 2007     [or whatever the current data is]
> .\".ds DATE \*[grDATE]      [which you can uncomment to get the
>                              latest date when you revise]
>
> Then, if myfile.ps does not exist, it created with first line
>
> %!PS-Adobe-3.0
>
> (This is subsequently over-written by groff, but allows 'gv'
> to initially open the file as a PostScript file).
>
> Then, myfile.watch is 'touch'ed. Its purpose is to keep track,
> via its timestamp, of saves of the groff file myfile.tr being
> edited.
>
> Then 'gv' is opened to display myfile.ps
>
> Then an xterm is opened in which 'vim' is running with myfile.tr,
> in which this file can be edited.
>
> Then an auxiliary xterm is opened as a console in which you can
> access the system directly (e.g. to read other files in the same
> directory).
>
> Finally, a loop is entered.
>
> You edit the groff file in 'vim' as you wish. When you want to
> see the results, save the current version with ":w" in 'vim.
>
> The loop constantly checks whether the timestamp on myfile.tr
> is more recent than that of myfile.watch and, if it is, then
> groff is run on myfile.tr to generate myfile.ps, and then a
> 'kill -1' is sent to 'gv' so that it re-reads myfile.ps and
> displays the formatted version of the latest save. Then the
> file myfile.watch is again 'touh'ed.
>
> Also within the loop, the PID of 'gv' is monitored.
>
> You bring the whole thing to a finish by closing 'gv' (the
> quickest way is to type "q" when the 'gv' window has focus). 
>
> When the PID of 'gv' disappears, the auxiliary xterm is closed,
> and the temporary file myfile.watch is removed, and you are left
> with the xterm in which 'vim' is running. Just close this with
> ":q" in 'vim'. All done.
>
> I have no idea how to achieve anything similar if you are running
> groff on Windows.
>
> Hoping this helps. The 'ge' script is below.
> Ted.
>
> Script for 'ge' -- make this executable, and symlink 'ge_L' to it.
> =================================================================
> #! /bin/bash
> export gv_PID=$!
> export SCALEBASE="1"
> export trname="`dirname $1`/`basename $1 .tr`"
>
> ## Normal
> export GROFFge="groff -U"
> export MODEge="Portrait"
> export GEOMgv="978x754-0+0"
> export GEOMge="80x36+127+0"
>
> ## Landscape
> if [ "`basename $0`" = "ge_L" ] ; then
>   export GROFFge="groff -U -P-l -rPL=8.267 -rLL=9.693"
>   echo "Landscape Mode"
>   export MODEge="Landscape"
>   export GEOMgv="987x754-0+0"
>   export GEOMge="80x47+255+0"
> else
>   echo "Portrait Mode"
> fi
>
> touch $trname.tr
> touch $trname.watch
> touch $trname.ps
> export grDATE="`date +'%-d %B %Y'`"
>
> if [ ! -s $trname.tr ] ; then
>   echo -n ".ds DATE " > $trname.tr
>   date +'%-d %B %Y' >> $trname.tr
>   echo -n ".\\\".ds DATE \\*[grDATE]" >> $trname.tr
> fi
>
> if [ ! -s $trname.ps ] ; then
>   echo '%!PS-Adobe-3.0' > $trname.ps
> fi
>
> xterm -name "GE_aux" -title "GE_x_$trname" \
>    -geometry 80x36+0-0 &
> export AUX_ID=$!
> xterm -name "GE $trname.tr" -title "GE $trname.tr" \
>       -geometry $GEOMge -fn 10x20 \
>       -e vim $trname.tr &
> gv -scale 2 -scalebase $SCALEBASE -antialias -spartan \
>    -geometry $GEOMgv $trname.ps &
>
> export gvpid=$!
> echo $gvpid
> ps -ax | grep gv | grep -v grep
>
> while [ -n "`ps -ax |  grep -v grep | grep $gvpid`" ] ; do
>   if [ $trname.tr -nt $trname.watch ] ; then
>     touch $trname.watch
>     $GROFFge -Tps -dgrDATE="$grDATE" -tpe -mpreted -ms \
>       $trname.tr > $trname.ps
>     kill -1 $gv_PID
>   fi
> done
> rm $trname.watch
> kill -15 $AUX_ID
>
>
> --------------------------------------------------------------------
> E-Mail: (Ted Harding) <address@hidden>
> Fax-to-email: +44 (0)870 094 0861
> Date: 20-Aug-07                                       Time: 17:50:09
> ------------------------------ XFMail ------------------------------