[Date Prev][Date Next][Subject Prev][Subject Next][
Date Index][
Subject Index]
Re: Re Leaving
- Subject: Re: Re Leaving
- From: "Robert Holmgren" holmgren@xxxxxxxx
- Date: Mon, 2 Feb 2004 14:37:40 -0500
** Reply to message from Patricia M Godfrey on Mon, 2 Feb
2004 10:51:55 -0500
Patricia:
> The problem is, ALL computer documentation is written
> backwards: it says, "These keystrokes [menus, commands] do thus and so."
> But what the end-user needs to know is "What keystroke [menu, command]
> should I use to do thus and so?" The XyWrite III manual came closest to
> doing that.
Our "manual", XYWWWEB.INF[ormation], basically is organized "To do thus and so,
use these commands". Thus and so *always* has a (pretty good, IMHO) denotative
name: e.g. ZIPView is a tool for viewing ZIPfiles. LFN retrieves the Long
File Name for any individual file; DIRLFN does the same for a whole DIRectory
(or FIND listing). Et cetera. We have a secondary Index, at top of INF, which
organizes the programs by task category (take a look! HELP CONTENTS).
I admit, it isn't as extensive as it could be. The "friendliness" of the
instructions varies considerably. But you know, read enough *nix MAN pages,
and you (or I anyway) are/am slowly persuaded of the virtue of that approach,
which we generally approximate. Be pithy, be precise, be complete, give an
example or two (optional), and get off the horn.
> I am NOT blaming the programmers; documentation writing is a
> different skill, requiring a different mindset. Very Big Corporations
> should realize that and hire real writers, but they don't. We cannot
> expect it of volunteers spending their own precious time...
Huh! OK, Patricia, just for fun, let's see _your_ example entry for ZIPView,
since you are a professional writer (and we, mere hacks -- notwithstanding our
years of text editing, books, articles, pleadings, supreme court briefs, and
insignificant what-not). (Just sticking it to you... smile!)
Incidentally, I mentioned ZIPView ONLY because I'd been working on it over the
weekend and it was on my mind. Here's the latest version of the program, and
the INF entry (which I have NOT "polished up" in response to your msg!).
ZIPView now is capable of inspecting ZIPs within ZIPs; and I also fixed a bug
of which I was unaware: if a constituent file within a ZIP had space chars in
the path or filename, ZIPView wasn't extracting it for reading, due to the
absence of quotes around the "path/file" (Fixed). Import this msg into
XyWrite, DECODE it, and replace the frames in INF and U2... Show us
what really good documentation looks like! In as few words as possible (INF is
already very big -- always a consideration for us). And BTW, don't try to Read
a file within a ZIP that is larger than XyWrite can handle, i.e. about 2.4Mb if
it is the ONLY window open. Nor EXEs or binaries, needless to say...)
My very best to you too!
R.
XPLeNCODE v2.0
b-gin [UNTITLED]
{ZIPView*,ZIPView,ZIPView/NV}[cr|lf][cr|lf]ZIPView R.J.Holmg
ren LastRev.2/1/04[cr|lf][cr|lf]View .ZIP directory in UNTITL
ED screen, then [optionally] Read constituent file. Long File
Name ZIPfiles and constituents may be viewed|read. ZIPs with
in ZIPs may also be viewed|read (New! in v117)[cr|lf][cr|lf]Z
IPVIEW/NV allows you to read more files from an already-open{032}
ZIPView dir display[cr|lf][cr|lf]Within a ZIPView display, mo
ve the cursor Up or Down to any position on the line that sum
marizes the constituent filename you wish to Read[cr|lf]If yo
u don't wish to Read any files but simply want to View the ZI
P directory, hit "Esc"ape after it displays (exit ZIPView but
retain the directory display)[cr|lf][cr|lf]{<}LBUV{>}REGistr
y Variable {<}MDSO{>}{<}LBLink{<}SV50,UnZip{>}[JM_]2.RegEdit/
N[Q2_]{>}UnZip{<}MDNM{>} must point to a fully-qualified file
spec, e.g. UnZip=C:\WINNT\UNZIP.EXE[cr|lf]Download [Un]Zip fo
r DOS from {<}MDSO{>}{<}LBLink{<}SV50,ftp.info-zip.org/pub/in
fozip/MSDOS/{>}[JM_]2.vu[Q2_]{>}ftp://ftp.info-zip.org/pub/in
fozip/MSDOS/{<}MDNM{>} (unz550x.exe and zip23x.zip)[cr|lf][cr
|lf]Commands:[cr|lf]1) ZIPVIEW ["][d:\path\]ZIPfilemask.zip|e
xe["][cr|lf]{tab}(defaults to current directory)[cr|
lf]{tab}Examples:[cr|lf] ZIPVIEW "e:\longdirname\longfile
name.zip"{tab}<== Single ZIPfile[cr|lf] ZIPVIEW f:\xy4\cu
rl*.zip{tab}<== Multiple ZIPfiles[cr|lf] ZIPVIEW d:\new\u
nz550x.exe{tab}<== Self-unZIPing EXEs[cr|lf]2) With cursor on
XyWrite DIRectory listing[cr|lf]{tab}*OR* with ZIPfilename D
eFined in text:[cr|lf] ZIPVIEW[cr|lf]3) With ZIPVi
ew DIRectory listing in current window:[cr|lf] ZIPVIEW [d:\
path\]ZIPfilename.zip[cr|lf]{tab}*OR*[cr|lf] ZIPVI
EW/NV[cr|lf]{<}FC{>}[cr|lf]Renumber ZIPVIEW in PACK{032}
mode[cr|lf]Default Save/Get Range=[;00|50] 01-09[cr|lf]OPTION
(1): FREEZE 50, 99[cr|lf]{<}FL{>}[cr|lf]-{tab}-{tab}-{tab}-{
tab}-{tab}-{tab}-{tab}-{tab}-{tab}-[cr|lf][cr|lf]{{;5ZIPView*
}} View{032}
ZIP directory in Untitled screen, then Read constituent file{032}
[ZIPVIEW/NV reads from already-open ZIP dir] RJH LastRev.1/3
1/04[cr|lf]{002}{<}SX01,@UPR({<}VA$FR{>}){>}{<}SX02,{<}CP{>}{
>}[BX_]es 1[Q2_][DX_]{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}IF{<}VA
$FI{>}=="[UNTITLED]"{>}[TF_][BX_]sea {252}Archive: {252}[Q2_
]{<}IF@NOT({<}ER{>}){>}{<}SV01,/NV{>}{<}GLA{>}{<}EI{>}[BX_]jm
p {<}PV02{>}[Q2_]{<}EI{>}{<}SX03,{<}IS50{>}{>}{<}IF{<}VA$WS{>
}>1&{<}VA|03{>}<1{>}{<}SX03,{<}VA$DR{>}{>}{<}EI{>}{<}IF{<}VA$
WS{>}==1&{<}VA|03{>}<1&{<}VA$DF{>}>0{>}[DZ_]{<}SV03{>}{<}EI{>
}{<}IF{<}VA|03{>}<1{>}{<}PRCommand: ZIPVIEW ["]ZIPfile.zip["]
*or* ZIPVIEW/NV{>}{<}EX{>}{<}EI{>}{<}EI{>}{<}IF"/NV"{238}{<}
IS01{>}>-1&{<}VA$FI{>}<>"[UNTITLED]"{>}{<}PRNo ZIP directory{
>}{<}EX{>}{<}LBA{>}{<}EI{>}{<}SX50,{<}VA$ED{>}{>}[JM_]2.GetPa
th[Q2_]{<}SX04,{<}IS50{>}{>}{<}IF"/NV"{238}{<}IS01{>}<0&":"{2
38}{<}VA@03{>}<0{>}{<}SX50,{<}VA$PA{>}{>}{<}IF{<}IS03{>}{240}
"\"{>}{<}SX50,{<}VA@50:1{>}{>}{<}SX03,{<}IS50{>}+":"+{<}IS03{
>}{>}{<}GLB{>}{<}EI{>}{<}SX03,{<}IS50{>}+"\"+{<}IS03{>}{>}{<}
LBB{>}{<}EI{>}{<}SV50,{>}[JM_]2.tmpfile/nv[Q2_]{<}SX05,{<}IS0
4{>}+"\"+{<}IS50{>}{>}{<}SV99,UnZip{>}[JM_]2.RegData/R[Q2_]{<
}SX06,{<}IS99{>}{>}{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}SU07,[BX_
]window n[Q2_]{<}IF{<}ER{>}{>}{<}PRNo Window{>}{<}EX1{>}{<}EI
{>}{>}{<}GT07{>}[BX_]dos/nv/x/z /c {<}PV06{>} -v {<}PV03{>} *
> {<}PV05{>}[Q2_]{<}SV08,{>}{<}LBC{>}[BX_]ne/100[Q2_][BX_]me
{<}PV05{>}[Q2_][BX_]wait[Q2_][BX_]ernv {<}PV05{>}[Q2_][CL_]{
<}IF{<}VA$FE{>}>0&{<}VA|08{>}<1{>}[JM_]2.cmline[Q2_][JM_]2.ab
/nv[Q2_][BC_]{<}PV616{>}{<}SX03,"File not found: "+{<}IS03{>}
{>}{<}PR@03{>}{<}EX{>}{<}EI{>}{<}SX02,0{>}{<}EI{>}[XP_][TF_][
BX_]sea/f {252} Name{252}[Q2_]
{<}SX50,{<}IS02{>}{>}{<}SX02,{<}VA$CY{>}+2{>}{<}SX09,{<}VA$CX
{>}+1{>}[JM_]2.ReJuMP[Q2_]{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}CU
D,02{>}[CD_]{<}LBD{>}{<}EI{>}[BX_]es 1[Q2_]{<}SV02,{>}{<}CUE,
09{>}{<}SX02,{<}IS02{>}+"[CR_]"{>}{<}LBE{>}[DO_][FF_]{<}PRPic
k file to view, then ["Esc" aborts]{>}{<}SX09,{<}RK{>}{>
}{<}SX01,{<}VA$KC{>}{>}{<}SX01,("|"+{<}IS01{>}+"|"){238}"|1|2
8|67|104|"{>}{<}IF{<}PV01{>}<0{>}{<}PV09{>}{<}GLE{>}{<}EI{>}{
<}IF{<}PV01{>}<1{>}{<}IF{<}VA|08{>}>0{>}[JM_]2.ab/nv[Q2_]{<}E
I{>}{<}PRAbort{>}{<}EX{>}{<}EI{>}[DX_][YD_][XD_][BX_]seb [wC
][Q2_][CR_]{<}PV02{>}[DF_][BX_]se/f [wC][Q2_][DF_]{<}SV01{>}
[XD_][BX_]seb [wC][Q2_][CR_]{<}SX50,{<}CP{>}{>}[BX_]seba {25
2}Archive: {252}[Q2_][BX_]sea {252}Archive: {252}[Q2_][DF_]
[BX_]se/f [wC][Q2_][DF_]{<}SV03{>}[XD_][JM_]2.ReJuMP[Q2_][DO
_][FF_][BX_]dos/nv/x/z /c {<}PV06{>} -p {<}PV03{>} "{<}PV01{>
}" >{<}PV05{>}[Q2_]{<}IF(@UPR({<}IS01{>})+"[255+252+142]"){24
0}".ZIP[255+252+142]"{>}{<}SV50,{>}[JM_]2.tmpfile/nv[Q2_]{<}S
X50,{<}IS04{>}+"\"+{<}IS50{>}{>}[BX_]dos/nv/x/z /c {<}PV06{>}
-v {<}PV05{>} >{<}PV50{>}[Q2_]{<}SX08,{<}IS05{>}{>}{<}SX05,{
<}IS50{>}{>}{<}GLC{>}{<}EI{>}{<}IF{<}VA|08{>}>0{>}[BX_]ernv {
<}PV08{>}[Q2_][JM_]2.ab/nv[Q2_]{<}EI{>}{<}GT07{>}{<}PRWorking
{>}[BX_]ne[Q2_][BX_]me {<}PV05{>}[Q2_][BX_]wait[Q2_][TF_]{<}S
X01,"ZIPView: Displaying "+{<}IS01{>}+" in "+{<}IS03{>}+"[cr|
lf][cr|lf]"{>}{<}GT01{>}[BX_]ernv {<}PV05{>}[Q2_][BX_]se [w
][wO][255+192+145][Q2_]{<}IF@NOT({<}ER{>}){>}{<}PR|Change all
lone CR|LF to CR+LF (carriage returns)? y|N{>}{<}SX01,{<}RC{
>}{>}[TF_]{<}IF"Yy"{240}{<}IS01{>}{>}[JM_]2.t1310[Q2_]{<}EI{>
}[CD_][CD_]{<}EI{>}{<}PRDone{>}{002}[cr|lf][cr|lf]
-nd
XPLeNCODE
XPLeNCODE v2.0
b-gin [UNTITLED]
{ZIPView*,ZIPView,ZIPView/NV}[cr|lf][cr|lf]ZIPView R.J.Holmg
ren LastRev.2/1/04[cr|lf][cr|lf]View .ZIP directory in UNTITL
ED screen, then [optionally] Read constituent file. Long File
Name ZIPfiles and constituents may be viewed|read. ZIPs with
in ZIPs may also be viewed|read (New! in v117)[cr|lf][cr|lf]Z
IPVIEW/NV allows you to read more files from an already-open{032}
ZIPView dir display[cr|lf][cr|lf]Within a ZIPView display, mo
ve the cursor Up or Down to any position on the line that sum
marizes the constituent filename you wish to Read[cr|lf]If yo
u don't wish to Read any files but simply want to View the ZI
P directory, hit "Esc"ape after it displays (exit ZIPView but
retain the directory display)[cr|lf][cr|lf]{<}LBUV{>}REGistr
y Variable {<}MDSO{>}{<}LBLink{<}SV50,UnZip{>}[JM_]2.RegEdit/
N[Q2_]{>}UnZip{<}MDNM{>} must point to a fully-qualified file
spec, e.g. UnZip=C:\WINNT\UNZIP.EXE[cr|lf]Download [Un]Zip fo
r DOS from {<}MDSO{>}{<}LBLink{<}SV50,ftp.info-zip.org/pub/in
fozip/MSDOS/{>}[JM_]2.vu[Q2_]{>}ftp://ftp.info-zip.org/pub/in
fozip/MSDOS/{<}MDNM{>} (unz550x.exe and zip23x.zip)[cr|lf][cr
|lf]Commands:[cr|lf]1) ZIPVIEW ["][d:\path\]ZIPfilemask.zip|e
xe["][cr|lf]{tab}(defaults to current directory)[cr|
lf]{tab}Examples:[cr|lf] ZIPVIEW "e:\longdirname\longfile
name.zip"{tab}<== Single ZIPfile[cr|lf] ZIPVIEW f:\xy4\cu
rl*.zip{tab}<== Multiple ZIPfiles[cr|lf] ZIPVIEW d:\new\u
nz550x.exe{tab}<== Self-unZIPing EXEs[cr|lf]2) With cursor on
XyWrite DIRectory listing[cr|lf]{tab}*OR* with ZIPfilename D
eFined in text:[cr|lf] ZIPVIEW[cr|lf]3) With ZIPVi
ew DIRectory listing in current window:[cr|lf] ZIPVIEW [d:\
path\]ZIPfilename.zip[cr|lf]{tab}*OR*[cr|lf] ZIPVI
EW/NV[cr|lf]{<}FC{>}[cr|lf]Renumber ZIPVIEW in PACK{032}
mode[cr|lf]Default Save/Get Range=[;00|50] 01-09[cr|lf]OPTION
(1): FREEZE 50, 99[cr|lf]{<}FL{>}[cr|lf]-{tab}-{tab}-{tab}-{
tab}-{tab}-{tab}-{tab}-{tab}-{tab}-[cr|lf][cr|lf]{{;5ZIPView*
}} View{032}
ZIP directory in Untitled screen, then Read constituent file{032}
[ZIPVIEW/NV reads from already-open ZIP dir] RJH LastRev.1/3
1/04[cr|lf]{002}{<}SX01,@UPR({<}VA$FR{>}){>}{<}SX02,{<}CP{>}{
>}[BX_]es 1[Q2_][DX_]{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}IF{<}VA
$FI{>}=="[UNTITLED]"{>}[TF_][BX_]sea {252}Archive: {252}[Q2_
]{<}IF@NOT({<}ER{>}){>}{<}SV01,/NV{>}{<}GLA{>}{<}EI{>}[BX_]jm
p {<}PV02{>}[Q2_]{<}EI{>}{<}SX03,{<}IS50{>}{>}{<}IF{<}VA$WS{>
}>1&{<}VA|03{>}<1{>}{<}SX03,{<}VA$DR{>}{>}{<}EI{>}{<}IF{<}VA$
WS{>}==1&{<}VA|03{>}<1&{<}VA$DF{>}>0{>}[DZ_]{<}SV03{>}{<}EI{>
}{<}IF{<}VA|03{>}<1{>}{<}PRCommand: ZIPVIEW ["]ZIPfile.zip["]
*or* ZIPVIEW/NV{>}{<}EX{>}{<}EI{>}{<}EI{>}{<}IF"/NV"{238}{<}
IS01{>}>-1&{<}VA$FI{>}<>"[UNTITLED]"{>}{<}PRNo ZIP directory{
>}{<}EX{>}{<}LBA{>}{<}EI{>}{<}SX50,{<}VA$ED{>}{>}[JM_]2.GetPa
th[Q2_]{<}SX04,{<}IS50{>}{>}{<}IF"/NV"{238}{<}IS01{>}<0&":"{2
38}{<}VA@03{>}<0{>}{<}SX50,{<}VA$PA{>}{>}{<}IF{<}IS03{>}{240}
"\"{>}{<}SX50,{<}VA@50:1{>}{>}{<}SX03,{<}IS50{>}+":"+{<}IS03{
>}{>}{<}GLB{>}{<}EI{>}{<}SX03,{<}IS50{>}+"\"+{<}IS03{>}{>}{<}
LBB{>}{<}EI{>}{<}SV50,{>}[JM_]2.tmpfile/nv[Q2_]{<}SX05,{<}IS0
4{>}+"\"+{<}IS50{>}{>}{<}SV99,UnZip{>}[JM_]2.RegData/R[Q2_]{<
}SX06,{<}IS99{>}{>}{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}SU07,[BX_
]window n[Q2_]{<}IF{<}ER{>}{>}{<}PRNo Window{>}{<}EX1{>}{<}EI
{>}{>}{<}GT07{>}[BX_]dos/nv/x/z /c {<}PV06{>} -v {<}PV03{>} *
> {<}PV05{>}[Q2_]{<}SV08,{>}{<}LBC{>}[BX_]ne/100[Q2_][BX_]me
{<}PV05{>}[Q2_][BX_]wait[Q2_][BX_]ernv {<}PV05{>}[Q2_][CL_]{
<}IF{<}VA$FE{>}>0&{<}VA|08{>}<1{>}[JM_]2.cmline[Q2_][JM_]2.ab
/nv[Q2_][BC_]{<}PV616{>}{<}SX03,"File not found: "+{<}IS03{>}
{>}{<}PR@03{>}{<}EX{>}{<}EI{>}{<}SX02,0{>}{<}EI{>}[XP_][TF_][
BX_]sea/f {252} Name{252}[Q2_]
{<}SX50,{<}IS02{>}{>}{<}SX02,{<}VA$CY{>}+2{>}{<}SX09,{<}VA$CX
{>}+1{>}[JM_]2.ReJuMP[Q2_]{<}IF"/NV"{238}{<}IS01{>}<0{>}{<}CU
D,02{>}[CD_]{<}LBD{>}{<}EI{>}[BX_]es 1[Q2_]{<}SV02,{>}{<}CUE,
09{>}{<}SX02,{<}IS02{>}+"[CR_]"{>}{<}LBE{>}[DO_][FF_]{<}PRPic
k file to view, then ["Esc" aborts]{>}{<}SX09,{<}RK{>}{>
}{<}SX01,{<}VA$KC{>}{>}{<}SX01,("|"+{<}IS01{>}+"|"){238}"|1|2
8|67|104|"{>}{<}IF{<}PV01{>}<0{>}{<}PV09{>}{<}GLE{>}{<}EI{>}{
<}IF{<}PV01{>}<1{>}{<}IF{<}VA|08{>}>0{>}[JM_]2.ab/nv[Q2_]{<}E
I{>}{<}PRAbort{>}{<}EX{>}{<}EI{>}[DX_][YD_][XD_][BX_]seb [wC
][Q2_][CR_]{<}PV02{>}[DF_][BX_]se/f [wC][Q2_][DF_]{<}SV01{>}
[XD_][BX_]seb [wC][Q2_][CR_]{<}SX50,{<}CP{>}{>}[BX_]seba {25
2}Archive: {252}[Q2_][BX_]sea {252}Archive: {252}[Q2_][DF_]
[BX_]se/f [wC][Q2_][DF_]{<}SV03{>}[XD_][JM_]2.ReJuMP[Q2_][DO
_][FF_][BX_]dos/nv/x/z /c {<}PV06{>} -p {<}PV03{>} "{<}PV01{>
}" >{<}PV05{>}[Q2_]{<}IF(@UPR({<}IS01{>})+"[255+252+142]"){24
0}".ZIP[255+252+142]"{>}{<}SV50,{>}[JM_]2.tmpfile/nv[Q2_]{<}S
X50,{<}IS04{>}+"\"+{<}IS50{>}{>}[BX_]dos/nv/x/z /c {<}PV06{>}
-v {<}PV05{>} >{<}PV50{>}[Q2_]{<}SX08,{<}IS05{>}{>}{<}SX05,{
<}IS50{>}{>}{<}GLC{>}{<}EI{>}{<}IF{<}VA|08{>}>0{>}[BX_]ernv {
<}PV08{>}[Q2_][JM_]2.ab/nv[Q2_]{<}EI{>}{<}GT07{>}{<}PRWorking
{>}[BX_]ne[Q2_][BX_]me {<}PV05{>}[Q2_][BX_]wait[Q2_][TF_]{<}S
X01,"ZIPView: Displaying "+{<}IS01{>}+" in "+{<}IS03{>}+"[cr|
lf][cr|lf]"{>}{<}GT01{>}[BX_]ernv {<}PV05{>}[Q2_][BX_]se [w
][wO][255+192+145][Q2_]{<}IF@NOT({<}ER{>}){>}{<}PR|Change all
lone CR|LF to CR+LF (carriage returns)? y|N{>}{<}SX01,{<}RC{
>}{>}[TF_]{<}IF"Yy"{240}{<}IS01{>}{>}[JM_]2.t1310[Q2_]{<}EI{>
}[CD_][CD_]{<}EI{>}{<}PRDone{>}{002}[cr|lf][cr|lf]
-nd
XPLeNCODE
-----------------------------
Robert Holmgren
holmgren@xxxxxxxx
-----------------------------