~ubuntu-branches/ubuntu/jaunty/edbrowse/jaunty-security : revision 7

1

<HTML>

2

3

<HEAD>

4

5

6

text based, command line, interactive,

7

editor, browser, mail client,

8

portable, C,

9

javascript,

10

secure, ssl,

11

blind, script, accessible">

12

<TITLE> edbrowse documentation </TITLE>

13

14

</HEAD>

15

16

17

<H2 align=center> edbrowse Documentation </H2>

18

19

<H3 align=center> <A NAME=top> Contents </A> </H3>

20

21

<H4> Chapter 1, Preface </H4>

22

23

<UL>

24

<LI><A HREF=#auth> Author </A>

25

<LI><A HREF=#copy> Copyright Notice </A>

26

<LI><A HREF=#ack> Acknowledgements </A>

27

<LI><A HREF=#over> Overview </A>

28

<LI><A HREF=#lang> Other Languages </A>

29

</UL>

30

31

<H4> Chapter 2, Quick Reference Guide </H4>

32

33

<UL>

34

<LI><A HREF=#guide> Quick Reference Guide </A>

35

<LI><A HREF=#tips> Tips for Avoiding Line Numbers </A>

36

<LI><A HREF=#mlist> Mailing List </A>

37

</UL>

38

39

<H4> Chapter 3, The Editor </H4>

40

41

<UL>

42

<LI><A HREF=#dev> Important Deviations From /bin/ed </A>

43

<LI><A HREF=#brace> Balancing Braces </A>

44

<LI><A HREF=#cx> Context Switch </A>

45

<LI><A HREF=#usage> Usage </A>

46

<LI><A HREF=#bin> Binary Characters </A>

47

<LI><A HREF=#bfile> Binary Files </A>

48

<LI><A HREF=#dir> Directory Scan, File Manager </A>

49

<LI><A HREF=#case> Upper/Lower Case </A>

50

<LI><A HREF=#bl> Break Line </A>

51

<LI><A HREF=#race> Race Conditions </A>

52

</UL>

53

54

<H4> Chapter 4, Web Browser </H4>

55

56

<UL>

57

<LI><A HREF=#url> Accessing A URL </A>

58

<LI><A HREF=#browse> Browse Mode </A>

59

<LI><A HREF=#math> Technical, Math </A>

60

<LI><A HREF=#title> Title, Description, Keywords </A>

61

<LI><A HREF=#rf> The Refresh Command </A>

62

<LI><A HREF=#hlink> Hyperlinks </A>

63

<LI><A HREF=#ilink> Internal Links </A>

64

65

<LI><A HREF=#move> The M Command </A>

66

<LI><A HREF=#music> Background Music </A>

67

<LI><A HREF=#input> Input Fields </A>

68

<LI><A HREF=#entry> Data Entry </A>

69

<LI><A HREF=#textarea> Text Areas </A>

70

<LI><A HREF=#button> Push The Button </A>

71

<LI><A HREF=#addr> Web And Email Addresses </A>

72

<LI><A HREF=#cook> Cookies </A>

73

<LI><A HREF=#ssl> Secure Connections </A>

74

<LI><A HREF=#ftp> FTP Retrievals </A>

75

<LI><A HREF=#proxy> Proxy Servers </A>

76

<LI><A HREF=#frame> Frames </A>

77

</UL>

78

79

<H4> Chapter 5, Javascript </H4>

80

81

<UL>

82

<LI><A HREF=#js> Introduction to Javascript </A>

83

<LI><A HREF=#valid> Validating and Modifying Forms </A>

84

<LI><A HREF=#popup> Popups and Popunders </A>

85

<LI><A HREF=#onc> Onchange and Undo </A>

86

</UL>

87

88

<H4> Chapter 6, Edbrowse Scripts and the Configuration File </H4>

89

90

<UL>

91

<LI><A HREF=#cfg> The Config File </A>

92

<LI><A HREF=#keyval> Keyword = Value </A>

93

<LI><A HREF=#agent> User Agent </A>

94

<LI><A HREF=#script> Edbrowse Functions </A>

95

<LI><A HREF=#init> The Init Script </A>

96

<LI><A HREF=#ma> Mail Accounts </A>

97

<LI><A HREF=#mt> Mime Descriptors </A>

98

<LI><A HREF=#sampcfg> A Sample Config File </A>

99

</UL>

100

101

<H4> Chapter 7, Mail Client </H4>

102

103

<UL>

104

105

<LI><A HREF=#smc> Send Mail Client </A>

106

<LI><A HREF=#fmc> Fetch Mail Client </A>

107

<LI><A HREF=#mailfmt> Formatted Mail </A>

108

<LI><A HREF=#filter> Mail Filtering </A>

109

</UL>

110

111

<H4> Chapter 8, Database Access </H4>

112

113

<UL>

114

<LI><A HREF=#sqlb> Building edbrowse with Database Access </A>

115

<LI><A HREF=#rtb> Reading Tables </A>

116

<LI><A HREF=#insupd> Insert, Update, Delete </A>

117

<LI><A HREF=#td> Table Descriptors </A>

118

</UL>

119

120

<H3 align=center> <A NAME=auth> Author </A> </H3>

121

122

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>Karl Dahlke

123

<A HREF=mailto:eklhad@comcast.net>eklhad@comcast.net</A>

124

248-524-1004 (during regular business hours)

125

</font></PRE>

126

127

<H3 align=center> <A NAME=copy> Copyright Notice </A> </H3>

128

129

This program is copyright (C) (C) Karl Dahlke, 2000-2007. 

130

It is made available by the author under the terms of the GNU General Public License (GPL),

131

as articulated by the Free Software Foundation. 

132

It may be used for any purpose, and redistributed, provided this copyright notice is included.

133

134

<P>

135

As a special exception, I hereby grant permission to link

136

the code of this program with the OpenSSL library

137

(or with modified versions of OpenSSL that use the same license as OpenSSL),

138

and distribute linked combinations including the two. 

139

You must obey the GNU General Public License in all respects

140

for all of the code used other than OpenSSL. 

141

If you modify this program, you may extend this exception to your version of the

142

program, but you are not obligated to do so. 

143

If you do not wish to do so, delete this exception statement from your version.

144

145

<H3 align=center> <A NAME=ack> Acknowledgements </A> </H3>

146

147

This program borrows some code and design concepts from the

148

149

links project</A>,

150

which is also freely available under the terms of the GPL. 

151

My thanks to the authors for all their hard work.

152

153

<P>

154

I would be dead in the water if it weren't for a cadres of excellent online tutorials. 

155

Their technical writing puts mine to shame. 

156

Please look through some of these web pages; you'll be glad you did.

157

158

<P>

159

160

Writing html

161

</A>

162

163

An html Code Tutorial

164

</A>

165

166

So You Want to Write some html...

167

</A>

168

169

Javascript for Webmasters

170

</A>

171

172

Javascript, the Definitive Guide

173

</A>

174

175

<P>

176

This package requires Spider Monkey Javascript, released by Mozilla under the MPL. 

177

You can

178

179

download it here</A>. 

180

Programmers and maintainers of this package should take advantage of the

181

182

online documentation</A>.

183

184

<H3 align=center> <A NAME=over> Overview </A> </H3>

185

186

This program is, at first glance, a reimplementation of /bin/ed. 

187

In fact you might issue a few ed commands and not realize that you are

188

actually running my program. 

189

But as you proceed

190

you will eventually discover some discrepancies,

191

areas where my program differs from ed. 

192

(These are discussed below.)

193

194

<P>

195

Reinventing ed <em>seems</em> like a complete waste of time,

196

until you realize that this program also acts as a browser -

197

a browser embedded inside ed. 

198

You can edit a URL as easily as a local file,

199

and activate browse mode to render the html tags

200

in a manner that is appropriate for a command-response program such as this. 

201

In other words, we discard most of the formatting information

202

and retain the links and fill-out forms. 

203

This allows blind users to access the Internet

204

via an application that is entirely compatible with the linear nature of speech or braille.

205

206

<P>

207

I find this approach superior to the "quick fix"

208

of pasting an adaptor onto a preexisting screen browser (lynx)

209

or graphical browser (Netscape). 

210

Of course that's just my opinion. 

211

To be fair, many blind users, even totally blind users, are satisfied with their auditory screen scrapers. 

212

I'm glad it works for them, but this approach frustrates the hell out of me. 

213

If you also prefer linear applications,

214

give this browser a try.

215

216

<P>

217

This documentation assumes you are familiar with ed. 

218

In fact it helps if you are fluent in ed. 

219

Experience with internet browsers and the associated terminology is also helpful.

220

221

<H3 align=center> <A NAME=lang> Other Languages </A> </H3>

222

223

The output and error messages have been "internationalized",

224

so that edbrowse can support most European languages. 

225

Set the environment variable LANG to interact with edbrowse in another language. 

226

Supported languages are shown below. 

227

If you can help in this effort, please let me know.

228

229

<P>

230

English: LANG=en (this is the default)

231

232

<P>

233

French: LANG=fr by

234

235

Erwin Bliesenick</A>

236

including <A HREF=edbdoc_fr.html>documentation</A>

237

238

<P>

239

Brazilian Portuguese: LANG=pt_br by

240

241

Cleverson</A>

242

243

<H3 align=center> <A NAME=guide> Quick Reference Guide </A> </H3>

244

245

Here are the ed and edbrowse commands, all in one place. 

246

This is a quick reference guide. 

247

Most of these commands will not make sense until you read the rest of the documentation.

248

249

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>q: quit the current session

250

qt: quit the program completely, whether you've written your files or not

251

!command: shell escape

252

p: print the current line

253

4,7p: print lines 4 through 7

254

'a,'bp: print a range of lines, marked with labels a and b

255

kb: mark the current line as b

256

l: list the current line, showing nonascii chars in hex

257

n: print the current line with its line number

258

=: print the number of lines in the file

259

z22: print the next 22 lines

260

X: make this the current line (a no-op)

261

s/x/y/: replace x with y on the current line

262

s/x/y/2: replace the second instance of x with y on the current line

263

4,7s/x/y/g: replace all instances of x with y, on lines 4 through 7

264

/x/: look for the line containing x

265

/x/i: look for the line containing x or X

266

ci: searches and substitutions are case insensitive

267

cs: searches and substitutions are case sensitive

268

sg: substitution strings are global across sessions

269

sl: substitution strings are local to their sessions

270

lc: convert line to lower case

271

mc: convert line to mixed case

272

uc: convert line to upper case

273

h: help, explain the last question mark

274

f: print the name of the current file

275

f foo: set the file name to foo

276

f/: retain only the lass component of the filename

277

e: print the number of the current session

278

e3: move to session 3

279

e foo: edit the file named foo

280

r foo: read the contents of foo into the current buffer

281

w foo: write the current buffer to foo

282

w+ foo: append to foo

283

w/: write to the lass component of the filename

284

d: delete the current line

285

1,$d: delete all the lines, 1 through eof

286

u: undo the last command

287

i: insert text before the current line, end with a period

288

c: change the current line, enter a new block of text, end with period

289

a: add text after the current line, end with a period

290

a+: include the line you just typed in, when you thought you were in append mode

291

4,7m11: move lines 4 through 7 to line 11

292

4,7t11: copy lines 4 through 7 to line 11

293

3,4j: join lines 3 and 4 together

294

3,4J: join lines 3 and 4 together with a space between

295

g/x/ p: print every line that has an x

296

v/x/ p: print every line that does not have an x

297

B: find the line with the balancing brace

298

b: brouse the current file, which is assumed to be in html

299

b foo.html: edit the file foo.html and browse it

300

b url: fetch url from the internet and browse it

301

ub: unbrowse a file

302

g: go to the link on the current line

303

g2: go to the second link on the current line

304

^: the back key, go back to the web page you were looking at before

305

i=xyz: set the input field on the current line to xyz

306

i2=xyz: set the second input field on the current line to xyz

307

i2*: push the second button on the current line, usually submit or reset

308

i3?: describe the third input field on the current line

309

db: set debug level [0-7]

310

cd: change directory

311

bl: break line into sentences and phrases

312

dr: directory is readonly

313

dw: directory is writable, and d moves files to your recycle bin

314

dx: directory is writable, and d deletes files

315

hf: show hidden files in directory listing (toggle)

316

bd: binary detection on files (toggle)

317

eo: end markers off

318

el: show end markers ^$ when a line is listed

319

ep: show end markers when a line is listed or printed

320

pb: play buffer

321

ft: show the title of the current web page

322

fd: show the description of the current web page

323

fk: show the keywords of the current web page

324

hr: http redirection (toggle)

325

js: allow javascript (toggle)

326

sr: send referrer (toggle)

327

tn: send dos-style newlines on lines in textareas (toggle)

328

fma: ftp mode active

329

fmp: ftp mode passive

330

fmd: ftp mode default, passive then active

331

rf: refresh the web page or directory listing

332

et: edit this web page as pure text

333

vs: verify ssl connections (toggle)

334

ip: show referenced ip numbers, usually for saved mail messages

335

sc: show columns

336

sm: send mail [account number]

337

</font></PRE>

338

339

<H3 align=center> <A NAME=tips> Tips for Avoiding Line Numbers </A> </H3>

340

341

If you're new to ed, you may find this program awkward. 

342

I often receive complaints about line numbers. 

343

People hate line numbers. 

344

They don't want to read the first page line by line,

345

1p 2p 3p 4p 5p etc. 

346

Well I hate line numbers too, and I never use them. 

347

Haven't for years.

348

349

<P>

350

If you just want to read the whole document, type ,p. 

351

That works, if you use a command line speech adapter. 

352

The whole document is in buffer, and you can read through it using the function keys on your adapter. 

353

Now I realize most people still use screen readers, so this won't work. 

354

Still, there's an easy way to step through screen by screen. 

355

Start with 1z20 to get the first 20 lines. 

356

Then the z command will give you the next 20, and the next 20, and so on. 

357

You may want to use 22, or 24, or whatever makes sense relative to your screen.

358

359

<P>

360

Another approach is to simply hit return, again and again, and proceed line by line. 

361

You may need to hit a function key to "read" each line,

362

after you hit return,

363

or maybe not, if your adapter has an autoread feature.

364

365

<P>

366

Once you are use to the regular expressions, you can jump to any part of the document,

367

even a large document, in record time simply by searching for a unique text fragment. 

368

This comes with practice. 

369

Sometimes I guess wrong, and my search string is not unique. 

370

I wind up somewhere else and have to search again. 

371

This doesn't happen very often. 

372

I usually get to the right place in one or two tries.

373

374

<P>

375

If you want to mark certain lines of text, please don't try to remember the line numbers. 

376

Use the k command to mark them. 

377

I usually use ka and kb to mark the start and end of a block of text,

378

while kc marks the new location. 

379

The move command is then 'a,'bm'c - with absolutely no line numbers. 

380

(This is standard ed fair, though most people never take advantage of it.)

381

382

<P>

383

To look for links on a web page, search for the right brace. 

384

Yes, you may stumble across a literal right brace in the text, but this doesn't happen very often. 

385

You might access a particular link by typing /{Next}/g. 

386

Similarly, you can look for input fields by searching for the greater than sign. 

387

(This will make sense as you read about the representation of web pages.) 

388

And of course, multiple operations can be scripted, a feature unique to this browser.

389

390

<P>

391

These are just some of the tips and tricks that will make you as fast and efficient as anybody using a screen editor or browser,

392

provided you are familiar with the page. 

393

(You will never be faster than your sighted colleague when traveling through unfamiliar territory,

394

no matter what system you use.) 

395

My wife is always amazed at how quickly I can negotiate websites,

396

or edit the common documents that we work on together.

397

398

<H3 align=center> <A NAME=mlist> Mailing List </A> </H3>

399

400

There is a mailing list for users of edbrowse and other command line utilities. 

401

You can join by sending mail to

402

403

commandline-subscribe@yahoogroups.com</A>.

404

405

<H3 align=center> <A NAME=dev> Important Deviations From /bin/ed </A> </H3>

406

407

Certain search/substitute commands may behave differently under this editor. 

408

This is because the regular expressions are interpreted

409

by the perl compatible regular expression (pcre) library,

410

rather than the traditional regexp library. 

411

Hence regular expressions have more features, and more power,

412

than the regular expressions employed by /bin/ed. 

413

The syntax is also somewhat different. 

414

For instance, perl uses bare parentheses where ed uses escaped braces --

415

to delimit sections of matched text. 

416

And perl uses $1 ... $9 to reference the matched substrings,

417

whereas ed uses \1 ... \9. 

418

Also, perl supports the i suffix, for case insensitive search,

419

along with the traditional g suffix for global substitute. 

420

There is no reason to describe all the nuances here. 

421

Please read the perlre man page `man perlre' for a full description

422

of regular expressions under perl. 

423

Once you are accustomed to their power and flexibility,

424

you'll never go back to ed.

425

426

<P>

427

Great! You've read the perlre man page, and you're back. 

428

Here are a few changes that I've made to perl regular expressions. 

429

I have found that ( and ) are almost always meant to be literal,

430

as in searching for myFunction(),

431

so I reverse the sense of escaped parentheses in perl. 

432

That is, ( and ) now match the literal characters,

433

and $ and $ are used to demark substrings of the matched text. 

434

These substrings are then referenced, in the replacement string, by $1 through $9. 

435

Similarly, | means a literal |, and \| is alternation. 

436

I also change the sense of &, on the right hand side,

437

to mean what it means in ed. 

438

I leave ^ $ . [ ] + * ? and {m,n} alone, to be interpreted by perl,

439

as described in the perlre man page. 

440

However, if * is the first character, it is treated as a literal star. 

441

This makes sense, as there is no previous character to modify. 

442

Some versions of ed do this, some don't. 

443

But I find it convenient; when I want to replace * + or ?, I don't have to escape it, just because it is a modifier. 

444

Similarly, an open bracket by itself is treated as literal. 

445

These changes to regexp, to look more like ed, may be confusing

446

if you are a perl expert. 

447

Sorry about that, but I think these changes make this

448

editor much easier to use for everyone,

449

especially the experienced ed users. 

450

Below are some additional differences between this program and /bin/ed.

451

452

<UL>

453

<P><LI>

454

Lines beginning with # are ignored, making it easier to comment your edbrowse scripts. 

455

The # character has no special significance in the middle of a line.

456

457

<P><LI>

458

Lines beginning with ! implement a shell escape. 

459

The ! character has no special significance in the middle of a line. 

460

The ! alone spawns an interactive subshell - type exit to return to edbrowse. 

461

The work "ok" is printed when the shell command is finished -

462

thus you can tell when a no-output command is done.

463

464

<P><LI>

465

Type `cd dirname' to change directories. 

466

The new directory is always printed. 

467

Type cd alone to find out where you are. 

468

I don't know what happens under dos

469

if you type cd f:/this/that, I never tested it.

470

471

<P>

472

Unlike bash, edbrowse does not retrace your steps back through symbolic links. 

473

Thus .. is always the physical parent directory.

474

475

<P>

476

environment variables are expanded before the cd command is applied, including the leading ~. 

477

Thuse cd ~/work takes you to the work directory under your home directory.

478

479

<P>

480

This command does not change any filenames that may be active. 

481

You can edit foo, cd .., and write,

482

and foo will be copied to the parent directory. 

483

That's probably not what you want, so be careful.

484

485

<P><LI>

486

r operates on the current line by default,

487

rather then the last line. 

488

Use $r to read a file at the end of your working text.

489

490

<P><LI>

491

The w+ command appends to the file. 

492

Some versions of ed use w> for this operation,

493

but for 40 years > has been the industry standard for write with truncate,

494

so using > for append is somewhat confusing. 

495

And w>> is just too clunky, so I use w+.

496

497

<P><LI>

498

w/ writes the data into a file whose name is the last component

499

of the current file name. 

500

This is useful when you've just downloaded this.that.com/foo/bar/package-2.7.7-22.tar.gz,

501

and you want to write the file locally, but don't want to retype the stuff at the end. 

502

Alternatively, f/ changes the filename, keeping only the last component.

503

504

<P><LI>

505

Whenever a file is read from or written to disk,

506

$var, in the filename, is replaced with the corresponding environment variable. 

507

Thus you can edit your address book at any time via `e $adbook',

508

provided $adbook has been set in your environment. 

509

Also, a leading ~/ is replaced with $HOME/,

510

making it easy to edit files in your home directory

511

such as ~/.profile.

512

513

<P>

514

Shell metta characters are also expanded, provided the result is one file name. 

515

You can read or write a file by typing a minimal portion of its name. 

516

Neither $variables nor stars are expanded for files on the command line,

517

as this expansion is already done by the Unix shell. 

518

Windows users should compile using the setargv.obj utility,

519

which performs wildcard expansion on command line arguments. 

520

Thus you should be able to edit *.c in any operating system

521

and get all the C source files in the current directory.

522

523

<P><LI>

524

Many versions of ed place a $ at the end of a listed line,

525

but this is not one of them, at least not by default. 

526

I use a linear speech adapter, rather than a screen reader,

527

so the embedded newlines tell me exactly where the line boundaries are. 

528

The extraneous $ character just gets in my way.

529

530

<P>

531

However, I realize most people still use screen readers,

532

where trailing whitespace is indistinguishable from the blank screen,

533

and a wrapped fragment is sometimes mistaken for a second line. 

534

Therefore, you can use the command `el' to place end markers around listed lines. 

535

Listed lines begin with ^ and end with $. 

536

Enter `ep' to place end markers around all printed lines. 

537

Use `eo' to turn end markers off.

538

539

<P><LI>

540

q quits without a warning message if the text

541

has never been associated with a file.

542

543

<P><LI>

544

Capital Q does not quit the editor absolutely. 

545

This is because I often hit caps lock by mistake,

546

or even shift q by mistake,

547

and if I've forgotten about some important changes that I've made,

548

those changes are gone! 

549

I know, this seems contrived, like it would never happen,

550

but it has happened to me many times,

551

so I disabled capital Q. 

552

Type qt to quit absolute.

553

554

<P><LI>

555

Capital J joins lines together with spaces between them.

556

557

<P><LI>

558

x (encryption) is not implemented.

559

560

<P><LI>

561

P (prompt) is not implemented.

562

563

<P><LI>

564

missing line numbers before or after the comma are assumed to be 1 and $. 

565

This is consistent with ,p -- to print the entire file.

566

567

<P><LI>

568

You cannot enter one command across two physical lines

569

by putting a backslash at the end of the first line. 

570

And there's no need to in any case, because perl supports \n translation. 

571

To split a line in the middle of the word doghouse, you would type

572

<br>

573

s/doghouse/dog-\nhouse/

574

575

<P><LI>

576

Only the first 500 characters of a line are displayed. 

577

The rest of the line is in the buffer, and can even be modified via a substitute command,

578

but if you want to see it, you will need to split it,

579

as in the doghouse example above.

580

581

<P><LI>

582

a+ adds text, like a, but also adds the line you last typed,

583

when you thought you were in append mode, but you weren't.

584

585

<P><LI>

586

This program is less tolerant of whitespace than /bin/ed.

587

<br>

588

57 , 63 p will not fly.

589

590

<P><LI>

591

A single % on the right hand side of a substitution is replaced with the last right hand side. 

592

Some versions of ed do this, some don't; I find it a convenient feature.

593

594

<P><LI>

595

s, is shorthand for s/, +/,\n

596

This is used to split lines at phrase boundaries. 

597

You can also use s. to split a line after the first period -- at a sentence boundary. 

598

s; s: s) and s" can also be used. 

599

s,3 splits the line after the third comma. 

600

You might need to use s.2 if the sentence begins with Mr. Flintstone.

601

602

<P><LI>

603

Type s by itself for s//%.

604

605

<P><LI>

606

The commands sg and sl make the remembered substitution and replacement strings global and local respectively. 

607

If you want to look at all instances of "foo" in all the files in the current directory,

608

and change some of them to bar at your discretion,

609

edit *, then enter sg to make substitution strings global to all edit sessions. 

610

In the first session, search for foo, and replace some of them with bar. 

611

Type e2 to move to the next session, whence you can search using slash alone,

612

because the string "foo" is applied to all sessions. 

613

Similarly, you can use % to refer to "bar". 

614

The sl command returns this editor to its local behavior,

615

where each file has its own search/replace strings.

616

617

<P><LI>

618

Errors associated with reading or writing files, or switching sessions,

619

are always printed. Other errors elicit the usual question mark,

620

whence you must type h to read the explanation. 

621

Type capital H if you always want to see the error messages.

622

623

<P><LI>

624

In most versions of ed, the command z7 means .,+6p,

625

making the current line +7. 

626

I think this is inconsistent, having one and only one ed command that leaves dot

627

somewhere other than the last line printed. 

628

The confusion is compounded when z prints the last lines in the file,

629

whence dot actually is the last line printed. 

630

So I have changed the z command slightly. 

631

In this program z7 means +,+7p,

632

and the current line becomes the last line printed, just like the other commands. 

633

Without a number, z prints the previous number of lines. 

634

Thus you can read your file a chunk or screen at a time.

635

636

</UL>

637

638

<P>

639

Subsequent sections describe

640

new and interesting features, completely foreign to ed. 

641

These include the simultaneous edit of multiple files

642

similar to emacs and vi,

643

and the ability to browse an html file and "edit" its fill-out form. 

644

That's why I wrote the program in the first place.

645

646

<H3 align=center> <A NAME=brace> Balancing Braces </A> </H3>

647

648

The capital B command is of interest to programmers,

649

and will probably not be used by casual home users. 

650

It locates the line with the balancing brace, parenthesis, or bracket. 

651

Consider the following code fragment.

652

653

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif><code> if(x == 3 &&

654

y == 7) {

655

printf("hello\n");

656

} else {

657

printf("world\n");

658

exit(1);

659

}

660

</code></font></PRE>

661

662

<P>

663

The capital B command, on either the second or the last line,

664

moves to the middle line "} else {",

665

because that balances the open brace. 

666

On the first line, B moves to the second line,

667

which balances the open parenthesis. 

668

The second line balances {, rather than ),

669

because braces have precedence over parentheses,

670

which have precedence over brackets. 

671

You can force a parenthesis match by typing B),

672

which moves from line 2 back to line 1.

673

674

<P>

675

The B command on the else line is ambiguous -

676

I don't know whether to look backwards or forwards. 

677

You must type B{ or B}.

678

679

<P>

680

You can explicitly balance <>, as in multiline html tags,

681

or `', used in some preprocessors such as m4.

682

683

<P>

684

Comments or literal strings that contain balancing punctuation marks will

685

definitely throw edbrowse off the track. 

686

If you are the author of the source,

687

you might want to avoid braces in comments,

688

or use comments to keep braces in balance.

689

690

<P>

691

static char openstring[] = "{block"; /* closing } is found elsewhere */

692

693

<H3 align=center> <A NAME=cx> Context Switch </A> </H3>

694

695

This program allows you to edit multiple files at the same time,

696

and transfer text between them. 

697

This is similar to the world of virtual terminals (Linux),

698

where you switch between sessions via alt-f1 through alt-f6. 

699

In this case you switch to a different editing session via the commands

700

e1 through e6. 

701

Note that `e 2' edits a file whose name is "2",

702

whereas `e2' (without the space) switches to session 2. 

703

Similarly, you can read the contents of session 3 into the current buffer

704

via r3, and you can write the current buffer into session 5 via w5. 

705

The latter command will produce a warning if session five already exists,

706

and you have made changes to its text, but have not saved those changes. 

707

In other words, you are about to lose your edits in session 5. 

708

Typing h will produce the explanation:

709

"Expecting `w' on session 5".

710

711

<P>

712

If you quit a session you are moved to the next valid editing session,

713

wrapping around to session 1 if necessary. 

714

The program exits when the last session quits.

715

716

<P>

717

Warning, the program contains a bug regarding the undo command. 

718

If you switch to another session, then switch back,

719

you cannot undo your last edit. 

720

You'd think this would be easy to fix,

721

but it is trickier than it seems, so I haven't gotten rround to it. 

722

I just wanted you to know. 

723

Make sure everything is copasetic before you switch to another session.

724

725

<P>

726

Let's run through a cut&paste example. 

727

You are editing file foo in session 1, and you realize

728

that a paragraph from file bar would fit perfectly right here. 

729

Here is how it might look. 

730

Lines beginning with < are the user's input,

731

and lines beginning with > form the program's responses. 

732

The # sign delimits my injected comments.

733

734

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>< e2 # switch to session 2

735

> new session

736

# Unlike ed, the r command does not establish a file name, even if the

737

# buffer is empty.

738

# Thus "r bar" is safer than "e bar".

739

# The text is not linked to the file bar,

740

# and we cannot accidentally corrupt this file.

741

# After all, we don't want to change bar, we just want to steal from it.

742

< r bar

743

> 28719

744

< /start/

745

> This is the start of the cool paragraph that you want to copy.

746

< 1,-d # don't need the stuff before it

747

< /end/

748

> This is the end of the cool paragraph that you want to copy.

749

< +,$d # don't need the stuff after it

750

< e1

751

> foo

752

< r2

753

> 3279 # size of text read from session 2

754

< q2 # clean house, get rid of session 2

755

< w # write foo, with the new paragraph included

756

> 62121

757

</font></PRE>

758

759

<P>

760

The following moves the data from one file to another.

761

762

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>< e2

763

> new session

764

< e bar # this time I'm going to change bar

765

> 28719

766

< /start/

767

> This is the start of the cool paragraph that you want to move.

768

< ka # mark the paragraph

769

< /end/

770

> This is the end of the cool paragraph that you want to copy.

771

< kb

772

< 'a,'bw3

773

> 3279

774

< 'a,'bd

775

< w # write bar, withouth the cool paragraph

776

> 25440

777

< q

778

> no file # now in session 3

779

< e1

780

> foo # back to session 1

781

< r3

782

> 3279

783

< q3 # quit session 3 remotely, while still in session 1

784

< w # write foo, with the new paragraph included

785

> 62121

786

</font></PRE>

787

788

<P>

789

An e command, by itself, tells you the current session, in case you've forgotten. 

790

This is similar to f, by itself, which tells you the current file.

791

792

<H3 align=center> <A NAME=usage> Usage </A> </H3>

793

794

type `edbrowse -h' to produce the usage message. 

795

You will see the -m option, used in several different ways. 

796

Try to ignore this for now. 

797

The -m option causes edbrowse to run as an interactive mail client,

798

rather than an editor. 

799

This will be discussed later.

800

801

<P>

802

The -dx option sets the debug level to x, where x is between 0 and 9. 

803

The default is -d1,

804

which prints the sizes of files as they are written and read. 

805

Some people like -d2, which prints the URLs

806

as you jump to new web pages or submit forms online. 

807

Unless you are debugging the program, you probably don't want to go any higher than -d3. 

808

On rare occasions you might want to set -d4, to see the http headers in and out. 

809

Remember, the debug level can be changed on the fly by using the dbx command (x between 0 and 9).

810

811

<P>

812

The -e option causes edbrowse to exit when it encounters an error. 

813

This is usually used by batch scripts. 

814

If there is a problem, you don't want to march on, executing the rest of the edbrowse commands.

815

816

<P>

817

Use -c to suppress processing of, and edit, the .ebrc configuration file. 

818

(This config file will be described later.) 

819

And why would you want to do this? 

820

Suppose you have made a change to this file,

821

and thereby produced a syntax error, so that edbrowse cannot even get started. 

822

Now you can't use edbrowse to fix your config file. 

823

Of course you could rename the config file to something else, fix it, and put it back;

824

but then you might discover another syntax error, and so on. 

825

Instead, use the -c option to edit the config file directly. 

826

It is automatically loaded into buffer 1. 

827

Note that -c must be the first option.

828

829

<P>

830

The arguments are the files to edit. 

831

Edbrowse reads these files into corresponding sessions,

832

and starts you off in session 1. 

833

If there are no arguments, you start in session 1,

834

but there is no text and no associated file.

835

836

<P>

837

If you like this program, and you want it to be your primary editor,

838

you can set the following Unix alias.

839

840

<P>

841

alias e="/usr/local/bin/edbrowse"

842

843

<P>

844

If you do this, you can use `e filename',

845

to edit a new file, whether you are inside edbrowse or at the shell prompt. 

846

Very convenient.

847

848

<H3 align=center> <A NAME=bin> Binary Characters </A> </H3>

849

850

At all times, even when entering a file name, this program scans its input

851

for binary codes. 

852

Sorry, but I like hex better than octal. 

853

I know it's not standard, but there it is. 

854

Use the three character sequence ~bd to enter the nonascii character 0xbd,

855

which is the code for 1/2. 

856

Similarly, if you list a line, with the l command, the 1/2 character

857

is displayed as ~bd. 

858

All nonascii and most control characters

859

are entered and displayed in this manner. 

860

Tab and newline must be entered directly from the keyboard. 

861

Tab and backspace are displayed as > and < respectively. 

862

If the following line is entered,

863

864

<P>

865

Hello~07 ~x is ~bd of y

866

867

<P>

868

And then listed, you will see the very same text,

869

but there is a bell and a 1/2 character inside. 

870

The ~x is not encoded into anything, because x is not a hex digit. 

871

If you want to force a ~, even though there are hex digits following,

872

use two tildes, ~~.

873

874

<P>

875

When you are entering a regular expression, you have the choice, hex or octal. 

876

This program converts ~xx, as a hex value,

877

and the perl regexp machinery converts \nnn, as octal. 

878

Thus any of the following will undos a file. 

879

The first is translated via my software, the second and third by perl regexp.

880

881

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>,s/~0d$//

882

,s/\15$//

883

,s/\r$//

884

</font></PRE>

885

886

<P>

887

Embedded escape characters are always displayed in hex,

888

whether the line is listed or not. 

889

Most terminals and terminal emulaters, including the Linux console

890

and my speech adapter,

891

interpret various escape sequences as control commands. 

892

Thus an errant escape sequence from a binary file could send your terminal or your speech adapter into an unexpected state,

893

making recovery difficult. 

894

It seems prudent to render escapes as visible characters all the time. 

895

If you have no idea where that ~1b came from, it's probably a literal escape character.

896

897

<P>

898

Returns and nulls are also converted into hex all the time. 

899

Thus an embedded return will not make one line look like two lines. 

900

You will usually see this when importing a dos text file. 

901

Every line ends in ~0d. 

902

Issue one of the three commands shown above to undos the file.

903

904

<H3 align=center> <A NAME=bfile> Binary Files </A> </H3>

905

906

Data is considered binary if it is sufficiently large

907

(more than 50 bytes)

908

and it contains a significant fraction of non-ascii or null characters (more than 25%). 

909

International text may contain scattered binary codes, for accented letters etc,

910

but most of the characters should still be ascii. 

911

Therefore binary data is not international text. 

912

In fact you probably won't be able to display or edit binary data effectively,

913

at least not by this program. 

914

But don't let that stop you. 

915

As an exercise, create an executable program that prints "hello world",

916

then edit the executable using this editor. 

917

Look for the string "hello world" and replace world with jorld. 

918

Write the file and run the executable. 

919

You should now see "hello jorld".

920

921

<P>

922

When binary data is first read into the buffer, you will see the words "binary data". 

923

After that the buffer remains "binary", even if you delete all the data and read in ascii text. 

924

You must use the `e' command to get a fresh, ascii buffer.

925

926

<P>

927

For the most part it doesn't really matter if the data is considered binary or ascii. 

928

Either way you can display and edit the data, and write it to a file.

929

930

<P>

931

This program tries to "do the right thing" under DOS/Windows. 

932

That is, it converts crlf to and from newline if it believes the file is text;

933

and it leaves binary data alone. 

934

These distinctions are not relevant on Unix/Linux.

935

936

<P>

937

Although this approach is satisfactory for English and most European languages,

938

it fails miserably for Asian languages, which definitely look like binary data. 

939

You can disable binary detection by entering the `bd' command. 

940

If you speak an Asian language,

941

you may want to put this command in your init script,

942

so edbrowse comes up the way you want -

943

treating your international files as text files.

944

945

<P>

946

If you speak an Asian language, and you are running Windows,

947

and binary detection is disabled,

948

<em>don't</em> use this program to manipulate binary files,

949

as they will get corrupted! 

950

Better still, say goodbye to Windows and start using a real operating system.

951

952

<H3 align=center> <A NAME=dir> Directory Scan, File Manager </A> </H3>

953

954

If you edit a directory

955

you will see a list of all the visible files in that directory,

956

in alphabetical order. 

957

(Use the `hf' option if you want to see the hidden files too.) 

958

Type g to go to one of these files or sub directories. 

959

Type ^ to return to the parent directory. 

960

(Note, g is the "go" command, and ^ is the back key; more on this later.) 

961

Thus you can traverse an entire directory tree

962

as though you were inside a file manager.

963

964

<P>

965

Like `ls -F', a subdirectory is indicated by a trailing slash. 

966

This slash is not part of the filename. 

967

Similarly, named pipe is indicated by |,

968

symbolic link by @,

969

block special by *, character special by <,

970

and socket by ^. 

971

If a regular file ends in one of these characters, it may confuse you,

972

but it won't confuse this program. 

973

Edbrowse knows whether that trailing | is part of the filename

974

or a pipe indicator. 

975

Since each file is represented by a single line of text,

976

files with newlines embedded in their names cannot be accessed.

977

978

<P>

979

If you read a directory into a preexisting file it is just text. 

980

You can't visit any of the underlying files, because they are just words. 

981

You must edit a directory in its own session

982

or read a directory into an empty session

983

if you want to access the underlying files. 

984

Note that you can write the buffer to another editting session,

985

and in that session the words are just words. 

986

This distinction is important as we start to edit the text.

987

988

<P>

989

By default, directories are readonly. 

990

If you try to delete a line, and hence the associated file,

991

it will tell you that you are still in directory read mode. 

992

I'm trying to save you from yourself! 

993

Type dw to enable directory writes,

994

and dr to make directories readonly again.

995

996

<P>

997

When directory writes are enabled,

998

you can remove files using the d command. 

999

For instance, g/\.o$/d removes all the object files. 

1000

Since these edits have implications outside the scope of this program,

1001

there is no undo capability. 

1002

When you make a change it is made. 

1003

With this in mind, I borrowed a good idea from Microsoft, which, as you might expect, originated with Apple. 

1004

The deleted file isn't actually deleted;

1005

it is moved to your recycle bin,

1006

located in $HOME/.recycle. 

1007

So if you accidentally type ,d and remove all your files,

1008

you can recover them from your recycle bin. 

1009

You may want to set up a cron job that removes

1010

all the files from your recycle bin once a week. 

1011

This directory is created mode 700, so nobody else can look at your deleted files. 

1012

If you create this directory yourself, please make it 700. 

1013

After all, some of your files might be private.

1014

1015

<P>

1016

Because this operation is a move, rather than a true delete,

1017

there are a few restrictions based on your operating system. 

1018

If your OS can move directories,

1019

this program will be able to delete a subdirectory as easily as a file. 

1020

The entire subtree is moved to your recycle bin. 

1021

Make sure your cleanup cron job is capable of removing directory trees, not just files.

1022

1023

<P>

1024

Depending on your OS, you may not be able to move files across file systems. 

1025

From /disk2 to /disk1, or from the D drive to the C drive. 

1026

In this case you might want to issue the dx command,

1027

which makes directories writable, like dw, but actually deletes the files. 

1028

You'll need this if you're trying to free up space on the disk. 

1029

Note that symbolic links are always deleted;

1030

there isn't much point in moving a link to the recycle bin.

1031

1032

<P>

1033

"What's the point of all this?" you may ask. 

1034

"What's wrong with the shell?"

1035

1036

<P>

1037

Nothing, as long as the file names are small and familiar. 

1038

But sometimes the file names are long and cumbersome,

1039

and it is nearly impossible to type those names into the shell,

1040

character for character, upper and lower case, with no mistakes. 

1041

Meta characters such as the * can help,

1042

but only when the file you want has a name radically different from the other files in the directory. 

1043

This isn't always the case. 

1044

Suppose an application generates log files as follows.

1045

1046

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>ProgramFooBar.-04-04-1998.06:31:59.log

1047

ProgramFooBar.-04-11-1998.11:37:14.log

1048

ProgramFooBar.-04-18-1998.16:22:51.log

1049

</font></PRE>

1050

1051

<P>

1052

How do you delete the old ones and keep the most recent,

1053

or rename them to something more manageable? 

1054

Stars are a bit risky; you can access multiple files without realizing it. 

1055

And we're not even talking about those pesky files with spaces or invisible control characters in their names. 

1056

Our sighted friend calls up his file manager and simply clicks on the file he wants to view or edit or remove. 

1057

Sometimes I want/need that kind of power.

1058

1059

<P>

1060

When the substitute command changes text, it renames the underlying file. 

1061

This won't move the file on top of another existing file,

1062

so you can't lose any data this way. 

1063

Again, I'm saving you from yourself.

1064

1065

<P>

1066

The search and substitute commands ignore the trailing filetype characters. 

1067

If you want to rename a directory from foo/ to foobar/,

1068

you can type s/$/bar/. 

1069

The bar will be placed at the end of the word foo, because the trailing / isn't really there.

1070

1071

<P>

1072

Now suppose you want to run an arbitrary program on some of these files. 

1073

This could be a print utility,a compiler, whatever. 

1074

Sometimes you can rename the files for your convenience, then work in the shell. 

1075

But sometimes you don't own the files,

1076

and sometimes they must retain their original names. 

1077

This happens when several html documents reference each other through hyperlinks,

1078

using their existing filenames. 

1079

So you can't rename the files, yet you still want to run your program on one or two of them.

1080

1081

<P>

1082

You can run any program on any file without retyping that filename via the shell escape. 

1083

Use kx to assign the label x to the file you are interested in. 

1084

(This is standard ed syntax.) 

1085

Then run !program 'x

1086

to invoke your program on that file. 

1087

This sounds involved, but it is merely macro substitution, implemented in a few lines of code. 

1088

If 'x is present in a shell escape, and is not next to any letters or digits,

1089

we replace it with the text on the line labeled x. 

1090

Thus if your filename contains spaces, you'd better run !program "'x",

1091

to make sure the entire file name is one argument to the running program.

1092

1093

<P>

1094

The token '. is replaced with the text on the current line,

1095

and the token '_ is replaced with the current filename. 

1096

If you try to write a file, and remember that you left it readonly,

1097

you can make it writable via !chmod +w '_,

1098

then write the text to the file.

1099

1100

<P>

1101

You can expand multiple tokens in one shell command. 

1102

Use kx and ky to mark two files that you want to compare, then run !diff 'x 'y.

1103

1104

<P>

1105

This feature is not limited to directory scans. 

1106

You may be editing a simple file,

1107

but you can still paste the contents of a line into your shell command. 

1108

Off hand I don't know why you'd want to do this,

1109

but you can.

1110

1111

<H3 align=center> <A NAME=case> Upper/Lower Case </A> </H3>

1112

1113

The `lc' command converts a line to lower case,

1114

and `uc' converts it to upper case. 

1115

Perl users will recognize these directives. 

1116

As an extension, `mc' converts to mixed case, capitalizing the first letter of each word,

1117

and the d in mcdonald.

1118

1119

<P>

1120

This is especially useful in a directory scan. 

1121

The last thing a blind person wants to worry about is whether some of the letters in a file name are upper case. 

1122

If directory write mode is enabled,

1123

type ,lc to convert all the file names to lower case. 

1124

It's that simple.

1125

1126

<P>

1127

If you want to upcase a particular word, type s/word/uc/. 

1128

This converts the word to upper case. 

1129

All the other substitution suffixes apply. 

1130

To change foo, Foo, FOo, and FOO to FOO, everywhere,

1131

type ,s/\bfoo\b/uc/ig.

1132

1133

<H3 align=center> <A NAME=bl> Break Line </A> </H3>

1134

1135

The `bl' command breaks the current line into sentences and phrases,

1136

each about 70 characters long. 

1137

It also compresses white space and strips white space from the end of the line. 

1138

If the line contains return characters,

1139

these are turned into line separaters -

1140

places where the line will definitely be cut. 

1141

The only white space that is preserved is the tabs or spaces

1142

at the beginning of the line, or after each return character. 

1143

This is a modest attemp to keep indented text indented,

1144

if that makes any sense?

1145

1146

<P>

1147

I use this feature in two different ways. 

1148

If I am familiar with the document,

1149

(I probably wrote it),

1150

I may use the bl command on a line of text that seems rather long. 

1151

I typed it in quickly, as an uninterrupted thought, and now I want to break it up. 

1152

But I don't want to count punctuation marks and say,

1153

"I think we need a break after the third comma

1154

and the period following that and then at the next comma",

1155

issuing the s punctuation commands along the way. 

1156

Oh I like the s commands well enough - they put you in complete contrl -

1157

but it's easier to type bl - and bl usually does the right thing. 

1158

Also, bl compresses accidental double spaces,

1159

a typo that I will never hear if I simply read the line as a whole.

1160

1161

<P>

1162

When the document comes in from the outside,

1163

usually from another word processor such as MS-Word,

1164

bl serves a completely different function. 

1165

Paragraphs are often stored on a single physical line. 

1166

Sometimes the entire document is on a single line,

1167

with return characters, \r, separating paragraphs. 

1168

Wysiwyg word processors don't worry about separating sentences and phrases -

1169

that's what word wrap is for. 

1170

Well - bl is our version of word wrap. 

1171

It doesn't try to conform to any screen;

1172

it merely cuts the text into manageable chunks,

1173

each piece a separate semantic unit. 

1174

When bl is issued,

1175

physical lines will contain sentences or phrases, as delimited by punctuation,

1176

or by the newline/return characters embedded in the original document.

1177

1178

<P>

1179

If one of the original lines, delimited by newline or return,

1180

is long, i.e. more than 120 characters,

1181

it is assumed to be a self-contained paragraph,

1182

and a blank line is added before and after. 

1183

Thus a disassembled paragraph containing 20 sentences

1184

does not simply flow into the next disassembled paragraph containing 18 more sentences. 

1185

An empty line separates the two paragraphs. 

1186

This is only applicable if bl is applied to a range of lines,

1187

or the entire document,

1188

as might occur when making an outside document readable.

1189

1190

<P>

1191

Don't apply the bl command to a preformatted section,

1192

such as a table or ascii art. 

1193

If you're not sure what to expect,

1194

i.e. you didn't write the file,

1195

scan through it first,

1196

and apply bl to the range of lines that actually represents text. 

1197

Often this is the entire document (,bl). 

1198

The following commands do a pretty good job of cleaning up a typical Microsoft Word document.

1199

1200

<P>

1201

<PRE><font size=3 face=Arial,Helvetica,sans-serif>e whatever.doc or whatever.wps

1202

# change filename, so you don't accidently overwrite the microsoft document

1203

f _

1204

,s/[~80-~ff~00-~0c~0e-~1f]//g # strip out non ascii control/formatting codes

1205

g/^\s*$/d # these blank lines use to contain non ascii codes

1206

,bl # break lines and paragraphs

1207

1,20p # first couple lines are often garbage, but then the text begins.

1208

</font></PRE>

1209

1210

<P>

1211

Of course the program catdoc does a better job of converting word documents into text. 

1212

This is often bundled with xls2cvs. 

1213

These are must-have programs for people who want a command line environment.

1214

1215

<H3 align=center> <A NAME=race> Race Conditions </A> </H3>

1216

1217

Suppose you are writing a file,

1218

and edbrowse truncates the existing file,

1219

then the computer crashes before edbrowse can write the new data. 

1220

When you bring your computer back to life,

1221

your file is empty, zero bytes, and all your work is lost.

1222

1223

<P>

1224

This is a narrow window to be sure;

1225

the computer has to fail at precisely the wrong millisecond. 

1226

To guard against this improbable calamity,

1227

some editors write your data to a temp file,

1228

remove the true file, and move the temp file over to the true file. 

1229

This way your data cannot be lost. 

1230

Either the new or the old file will survive.

1231

1232

<P>

1233

Then links came on the scene, hard links, and then symbolic links. 

1234

Authors of ed, and other editors, had to scramble. 

1235

You can't remove a link, write to temp,

1236

and move the temp file over to the link. 

1237

It isn't a link any more, it's a regular file,

1238

and your filesystem is not what it use to be. 

1239

For one thing, the true file, pointed to by the (symbolic) link,

1240

has not been changed at all. 

1241

This is not what you want! 

1242

So people rewrote there editors to disable this feature if the named file is

1243

a link to some other file. 

1244

They had to revert back to the old truncate and write paradigm,

1245

and hope that nothing bad happens in between. 

1246

And you know what, it never does. 

1247

The window is just too small.

1248

1249

<P>

1250

With this in mind, edbrowse doesn't mess with temp files at all. 

1251

I just don't bother. 

1252

I truncate the file and write out the data,

1253

and I don't expect anything to go wrong during the critical millisecond.

1254

1255

<P>

1256

Another race condition is more subtle. 

1257

Suppose you are editing a file and your friend,

1258

or a system program, edits the same file. 

1259

Your file has actually been changed out from under you,

1260

while you held it in memory. 

1261

When you go to write your changes,

1262

they will clobber any changes made by your friend, or the system utility. 

1263

Most text editors guard against this by watching the timestamp. 

1264

When you first edit the file foo,

1265

an editor might remember the timestamp on foo. 

1266

then, when you are ready to write your changes,

1267

it checks the timestamp, and if foo has been updated in the interim,

1268

it issues a warning message. 

1269

"File has been updated by someone else -

1270

do you really want to write?"

1271

1272

<P>

1273

This is a good feature,

1274

but edbrowse doesn't have it, simply because I haven't gotten round to writing it. 

1275

I'm the only user on my PC,

1276

and you're probably the only user on your PC too,

1277

so this feature is not in high demand. 

1278

Still, I should implement it some day.

1279

1280

<H3 align=center> <A NAME=url> Accessing A URL </A> </H3>

1281

1282

Instead of invoking `e filename', you can invoke `e http://this.that.com/file.html',

1283

and the editor will retrieve the named file using the http protocol. 

1284

The source (i.e. raw html) is made available for edit. 

1285

You can modify it and save it on your local machine. 

1286

Because the text was retrieve from another machine,

1287

it cannot be written back to that machine,

1288

hence the `w' command will not work. 

1289

You must specify a local file `w myfile.html',

1290

or another editing session `w3'.

1291

1292

<P>

1293

Note that this is not browsing, we are simply retrieving text from

1294

another machine and editing it locally. 

1295

The text need not be html, it could be (for instance) a plain ascii document. 

1296

Many people, myself included, put various types of files, even executables,

1297

on their websites for retrieval. 

1298

Of course you wouldn't want to edit a binary file,

1299

but you can still use this editor to retrieve the file and save it locally,

1300

thus implementing an http download.

1301

1302

<P>

1303

While inside the editor, you can type `e URL'

1304

to leave the current buffer and

1305

retrieve text from a remote machine. 

1306

Or you can type `r URL' to retrieve remote text and add it to the current buffer. 

1307

There is no `w URL' command, because the http protocol

1308

does not allow you to "write" html source back to a remote machine.

1309

1310

<P>

1311

As a convenience, any filename with two or more embedded dots

1312

and a standard suffix (such as .com or .net)

1313

is treated as a URL. 

1314

You can usually omit the http:// prefix. 

1315

Try invoking `e www.space.com',

1316

as an example. 

1317

But again, you are looking at html source, which probably isn't what you want. 

1318

Browsing will be discussed later.

1319

1320

<P>

1321

Whenever you retrieve data from a URL, the editor, directed by the http protocol,

1322

might change the filename out from under you. 

1323

This is because the resource has moved,

1324

and the original computer was kind enough to give you the new address. 

1325

If debugging is set to 2 or higher,

1326

you might see a series of three or four different URLs

1327

as the editor is redirected across the internet. 

1328

Finally it retrieves your document,

1329

and the current file name holds the correct (latest) URL. 

1330

You might want to update your bookmark file accordingly. 

1331

Then again, you might not. 

1332

Sometimes the initial url is the "public" location of the web page,

1333

and subsequent redirections occur inside the company. 

1334

In this case you'll want to retain the public url,

1335

which will always work, even if the company relocates its web server. 

1336

Use youre best judgment.

1337

1338

<H3 align=center> <A NAME=browse> Browse Mode </A> </H3>

1339

1340

If the editor contains html text, from any source,

1341

you can type `b' to activate browse mode. 

1342

The command will be rejected only if the buffer is lacking in common html tags,

1343

or the editor is already in browse mode. 

1344

You can force its hand by adding <html> at the top,

1345

or any other tag we recognize -

1346

it will always try to convert such a file. 

1347

Now the transformed text is readable, without any visible html tags. 

1348

In other words, <P> has been turned into a paragraph break,

1349

<OL> has become an ordered (numbered) list, and so on. 

1350

The filename is also changed; a .browse suffix has been appended. 

1351

If you write the transformed data, deliberately or accidentally,

1352

the reformatted text will be saved in a new file,

1353

whatever.html.browse,

1354

without disturbing the original html. 

1355

This protects you if you are developing your own web pages. 

1356

BTW, I believe blind people should write raw html,

1357

rather than wielding a wysiwyg web development tool such as Front Page. 

1358

In fact I write all my documents in html, even short business letters. 

1359

I can create headings, lists, tables, etc,

1360

without using a wysiwyg editor or a screen reader. 

1361

This

1362

1363

excellent tutorial</A>

1364

will get you started.

1365

1366

<P>

1367

When the browse conversion is executed, the system checks for

1368

common syntax errors, such as a numbered list that is never closed. 

1369

If the file name is a URL, these syntax errors are not reported. 

1370

After all, it's not your web page, and there's nothing you can do about it. 

1371

However, if the web page is yours, as indicated by a local filename,

1372

the first syntax error is displayed,

1373

whence you can return to the html source and fix it. 

1374

Type `ub' to undo the browse conversion. 

1375

This takes you back to the raw html text under its original filename. 

1376

Now you can coorect the error and try the `b' command again. 

1377

For your convenience, the label 'e is set to the line containing the error. 

1378

Repeat this process until `b' runs without errors.

1379

1380

<P>

1381

If you try to quit, and the editor says "expecting `w'",

1382

remember that you should be back in raw html before you issue the write command. 

1383

You could write the browsed text into file.browse,

1384

and that will satisfy the "write" criteria,

1385

but this isn't really what you want. 

1386

You've corrected errors in the html source, and that's what you need to save,

1387

so remember to undo the browse reformatting before you write the file.

1388

1389

<P>

1390

Note that you can issue the unbrowse command even if there were no errors. 

1391

If, for instance, you are looking at a well-constructed page

1392

on some other website,

1393

and you'd like to read or save the raw html, just type ub. 

1394

As an exercise, invoke `e www.space.com',

1395

and use the `b' and `ub' commands to switch between

1396

the raw html and the browsable text.

1397

1398

<P>

1399

The browse reformatting is relatively simple,

1400

because a blind person doesn't want complexity. 

1401

We don't care about fonts and italics etc, and if we do,

1402

the best way to obtain this information is by reading the raw html. 

1403

So most tags are discarded, except those related to headers, paragraphs, and lists.

1404

1405

<P>

1406

I don't indent subsections or list items. 

1407

The visual effect is lost on us,

1408

and sometimes the extra spaces get in the way.

1409

1410

<P>

1411

Because the physical line is, for us, the unit of thought,

1412

i.e. the atomic construct that is modified or moved or copied,

1413

lines are cut at approximately 80 characters, give or take a few,

1414

usually at a sentence or phrase boundary. 

1415

Thus reading line by line often reveals a sequence of sentences,

1416

or at least self-contained phrases within a larger sentence. 

1417

I consider this the optimal way to view or edit a document --

1418

any document. 

1419

If you read this manual raw, without doing the browse on the file,

1420

you'll see what I mean. 

1421

Review the <A HREF=#bl>break line</A> command above.

1422

1423

<P>

1424

The layout of a preformatted section, <pre>, is honored,

1425

although sequences of blank lines are compressed down to one blank line,

1426

and whitespace at the end of lines is stripped. 

1427

This preserves the structure of street addresses,

1428

and other preformatted blocks.

1429

1430

<P>

1431

Tables are formatted like an ascii unload from a spreadsheet or sql database. 

1432

Pipes separate the fields on each row. 

1433

There is no whitespace around the pipes,

1434

and the fields of a given row probably won't line up with the fields below. 

1435

It isn't pretty,

1436

but a blind user can't really trace down a column in any case,

1437

especially when using a line editor such as this. 

1438

Better to write the table to a local file and use cut, sort, join, etc. 

1439

Here is a sample table.

1440

1441

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>part number|quantity|price

1442

2635|2|$34.80

1443

1398|1|$67.50

1444

8118|5|$125.00

1445

</font></PRE>

1446

1447

<P>

1448

Empty fields at the end of a row are dropped. 

1449

These are almost always images -- sometimes an entire row of images --

1450

sometimes an entire table of images. 

1451

The blind user doesn't need to read the no-content pipes.

1452

1453

<P>

1454

Note that the browsable text is readonly. 

1455

After all, it's not the "source" -- why should you edit it? 

1456

There are ways to enter and edit the input fields of an on-line form,

1457

but this will be discussed later. 

1458

For now, you can think of the text as readonly. 

1459

Issue a copy or insert or substitute command,

1460

and you'll get an error.

1461

1462

<P>

1463

If you do want to edit the text, as pure text,

1464

enter the `et' command (edit as text). 

1465

You will not be able to return to the html that produced this page. 

1466

Nor can you follow a hyperlink or submit a fill-out form. 

1467

The browsable text has become plain text, with no internet semantics.

1468

1469

<P>

1470

The command `b file.html' is shorthand for `e file.html', followed by `b'. 

1471

Remember that the ub command reverses the browse conversion, and reproduces the original html text,

1472

as though you had entered `e file.html' alone.

1473

1474

<P>

1475

If a url is opened from the command line,

1476

as in `e www.google.com', it is automatically browsed. 

1477

Type `ub' to revert back to the raw html.

1478

1479

<H3 align=center> <A NAME=math> Technical, Math </A> </H3>

1480

1481

Most people never read technical web pages, but if you do...

1482

1483

<P>

1484

A subscript, as indicated by html tags, is enclosed in brackets. 

1485

Thus x<sub>n</sub> becomes x[n]. 

1486

This transformation is not done if the subscript is a one or two digit number. 

1487

Thus x subscript 1 is rendered x1, just like your professor would say it. 

1488

This is not ambiguous, as you might first think;

1489

only programmers use x1 as a variable name, not mathematicians. 

1490

If you see x1 in a formula, it means x subscript 1. 

1491

Even 17a3b3 is not ambiguous;

1492

it is a translation of 17 times a[3] times b[3].

1493

1494

<P>

1495

Superscripts are enclosed in parentheses, with a preceeding arrow. 

1496

The parentheses are omited if the superscript is a number. 

1497

Thus x cubed looks like x^3,

1498

while x to the n-1 power looks like x^(n-1).

1499

1500

<P>

1501

There are, sad to say, three different ways to encode mathematical symbols

1502

in html. 

1503

At present edbrowse only supports one of them,

1504

though it is the most common, and the most portable among all browsers. 

1505

This is the unicode system,

1506

where the Greek letter theta is specified as

1507

&#952;. 

1508

Explorer turns this expression into θ,

1509

one character on the screen,

1510

while edbrowse turns it into the word theta. 

1511

We also put spaces around the word

1512

if its neighbors are also words. 

1513

This is illustrated by the circumfrence of a circle, which is 2 times pi times r. 

1514

These three tokens are usually squashed together,

1515

and there is no confusion in the sighted world,

1516

where pi is a separate Greek letter. 

1517

But if pi is spelled out,

1518

and the tokens are left together,

1519

the result is 2pir. 

1520

Now pir looks like a three letter word. 

1521

To avoid this, edbrowse inserts spaces, giving 2 pi r.

1522

1523

<P>

1524

These translations are designed to work with the pages of the

1525

<A HREF=http://www.mathreference.com> Math Reference Project</A>,

1526

an archive of advanced mathematics

1527

that atemps to be both sighted and blind friendly at the same time. 

1528

This may be impossible,

1529

but I'm giving it a whirl.

1530

1531

<H3 align=center> <A NAME=title> Title, Description, Keywords </A> </H3>

1532

1533

While in browse mode, the commands ft, fd, and fk

1534

produce the title, description, and keywords of the current web page respectively. 

1535

These are normally not visible to the user. 

1536

The title describes the web page in 80 characters or less. 

1537

The description is a more complete explanation,

1538

which is displayed by a search engine such as yahoo or altavista. 

1539

The user reads the description via the search engine and decides whether to read that web page. 

1540

Finally, the keywords are used by search engines to facilitate keyword searches. 

1541

Like the rest of the browsable text,

1542

these three attributes are readonly. 

1543

If it is your web page,

1544

you can modify them by returning to the raw html. 

1545

Web designers should pay close attention to the description and the keywords,

1546

else your pages will not be accessible via the standard search engines.

1547

1548

<P>

1549

Note that `ft' prints the title of the web page,

1550

whereas `f t' (with a space) renames the current file to "t",

1551

which is probably not what you want.

1552

1553

<H3 align=center> <A NAME=rf> The Refresh Command </A> </H3>

1554

1555

Type `rf' to refresh the current file. 

1556

This rereads the file or url into the current buffer. 

1557

It does not push a new editing session onto the stack. 

1558

This is analogous to the refresh button on Netscape and Explorer.

1559

1560

<P>

1561

If a web page is updated every minute, e.g. with the latest stock prices for your favorite companies,

1562

you can type rf to fetch the latest copy of this web page. 

1563

This assumes the intervening internet servers are not caching the web page

1564

and handing you the same out-of-date copy over and over again.

1565

1566

<P>

1567

On your local machine,

1568

you can use this feature to read the latest version of a dynamic file,

1569

such as a log file. 

1570

Or you can reread a directory,

1571

to incorporate any new files that have been placed in that directory. 

1572

For example, you might use the shell escape to execute

1573

`cat x y >z',

1574

yet z will not appear in your directory scan until you type rf.

1575

1576

<H3 align=center> <A NAME=hlink> Hyperlinks </A> </H3>

1577

1578

A link to another web page is enclosed in braces, like this:

1579

1580

<P>

1581

{Recent reports} suggest a connection between autism and intestinal bacteria.

1582

1583

<P>

1584

Behind the scenes, "recent reports" is linked to

1585

www.pecanbread.com/BTVCautismchapter.html,

1586

but you don't see that unless you activate the link

1587

or view the raw html.

1588

1589

<P>

1590

Of course the browsable text might also contain words inside braces,

1591

especially if the web page is technical in nature. 

1592

Hence there is some ambiguity. 

1593

However, I believe it is clear from context. 

1594

{More information} is probably a link,

1595

whereas ${HOME}/.profile is probably not.

1596

1597

<P>

1598

Some web pages present a series of icons

1599

that are actually links to other pages. 

1600

That is, you click on an icon, rather than a phrase, to go somewhere else. 

1601

These icons are suppose to be intuitive. 

1602

Sometimes they are -- sometimes they're not. 

1603

In any case, they aren't much use to the blind. 

1604

Sometimes the web designer is kind enough to supply

1605

a text phrase that roughly describes the image. 

1606

In this case the phrase is used as the link. 

1607

It appears in braces, as though there were no image at all. 

1608

If there is no alternate phrase,

1609

the filename of the hyperlink reference is used. 

1610

This name can be surprisingly helpful,

1611

or it can be utterly useless, as in "index.html". 

1612

If this name canot be determined,

1613

the generic link {image} is used. 

1614

In this case you will have to go to the web page to find out what it contains.

1615

1616

<P>

1617

To follow a link, enter the `g' (go) command. 

1618

Yes, `g' also initiates a global command,

1619

such as a global substitute,

1620

but only when it is followed by a regular expression. 

1621

By itself, g follows the link on the current line,

1622

g2 follows the second link on the current line,

1623

and 4g follows the link on line 4. 

1624

If a link spreads across multiple lines, you must be on the first of these lines,

1625

the line containing the left brace.

1626

1627

<P>

1628

The g command can also act on a link that is written in raw text,

1629

as long as it "looks" like a valid url. 

1630

If your friend sends you an interesting url via email,

1631

and you save it to a text file,

1632

you can "go" to that link,

1633

even though the file is not html,

1634

and you've never issued a browse command.

1635

1636

<H3 align=center> <A NAME=ilink> Internal Links </A> </H3>

1637

1638

Although most links lead to other web pages,

1639

some links point to other sections within the current document. 

1640

Again, you will be able to tell by context. 

1641

Links in the table of contents are usually

1642

shortcuts to chapters in the current document. 

1643

The same holds for links that look like:

1644

see {Appendix I},

1645

or, see the section on {Hardware Configuration}.

1646

1647

<P>

1648

The g command follows an internal link or an external link. 

1649

Either way you find yourself in a different place. 

1650

However, if the link is internal,

1651

you are still browsing the same file. 

1652

In fact, the only thing that has changed is the current line number. 

1653

The new line is displayed,

1654

and should correspond to the link you activated. 

1655

Often the words are the same. 

1656

Activate {Appendix I}, and you'll probably see the section heading "Appendix I". 

1657

Enter z10 to read the first few lines of the appendix.

1658

1659

1660

1661

If you edit a new file via the `e', `b', or `g' commands,

1662

and you already have text in the buffer,

1663

that text is bundled up and pushed onto an internal stack. 

1664

You can pop the stack by issuing the `^' command. 

1665

This is suppose to be intuitive --

1666

the up arrow pointing to the previous page that rolled off your screen.

1667

1668

<P>

1669

This feature seems rather silly if you're just editing files,

1670

but it makes sense when surfing the net. 

1671

Often we descend through two or three links,

1672

only to find ourselves at a dead end. 

1673

"I didn't want to go here." 

1674

So we hit the back key again and again, until we reach familiar territory. 

1675

We can now proceed in a new direction. 

1676

The command ^3 or ^^^ backs up through three pages. 

1677

Don't use this iterative feature unless you know exactly how many times you need to back up.

1678

1679

<P>

1680

Note that the entire state of an editing session is saved and reproduced,

1681

including the file name,

1682

the last search/replace strings for substitutions,

1683

the hyperlinks and forms,

1684

the compiled javascript,

1685

everything!

1686

1687

<P>

1688

Unlike lynx, I don't keep a running history of every web page visited. 

1689

I never really saw a need for this feature. 

1690

99% of the time I simply want to back up one or two pages,

1691

and that's it. 

1692

Unfortunately this high-runner operation requires two somersaults and a back flip under lynx. 

1693

It is a one key command in my browser.

1694

1695

<P>

1696

The stack should not be confused with parallel edits,

1697

as described in an earlier section. 

1698

In fact each editing session, e1 e2 e3 ..., has its own internal stack. 

1699

Parallel sessions are appropriate when you need to move back and forth between two files,

1700

or cut&paste between them. 

1701

However, one session, with its internal stack,

1702

is usually sufficient to surf the net.

1703

1704

<P>

1705

If a browse command fails completely,

1706

giving you a rather uninteresting empty buffer,

1707

the stack is popped automatically,

1708

taking you back to the previous web page. 

1709

Now you can retry the link by typing `g' again,

1710

or follow a different link on the page. 

1711

Note that a browse command can fail, and still give you text explaining why it failed,

1712

if the remote server is well-designed. 

1713

In this case you may see the error message "file not found",

1714

yet you will be viewing a new web page, which explains the problem. 

1715

After you've read the explanation,

1716

follow its directions,

1717

or type ^ to back up and try again.

1718

1719

<P>

1720

If you are presented with a number, even 0, the stack has been pushed, and you are in a new file or url. 

1721

The number is the size of the new file. 

1722

Use the ^ command to get back. 

1723

If there is no number, merely an error message,

1724

then edbrowse did not create a new buffer. 

1725

It probably didn't get that far. 

1726

Typing . will produce the same line you saw before.

1727

1728

<P>

1729

Following an internal link to another section in the current document

1730

does not push anything onto the stack. 

1731

In other words, ^ will not take you back to where you were. 

1732

In fact, it will take you up to the previous web page, which is not what you want. 

1733

If you want to take a glance at Appendix I, and then return,

1734

mark the current position with `kr'. 

1735

After you've visited the appendix, use the label 'r to return to your original location in the file.

1736

1737

<H3 align=center> <A NAME=move> The M Command </A> </H3>

1738

1739

If you want to read and/or interact with several web pages in parallel,

1740

pages that would normally stack up,

1741

you can move each one to another session using the capital M command. 

1742

The tags and links are transferred along with the rendered text. 

1743

Once the web page has moved to another session,

1744

edbrowse issues the ^ command for you. 

1745

Now you are back to the previous page.

1746

1747

<P>

1748

It is generally unsafe to make a copy of a running web page,

1749

with all its javascript objects etc,

1750

so the M command <em>moves</em> the page out of the way,

1751

and takes you back to the previous page. 

1752

Note, this command works just as well with files.

1753

1754

<P>

1755

Suppose a web page presents

1756

<P>

1757

{planes}

1758

<br>

1759

{trains}

1760

<br>

1761

{automobiles}

1762

1763

<P>

1764

If you are curious about all three topics,

1765

issue these commands in this order.

1766

1767

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>1g

1768

M2

1769

2g

1770

M3

1771

3g

1772

M4

1773

</font></PRE>

1774

1775

<P>

1776

Now sessions 2 3 and 4 are the subpages about plains trains and automobiels respectively. 

1777

You can fill out forms or follow hyperlinks in any of them,

1778

or stay in session 1 and do something else.

1779

1780

<H3 align=center> <A NAME=music> Background Music </A> </H3>

1781

1782

If you are trying to listen to a speech synthesizer,

1783

the last thing you need is background music. 

1784

Instead of playing the song, I make it available to you through a hyperlink.

1785

<P>

1786

{Background Music}

1787

<P>

1788

This always appears at or near the top of the page. 

1789

Click on this link and download the wave or mp3 file,

1790

and play it at your convenience. 

1791

Use the play buffer `pb' command. 

1792

Normally pb uses the name of the file to infer the audio format. 

1793

If the filename ends in .wav, it's a wave file, and so on. 

1794

If the filename is not particularly helpful, and you know the audio format, you can specify it by typing

1795

pb.wav for a wave file, pb.mp3 for an mp3 file, and so on.

1796

1797

<P>

1798

The config file (described below)

1799

includes mime type descriptors,

1800

which tell edbrowse how to play wave and mp3 files etc. 

1801

These must be set up, or the pb command won't work. 

1802

It will say something like,

1803

"I don't know how to process an mp3 file". 

1804

This is consistent with other browsers, which use "plugins" to play multimedia files that are retrieved from the internet.

1805

1806

<H3 align=center> <A NAME=input> Input Fields </A> </H3>

1807

1808

The input fields of an on-line form are usually indicated by angle brackets. 

1809

For example, a search engine might present the following form.

1810

1811

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>Keywords: <>

1812

Advanced parsing: <->

1813

Language: <en>

1814

Search now: <GO>

1815

Cleaar form: <RESET>

1816

</font></PRE>

1817

1818

<P>

1819

The first line in this sample form is a simple text field, which is initially empty. 

1820

You supply the keywords to search for. 

1821

Entering and editing input fields is discussed later.

1822

1823

<P>

1824

The second line is a checkbox. 

1825

This field tells the search engine to use advanced boolean features,

1826

such as this keyword and that, or this, but not that, etc. 

1827

The feature is disabled, indicated by -. 

1828

(Most people don't know how to use advanced search anyways.) 

1829

A + means the checkbox is on.

1830

1831

<P>

1832

The third line determines the language of the keywords, English by default. 

1833

This isn't a free text field, you can't just type in anything you want. 

1834

We'll describe how to view the options later.

1835

1836

<P>

1837

The fourth line is the submit button, which sends the form to the search engine

1838

and retrieves the results. 

1839

This "field" cannot be edited; it is merely a button to push.

1840

1841

<P>

1842

The fifth line is also a button to push. 

1843

It clears all the data you have entered, so you can start over. 

1844

Default values will be restored. 

1845

Thus the third line goes back to <en>, rather than <>.

1846

1847

<H3 align=center> <A NAME=entry> Data Entry </A> </H3>

1848

1849

Filling out a form is relatively easy,

1850

once you are familiar with the (overloaded) `i' command. 

1851

Yes, i by itself means insert text,

1852

but in browse mode, i refers to the input fields.

1853

1854

<P>

1855

If there is only one input field on the current line, i? 

1856

displays information about that input field. 

1857

If the line contains multiple input fields, you will need to use a number,

1858

as in i3? for the third field. 

1859

The type of input field is displayed, then its size,

1860

then the field name. 

1861

If the input field is drawn from a set of options,

1862

the option list is displayed as well,

1863

with menu numbers prepended. 

1864

When you want to select an option,

1865

you can either type in a substring that determines that option uniquely,

1866

such as mich for Michigan,

1867

or you can type in its menu number. 

1868

Needless to say, the latter is often easier. 

1869

Recall the sample form in the previous section. 

1870

If you type i? at the third field, you might see the following.

1871

1872

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>select[7] language

1873

1: english

1874

2: french

1875

3: german

1876

4: italian

1877

5: spanish

1878

</font></PRE>

1879

1880

<P>

1881

If a select list contains hundreds of options,

1882

type i?string to see only those options that contain the specified string. 

1883

Type I?mi in a state field and get Michigan, Mississippi, Missouri, and Minnesota. 

1884

Then you can select the option you want by name or by number.

1885

1886

<P>

1887

Now let's do some data entry. 

1888

Type i=xyz to place xyz in the input field. 

1889

Remember, you will need to type i3=xyz

1890

to put information into the third input field on the current line. 

1891

If you get an error, it is probably because the field has a fixed set of options,

1892

and you didn't pick one of those options. 

1893

You can either type in one of the options or its menu number. 

1894

You can also type in a fragment of the option you want,

1895

and edbrowse will fill in the rest. 

1896

This is done whenever one and only one option contains a copy

1897

(case insensitive) of the string you entered. 

1898

Thus you could enter tali above and get Italian,

1899

as that is the only language with those four letters. 

1900

This is useful when you are entering your address,

1901

and they ask for the state. 

1902

Type in a few letters of your state name, enough to be unique,

1903

and you'll probably glom onto the correct option in the list. 

1904

Note the paradigm here:

1905

blind people don't want to wade through a menu unless they absolutely have to!

1906

1907

<P>

1908

There is some ambiguity when the option is itself a number. 

1909

In this case I perform three matches. 

1910

If you type in the number exactly as it appears, that option is selected. 

1911

If the number you entered is not a perfect match for one of the options, it is treated as a menu number. 

1912

If it is not a valid menu number (e.g. out of range), I perform a partial match on the options, looking for those digits as a substring. 

1913

This may seem confusing, but it is usually what you want.

1914

1915

<P>

1916

You can use i<7 to pull the contents of session 7 into the current input field. 

1917

Session 7 must have one line of text. 

1918

Similarly, i<filename reads the contents of the file into the current input field. 

1919

Again, the file should contain one line of text. 

1920

The filename is expanded in the usual way. 

1921

This includes wildcard expansion, as long as the expansion leads to one and only one file. 

1922

Put enough characters around the * to designate a single file.

1923

1924

<P>

1925

Now suppose you are entering your credit card number, all 16 digits, into a free text field. 

1926

If you've made a typo, you don't really want to enter the entire string again. 

1927

No problem -- use the substitute command. 

1928

You can write this as i/x/y/ or s/x/y/ -- as you prefer. 

1929

Remember, you may need to specify a field, as in s3/x/y/. 

1930

The usual substitution syntax is honored. 

1931

Don't overgenralize the g suffix in your mind. 

1932

s3/x/y/g changes every x to y in the third input field, but does not affect the other fields on the current line.

1933

1934

<P>

1935

If the submit button is the third field on the current line, you can press it via i3*. 

1936

However, i* is sufficient when there is only one button on the line. 

1937

Similarly, you can establish a text field by entering i=kangaroo,

1938

rather than i1=kangaroo, if the second field on the current line is a submit button. 

1939

You only need specify a field number

1940

when there are multiple input fields, or multiple buttons, on the current line.

1941

1942

<H3 align=center> <A NAME=textarea> Text Areas </A> </H3>

1943

1944

Some internet forms allow you to type freely, as in "Please enter your comments here." 

1945

This is done inside a window within the screen,

1946

having a fixed number of rows and columns,

1947

although that is usually an artificial constraint. 

1948

The sighted user can type more lines than the window will hold,

1949

and the window scrolls appropriately. 

1950

Fortunately the blind user can ignore the artificial window and type freely. 

1951

Still, the i? directive tells you how big the window would be,

1952

if you were running a visual browser. 

1953

You might see something like "area[7x40]", which indicates a window 7 rows by 40 columns.

1954

1955

<P>

1956

The lynx implementation of the text area is particularly hideous. 

1957

This is not surprising, since lynx is not an editor. 

1958

You can correct small typos on the current line,

1959

but you can't actually "edit" the text you are working on. 

1960

Once you hit return, that line is done, and you're on to the next line. 

1961

You can't move lines around or insert lines etc. 

1962

Nor can you prepare your comments ahead of time and read them into the text area from a file.

1963

1964

<P>

1965

In edbrowse, the text area is managed from another editing session. 

1966

This allows you to use the full power of the editor. 

1967

You can move text, make global substitutions,

1968

or read comments in from a prepared file. 

1969

The editing session is chosen for you, and appears in the input field. 

1970

Consider the following form.

1971

1972

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>Enter your email address: <>

1973

Enter your comments: <buffer 2>

1974

</font></PRE>

1975

1976

<P>

1977

In this example, session 2 was not active when browsing began. 

1978

The browser allocated session 2 specifically for this input field. 

1979

Type e2 to move to session 2, prepare your comments,

1980

and type e1 to return to the input form. 

1981

On most web pages the text area starts out blank,

1982

whence buffer 2 will be empty,

1983

but this is not always the case. 

1984

Be sure to check for pre-existing text before you start typing your thoughts. 

1985

A particularly arrogant site might preload the text area with:

1986

"I love your website because:".

1987

1988

<P>

1989

When you finally submit the form,

1990

as discussed in the next section,

1991

text buffer 2, associated with the second editing session,

1992

will replace the words "bufffer 2" in the input field. 

1993

Thus your carefully crafted comments are on their way. 

1994

(This doesn't mean anybody is going to listen to them.)

1995

1996

<H3 align=center> <A NAME=button> Push The Button </A> </H3>

1997

1998

If the third input field on the current line is a reset or submit button,

1999

you can press the button via i3*. 

2000

The reset button puts the input fields back to their original values,

2001

as supplied by the web page when it was first loaded.

2002

2003

<P>

2004

The submit button sends the form to the remote server and waits for a response. 

2005

This is similar to following an internet link,

2006

but in this case you are sending some data along with the request. 

2007

Type "kangaroo" into a search engine and you'll soon be reading a web page about kangaroos. 

2008

As with any other link, you can use the ^ key to go back. 

2009

In this case you will return to the on-line form. 

2010

You can change the data and submit the form again, asking about another animal.

2011

2012

<P>

2013

I have implemented the "get" and "post" methods,

2014

the most common http protocols,

2015

and they seem to work on most sites.

2016

2017

<P>

2018

Once you have submitted your form,

2019

and you are viewing the results,

2020

you may notice some strange characters at the end of the filename. 

2021

If you have retrieved information on kangaroos, the filename might look like:

2022

www.search-engine.com?keywords=kangaroo. 

2023

The text after the question mark is an encoded version of the data

2024

you entered into the form. 

2025

It becomes part of the virtual URL. 

2026

This is actually a good thing, as we shall see in the next section.

2027

2028

<H3 align=center> <A NAME=addr> Web And Email Addresses </A> </H3>

2029

2030

The capital A command shows you the web addresses behind

2031

the links on the current line. 

2032

Each web address will be surrounded by <a> and </a> tags,

2033

ready to be pasted into a bookmark file, if that is what you wish. 

2034

These addresses exist in a new editing session; the previous session has been pushed onto the stack. 

2035

You can add these to your bookmark file via w+ $bookmarks,

2036

assumeing you have set the environment variable bookmarks appropriately. 

2037

They will be appended at the end;

2038

you can move them to a more appropriate place in the file later on, when you're not "on line". 

2039

For many, with dial up connections,

2040

connect time is precious,

2041

and should not be spent rearranging bookmark files. 

2042

Finally, use the ^ key to return to the web page you were viewing. 

2043

Here is how it might look.

2044

2045

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>< b this.that.com/whatever # browse a web page

2046

> 16834 # size of the raw html

2047

> 7855 # size of the browsable text

2048

< /kangaroo/i # looking for kangaroo on the page

2049

> Click here for {more information about kangaroos}, or {send us mail}.

2050

< A # capture the URLs

2051

> 144 # size of the URLs

2052

< ,p # let's see them

2053

> <A HREF=www.kangaroo-info.com>

2054

> more information about kangaroos

2055

> </A>

2056

> send us mail:info@kangaroo.org

2057

< 4d # don't need the email address

2058

< w+ $bookmarks # append this url to the bookmark file

2059

> 336

2060

< ^ # back to browsing

2061

> Click here for {more information about kangaroos}, or {send us mail}.

2062

</font></PRE>

2063

2064

<P>

2065

I suppose I could interrogate the environment variable $bookmarks myself,

2066

and append the URL to that file automatically,

2067

but as this example shows, you might not want all the links. 

2068

In fact the email link makes no sense in a bookmark file. 

2069

Also, you may want to change the description of the link,

2070

though in this example the description is pretty reasonable.

2071

2072

<P>

2073

Alternatively, you might discard the url and retain the email address,

2074

appending it to your address book. 

2075

Again, you will want to change the generic phrase "send us mail"

2076

to a brief string that is meaningful to you, such as kangaroo-mail. 

2077

This becomes the alias, which you can use to send mail

2078

to that recipient. 

2079

(Subsequent sections describe the use of edbrowse as a mail client.)

2080

2081

<P>

2082

If there are no links on the current line, or you are not in browse mode,

2083

the current filename is used. 

2084

This is useful when you want to bookmark the current page,

2085

rather than some other page pointed to by a link.

2086

2087

<P>

2088

If the current page is the result of a form submition, the filename

2089

may include your input fields after the question mark. 

2090

If it does, that's a feature, not a bug. 

2091

This exact URL, with the data at the end, can be stored as a bookmark

2092

and activated again and again,

2093

as though you had filled out the form each time. 

2094

Every week you can call up this virtual URL

2095

to see if there is any new information on kangaroos. 

2096

A more practical example might be a canned query that retrieves

2097

the weather for a certain city

2098

or the stock prices for the companies in your portfolio. 

2099

You can also write concise scripts that "fill in" the virtual

2100

form, simply by modifying the information after the question mark. 

2101

This provides a simple command to retrieve the weather from any major city

2102

or the current price of any stock.

2103

2104

<P>

2105

If the form uses the post, rather than the get method,

2106

the same data will appear,

2107

but the question mark is replaced with a control a. 

2108

Unfortunately the control a is not visible, and this could cause confusion. 

2109

When in doubt, list the line.

2110

2111

<P>

2112

One last warning about adding links to your bookmark file. 

2113

Let's say you've issued your A command, and tweaked the description a bit. 

2114

Now the link is just write, and you want to save it. 

2115

You accidentally type `w $bookmarks', forgetting the plus. 

2116

Instead of apending the link to the end, you have clobbered your entire bookmark file. 

2117

Years of accumulated links are gone. 

2118

To avoid this disastrous typo, create a macro to append to your bookmark file. 

2119

I know, we haven't talked about user defined macros yet, but we will. 

2120

And when we do, you should write a "bookmark append" macro that looks like this.

2121

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+bma {

2122

w+ $bookmarks

2123

}

2124

</font></PRE>

2125

2126

<P>

2127

Now you can type <bma to add a link to your favorites,

2128

and you don't have to worry about typos. 

2129

It's shorter than `w+ $bookmarks' anyways. 

2130

We'll return to this topic when we introduce macros,

2131

actually functions,

2132

that are defined in your config file.

2133

2134

<H3 align=center> <A NAME=cook> Cookies </A> </H3>

2135

2136

Some websites serve "cookies",

2137

which your browser is expected to retain

2138

and pass back during subsequent exchanges. 

2139

In fact many websites simply won't work without cooky support. 

2140

Therefore edbrowse always accepts cookies.

2141

2142

<P>

2143

Note that only Netscape-style cookies are supported. 

2144

However, this is the most common flavor of cooky. 

2145

It will probably meet your needs.

2146

2147

<P>

2148

Persistent cookies are stored in a file,

2149

usually $HOME/.cookies,

2150

and are thus available for subsequent edbrowse sessions. 

2151

These cookies are used to store long-term information about you,

2152

such as your login and password into amazon.com. 

2153

Hence your .cookies file should be mode 0600. 

2154

In fact the file is created mode 0600, for your own protection.

2155

2156

<P>

2157

You probably won't need to view your .cookies file, ever,

2158

but it is text based, and can be edited directly if you wish.

2159

2160

<H3 align=center> <A NAME=ssl> Secure Connections </A> </H3>

2161

2162

Edbrowse supports the most common method of encrypting web traffic,

2163

HTTP over SSL/TLS, colloquially known as secure http. 

2164

Websites that support

2165

secure http have URLs of the form:

2166

https://secure.server.com. 

2167

Notice the protocol is https:// rather than http://. 

2168

The extra s stands for "secure". 

2169

The traffic is encrypted, i.e. mathematically scrambled,

2170

and cannot be intercepted by a nefarious third party.

2171

2172

<P>

2173

Edbrowse will verify ssl connections,

2174

if you supply a file of ssl certificates. 

2175

This is an antispoofing measure, to make sure a hacker isn't posing as your bank,

2176

trying to steal your account numbers and passwords. 

2177

You can grab a certificate file <A HREF=ssl-certs>here</A>,

2178

but I don't always keep it up to date. 

2179

On some Linux distributions, you can run `cd /etc/ssl/certs ; cat * >../edbrowse-certs'

2180

to capture ssl certificates that are as current as your linux system.

2181

If you don't have or create this file,

2182

or, if you don't specify its location in your config file,

2183

you will not be able to verify secure connections, and you will be warned accordingly. 

2184

Some browsers don't have this feature at all, so it's not the end of the world,

2185

but in general it's a good idea to verify your secure connections,

2186

unless it prevents you from getting to a website whose authenticity you accept at face value. 

2187

In that case you can use the vs command to turn the feature off. 

2188

This is a toggle command; type vs again to turn the feature on.

2189

2190

<P>

2191

Never send sensitive information,

2192

such as social security numbers or credit card numbers,

2193

over an insecure channel. 

2194

Make sure the form is using ssl. 

2195

How can you tell? 

2196

The submit button will have the word "secure" added to its text.

2197

<P>

2198

2199

<P>

2200

This is similar to the lock icon that Explorer uses to tell you that your connection is secure,

2201

although my system is not quite as foolproof. 

2202

A website could fake you out by putting the word secure in the submit text.

2203

2204

<P>

2205

Note that generic buttons (besides the submit button) can also submit your form,

2206

through javascript. 

2207

I don't know if that button is going to submit the form or not,

2208

and I don't want to put the word "secure" on every button on the page. 

2209

I only add it to the submit button,

2210

but if that button is secure then they are all secure. 

2211

They all use the same form, and the same url.

2212

2213

<P>

2214

In theory, it is possible for javascript too switch the destination url out from under you at the last minute,

2215

from https://this.is.safe.com to http://this.is.untrusted.com. 

2216

I don't know if other browsers watch for this bait-and-switch, but edbrowse does. 

2217

If the original url was secure,

2218

and I reported this to you via <submit secure>,

2219

and javascript changes it to an insecure connection, I won't submit the form. 

2220

This is really paranoid,

2221

because the first website, the one that asked for your credit card number,

2222

also supplies the javascript,

2223

and they have no incentive to breech security,

2224

since you're going to hand them your credit card number anyways.

2225

2226

<P>

2227

If you have logins on secure servers,

2228

such as PayPal.com,

2229

you must keep your password absolutely safe. 

2230

Never send that password over an insecure connection. 

2231

It becomes as valuable as your credit card numbers. 

2232

I have a special password that I use for my secure logins,

2233

and <em>only</em> for those logins. 

2234

I use other, expendable passwords when the connection is not secure.

2235

2236

<P>

2237

Please don't fall for all those "phishing" email scams

2238

that tell you your login has expired, and would you please log in again using this convenient form. 

2239

The mail is forged to look legitimate,

2240

and the form actually sends your secret password to a thief,

2241

who then rades your account. 

2242

A reputable company will

2243

never, never, never, ask you to login through an email form. 

2244

They will always tell you to go back to the website and log in there.

2245

2246

<P>

2247

Internet security is complex, to say the least,

2248

and it is beyond the scope of this document. 

2249

If you have any questions about it,

2250

please send them to me directly. 

2251

As a general rule,

2252

secure http is really quite safe, and you can use it to send sensitive information across the Net. 

2253

It's probably safer than giving your credit card number to the clerk on the phone,

2254

who use to take your order before there was e-commerce. 

2255

so it's ok to be a little bit paranoid,

2256

in fact it's probably a good idea,

2257

but don't let that stop you from making your online purchases.

2258

2259

<H3 align=center> <A NAME=ftp> FTP Retrievals </A> </H3>

2260

2261

This browser supports the retrieval of ftp files and directories. 

2262

You can provide an FTP URL like:

2263

ftp://ftp.random.com/tarball.tar.gz

2264

and the file will be fetched. 

2265

It doesn't matter whether you type in the url yourself,

2266

or it is a hyperlink on a web page. 

2267

The file is retrieved, and placed in a local file of the same name. 

2268

You will ssee the words:

2269

<P>

2270

ftp download

2271

<br>

2272

some stats on the size of the file and the bits per second

2273

<br>

2274

success

2275

2276

<P>

2277

Of course the download could fail, in which case you will receive an error message. 

2278

If it was simply interrupted,

2279

due to some internet glitch,

2280

you can issue the command again,

2281

and edbrowse will resume the download from where it left off. 

2282

This can save time when fetching a large file.

2283

2284

<P>

2285

By default, edbrowse uses the account name "anonymous" and the password

2286

"some-user@edbrowse.net" for ftp connections. 

2287

However, you can override this in the url,

2288

and some web pages take advantage of this feature. 

2289

For example, let's say you want to access the file /etc/passwd on whatever.localdomain. 

2290

This file isn't readable by anonymous users. 

2291

You have to log in as a real person. 

2292

Within edbrowse, you might use the command:

2293

<P>

2294

e ftp://chris:xxx@whatever.localdomain/etc/passwd

2295

2296

<P>

2297

The ftp connection will be made as user "Chris", with password "XXX".

2298

2299

<P>

2300

Some ftp URLs point at directories, not files. If you visit one of these,

2301

and it is located on a Unix-like server, you will receive the listing as an

2302

html file with hyperlinks. You can visit the directory members just as

2303

though you were exploring a website. 

2304

If the server does not run some

2305

flavore of Unix, you will receive the directory listing in plain

2306

text.

2307

2308

<P>

2309

The ftp mode, i.e. the style of data connection,

2310

can be either active or passive. 

2311

One works well when the client is behind a router,

2312

and the other works well when the server is behind a router. 

2313

You can specify ftp mode active by entering the command `fma',

2314

or ftp mode passive by `fmp'. 

2315

The command `fmd' sets the ftp mode to a default,

2316

which tries to establish a passive connection first,

2317

and then an active connection as a fallback. 

2318

This is a reasonable default, so you should probably leave this alone.

2319

2320

<P>

2321

Edbrowse doesn't actually establish the ftp connections,

2322

rather, it invokes the program ncftpget to fetch the file,

2323

and ncftpls to list the directory. 

2324

These programs are distributed with most Unix systems. 

2325

If you don't have these programs, please visit

2326

<A HREF=http://www.ncftp.com>ncftp.com</A>.

2327

2328

<P>

2329

Once again, review the differences. 

2330

Http pulls a file into a buffer in memory, i.e. an edbrowse session,

2331

while ftp copies the file directly to disk. 

2332

Also, ftp does not print dots every 100K to indicate progress,

2333

so you just have to wait until it's done. 

2334

(Depending on your operating system, you could switch to another virtual console/window and check on the length of the local file.)

2335

2336

<H3 align=center> <A NAME=proxy> Proxy Servers </A> </H3>

2337

2338

A proxy server is a web server that sits between your web browser and remote websites. 

2339

It intercepts your requests for web pages and forwards them to the system that hosts

2340

the site you are browsing. 

2341

Proxy servers are used for a variety of reasons. 

2342

Here are just a few of them:

2343

2344

<OL>

2345

<P><LI>Efficiency. 

2346

The proxy server may be able to store previously-accessed webpages

2347

(known as caching). 

2348

If your connection to the proxy is faster than your connection to the rest of the network,

2349

then caching insures that frequently-accessed web pages load quickly.

2350

<P><LI>Policies. 

2351

Some firewall administrators require their users to use

2352

a proxy server.

2353

<P><LI>Anonymity. 

2354

There are so-called anonymizing

2355

proxy servers that hide your IP address from the websites that you browse.

2356

</OL>

2357

2358

<P>

2359

If you wish to use a proxy server for http traffic, simply set the proxy

2360

option in your configuration file. 

2361

Provide the hostname and port, separated by a colon. 

2362

For example:

2363

<P>

2364

proxy = proxy.campus.edu:3128

2365

2366

<p>

2367

Note that proxies often listen on ports other than port 80. 

2368

Squid is a proxy server that comes bundled with some Linux distributions, and it uses

2369

port 3128 by default.

2370

2371

<p>

2372

Presently, edbrowse only handles proxying of standard http. 

2373

Secure http and ftp

2374

can both be proxied, but this functionality is not implemented.

2375

2376

<H3 align=center> <A NAME=frame> Frames </A> </H3>

2377

2378

Frames are a mechanism whereby a web page can fetch and display several other web pages on the screen at once. 

2379

Each subpage is called a frame, and lives in its own space on the screen. 

2380

Sometimes the frames are top middle and bottom;

2381

sometimes they are left middle and right. 

2382

Edbrowse presents these frames as hyperlinks,

2383

and you can call up each in turn,

2384

or jump straight to a specific frame if you are familiar with the website. 

2385

Usually the top frame is navigational in nature,

2386

and the bottom is a legal disclaimer/copyright notice,

2387

so you're just as happy to skip these and cut to the chase. 

2388

On rare occasions, and I've only seen this once,

2389

you <em>must</em> open the top frame,

2390

whether you are interested in it or not,

2391

because that particular html page sets some cookies that you need to run the website.

2392

2393

<P>

2394

A page of frames might look like this. 

2395

I think you can guess which one to click on.

2396

2397

<P>

2398

Frame {navigation}

2399

<br>

2400

Frame {main}

2401

<br>

2402

Frame {bottom}

2403

2404

<P>

2405

I thought about a FetchFrame feature that fetches all the frames and presents them in one go,

2406

just as they are all displayed on the screen for a sighted user,

2407

but this feature is <em>very</em> difficult to implement,

2408

and so far, nobody seems to want it. 

2409

So as you might imagine, it's way down on the list.

2410

2411

<H3 align=center> <A NAME=js> Introduction to Javascript </A> </H3>

2412

2413

Javascript is software, embedded in the web page, that runs on your computer. 

2414

These functions do not run on the web server,

2415

they run right on your box. 

2416

Hence it is sometimes called client side javascript. 

2417

And javascript can do almost anything. 

2418

You could, for instance, download a web page that includes a javascript function to compute the digits of pi,

2419

right on your computer,

2420

although that would be rather silly. 

2421

Most of the time javascript is used to validate and/or modify forms,

2422

or create fancy visual effects.

2423

2424

<P>

2425

The first version of edbrowse, written in perl, ignored javascript completely,

2426

and that was ok for a while,

2427

but more and more sites use javascript,

2428

and these websites were simply inaccessible. 

2429

Most of the e-commerce sites fall into this category. 

2430

If you want to make purchases, or manage your bank account online,

2431

you <em>need</em> a javascript enabled browser.

2432

2433

<P>

2434

The second version of edbrowse, written in C,

2435

and indicated by a version number that starts with 2,

2436

included a home grown javascript compiler and engine

2437

that I wrote myself. 

2438

This worked pretty well, for a spare time project,

2439

but javascript evolves, like any other language or standard,

2440

and I just couldn't keep up.

2441

2442

<P>

2443

The third version, which is the "latest and greatest", uses a javascript engine from Mozilla.com,

2444

which is open source under the Mozzilla Public License. 

2445

This allows me to leverage, rather than reinvent, some 70,000 lines of code -

2446

and somebody else is maintaining that code as javascript evolves. 

2447

this illustrates the power of the open source community.

2448

2449

<P>

2450

Edbrowse does not support all the features of client side (DOM) javascript,

2451

and it never will. 

2452

For example, many websites use javascript to change images

2453

on the fly as you move your mouse around the screen. 

2454

This has no meaning in edbrowse. 

2455

Other websites bring up multiple windows,

2456

and let you control the contents of subwindows using icons in a master window. 

2457

This would be very difficult to simulate in a command-line environment -

2458

so we don't try.

2459

2460

<P>

2461

As a rough approximation, I expect to implement about half of javascript,

2462

the half that will satisfy 95% of the websites we care about. 

2463

So you may see warning messages about this or that feature not supported. 

2464

If you are tired of wading through these messages,

2465

or if a bug in my javascript interpreter causes edbrowse to crash completely,

2466

you can turn javascript off via the `js' command. 

2467

This is useful when you are casually surfing the net, looking for information,

2468

and you know you're not going to need javascript. 

2469

You can also disable javascript for specific domains. 

2470

This will be discussed later, when we describe the edbrowse config file.

2471

2472

<H3 align=center> <A NAME=valid> Validating Forms </A> </H3>

2473

2474

When a web page asks for user input,

2475

it often includes a

2476

"validate&submit" function. 

2477

This function checks your entries:

2478

have you filled in all the riquired fields -

2479

is there an @ sign in your email address -

2480

are there 5 digits in your zip code -

2481

and so on. 

2482

If there are no errors, it submits the form. 

2483

These functions usually behave well under edbrowse. 

2484

When you push the button, you will either see the error message,

2485

or the form will be submitted,

2486

and a confirmation page should appear shortly.

2487

2488

<P>

2489

In some cases the javascript function

2490

reformats your data. 

2491

It may fill in some of the "hidden" fields for you,

2492

or it may compute sales tax and adjust the purchase price accordingly. 

2493

This is more than form validation, this is active javascript,

2494

and the data won't be right unless the javascript runs properly

2495

on your computer. 

2496

More and more sites are using active javascript,

2497

so a javascript enabled browser is a must.

2498

2499

<P>

2500

Some javascript functions manage menus dynamically. 

2501

Make a primary selection,

2502

and javascript populates a second dropdown list with options

2503

corresponding to your first selection. 

2504

You can now make a second selection,

2505

which further refines your search. 

2506

If the first menu presents "meats", "vegetables", "fruits", and "grains",

2507

and you select fruits,

2508

the second menu might contain

2509

"apples", "oranges", "lemons", etc. 

2510

Javascript makes this possible. 

2511

Unfortunately these dynamic menus are not yet supported by edbrowse.

2512

2513

<H3 align=center> <A NAME=popup> Popups and Popunders </A> </H3>

2514

2515

A popup is a window that suddenly appears in front of the window you really want to see. 

2516

It usually advertises something, and is often annoying,

2517

although in rare cases it is a necessary aspect of the website.

2518

2519

<P>

2520

You have a distinct advantage over all those other surfers with their graphical browsers. 

2521

The popup window does not open automatically. 

2522

Windows are not well defined in a command line browser anyways,

2523

so it would be folly to try to implement this feature,

2524

or any other aspect of multi-windowing for that matter. 

2525

Instead, the popup appears as a hyperlink at or near the top of the page,

2526

and you can click on it if you like, or ignore it. 

2527

This is similar to the <A HREF=#music>background music</A>, described in an earlier section. 

2528

The popup link might look like this.

2529

<P>

2530

{Popup: specials()}

2531

2532

<P>

2533

Popunders are not as common. 

2534

They appear after you have closed the window. 

2535

In some sense they are hidden "under" your web page, and when you close the page they pop out. 

2536

In edbrowse, this does not happen automatically. 

2537

When you type q, you quit, and that's the end of it. 

2538

As you might expect, the popunder function appears as a hyperlink. 

2539

It might look like this.

2540

<P>

2541

{On Close: foo()}

2542

2543

<P>

2544

Remember, the popup link is a simple html link to another web page,

2545

while the Close link calls a javascript function on the current page. 

2546

However, this javascript function usually links to another web page,

2547

so don't be surprised if you find yourself somewhere else on the internet. 

2548

In either case, popup or popunder, you can use the back key to return to the

2549

page you were looking at. 

2550

If you need access to a popup window and the main page in parallel,

2551

use the <A HREF=#move>M command</A>.

2552

2553

<P>

2554

Javascript also includes timer functions,

2555

that fire after a specified number of seconds. 

2556

These are implemented as hyperlinks at the top of the page. 

2557

They usually manage visual effects, and are rather pointless. 

2558

The following timer might draw a star burst on the screen in 16 seconds.

2559

<P>

2560

{Timer 16: starburst()}

2561

2562

<H3 align=center> <A NAME=onc> Onchange and Undo </A> </H3>

2563

2564

When you set or change the value of an input field,

2565

the form can (optionally) call a javascript routine. 

2566

It doesn't usually, but it can. 

2567

In an earlier example, I described a primary and secondary menu. 

2568

When the first selection is made,

2569

e.g. fruits,

2570

javascript sets up the second menu commensurate with your primary selection,

2571

using the "onchange" feature.

2572

2573

<P>

2574

This is all well and good,

2575

but edbrowse has something

2576

your graphical browser does not, the undo command. 

2577

And in this context, it doesn't really work. 

2578

Change fruits to vegetables, and the second menu presents carrots and peas and the like. 

2579

Now type u for undo,

2580

and the first field reverts back to fruits,

2581

but the second menu still contains vegetables. 

2582

This is because the undo feature was originally written for the text editor. 

2583

It simply puts the text back the way it was, and has no capacity to "undo" the side effects of javascript code. 

2584

So the moral of the story, if there is one,

2585

is to set and change the values of an input form directly,

2586

and avoid the undo command, unless you're pretty sure there are no javascript side effects associated with that field.

2587

2588

<H3 align=center> <A NAME=cfg> Config File </A> </H3>

2589

2590

At startup, edbrowse reads and parses a config file. 

2591

It's ok if this file is missing, but if it is present,

2592

it has to be syntactically correct. 

2593

An error in your config file will cause edbrowse to abort. 

2594

If this happens, use the -c option to edit the config file directly. 

2595

This bypasses initialization, and places you in the editor,

2596

with the config file preloaded. 

2597

Make your corrections, write the file,

2598

quit, and invoke edbrowse again. 

2599

Repeate these steps until there are no errors,

2600

and you see the words "edbrowse ready".

2601

2602

<P>

2603

The config file is in $HOME/.ebrc. 

2604

The "eb" is shorthand for edbrowse. 

2605

You cannot rename the config file; it is what it is. 

2606

This is true on Windows as well, so make sure HOME is set.

2607

2608

<P>

2609

The config file is line oriented. 

2610

Lines begining with # are comments, and are ignored. 

2611

Blank lines are also ignored. 

2612

All other lines fall into one of 5 categories.

2613

2614

<OL>

2615

<P><LI> Define an option, using the keyword=value syntax.

2616

<P><LI> Define an edbrowse script that can be invoked from the command line,

2617

or from another script.

2618

<P><LI> An edbrowse command, that becomes part of an edbrowse script.

2619

<P><LI> Establish an email account. 

2620

This will be described later, when we talk about the email client.

2621

<P><LI> A mail filtering rule. 

2622

</OL>

2623

2624

<H3 align=center> <A NAME=keyval> Keyword = Value </A> </H3>

2625

2626

The best documentation is an example, so let's dive right in.

2627

2628

<P>

2629

Recall the section on <A HREF=#cook>cookies</A>. 

2630

You'll need a file, often called a cookie jar,

2631

to store your cookies. 

2632

The line that establishes this cookie jar might look like this.

2633

<P>

2634

jar = /home/eklhad/.ebsys/cookie-jar

2635

2636

<P>

2637

This is a simple keyword = value syntax. 

2638

It's ok if the filename has embedded spaces, or even an equals sign. 

2639

No need to quote it.

2640

2641

<P>

2642

When edbrowse sees this line in its config file, it records the location of the cookie jar,

2643

and it checks the validity of that file. 

2644

If the file is a directory (or something weird),

2645

or is otherwise inaccessible,

2646

edbrowse prints an error message and aborts. 

2647

If this happens,

2648

use the -c option to edit your config file,

2649

and change the cookie jar.

2650

2651

<P>

2652

Here are some additional name=value directives. 

2653

Some of these are used to set up an email account. 

2654

This will become clearer when we talk about the mail client.

2655

2656

<P>

2657

certfile = /home/eklhad/.ebsys/ssl-certs

2658

2659

<P>

2660

Specify the file that holds the certificates for secure connections. 

2661

This was explained in the section on <A HREF=#ssl>secure connections</A>.

2662

2663

<P>

2664

maildir = /home/eklhad/mbox

2665

<P>

2666

Go to this directory when fetching mail. 

2667

thus, if you save a mail message, you'll always know where it is.

2668

2669

<P>

2670

webtimer = 30

2671

<br>

2672

mailtimer = 180

2673

2674

<P>

2675

Wait 30 seconds for a response from a web server, and 3 minutes for a response from the mail server. 

2676

A time value of 0 waits forever. 

2677

Sorry, there seems to be no way to interrupt a socket call,

2678

other than control backslash (quit), which kills the entire program. 

2679

That's why these timers are here - so you don't hang forever. 

2680

The defaults are 20 and 0 respectively.

2681

2682

<P>

2683

nojs = space.com

2684

<P>

2685

Specify domains that don't need javascript. 

2686

You can eliminate annoying error messages and speed up access

2687

by disabling javascript for certain websites. 

2688

Javascript will not be run on pages within these domains,

2689

nor will it be fetched from these domains.

2690

2691

<P>

2692

The above directive will also drop javascript from subdomains such as www.space.com.

2693

2694

<P>

2695

You can include a path or partial path after the domain, as in space.com/popups. 

2696

This will block the popup ads that you don't want to see, and often generate edbrowse errors in any case. 

2697

Subdomains are not considered when a path is given; the domain must match exactly.

2698

2699

<P>

2700

inserver = pop3.some-domain.com

2701

<br>

2702

inport = 110

2703

<br>

2704

outserver = smtp.some-domain.com

2705

<br>

2706

outport = 25

2707

<P>

2708

Specify the machines and ports that you use to fetch mail and send mail respectively. 

2709

You can use the fully qualified domain names, or aliases, as defined in /etc/hosts. 

2710

The ports shown here are standard, and almost always correct. 

2711

They are also default in edbrowse, so you need not set inport and outport unless they are different from that shown above. 

2712

Note, these keywords are only valid in the context of a mail account, as indicated by mail{}.

2713

2714

<P>

2715

login = eklhad

2716

<br>

2717

password = secret

2718

<P>

2719

Specify the login and password that edbrowse uses to fetch your mail.

2720

2721

<P>

2722

from = Karl Dahlke

2723

<br>

2724

reply = karl.dahlke@some-domain.com

2725

<P>

2726

These lines are added in to the emails that you send. 

2727

They tell the recipient who you are, and how to reply. 

2728

It is

2729

2730

illegal</A> to use these lines for deceptive purposes. 

2731

Make sure they identify you, and that the reply address is indeed one of your email accounts.

2732

2733

<P>

2734

adbook = /home/eklhad/.ebsys/address-book

2735

<P>

2736

When specifying recipients, you can use aliases instead of full email addresses. 

2737

Aliases are checked against your address book,

2738

a line oriented text file that is specified here. 

2739

If your address book contains the line

2740

<P>

2741

fred : fred.flintstone@bedrock.us : 226 cobblestone way : 5553827

2742

<P>

2743

then you can use the alias fred,

2744

and edbrowse will substitute Fred's email address when sending mail. 

2745

Only the first two fields in the address book are significant

2746

as far as edbrowse is concerned. 

2747

Other fields might hold phone/fax numbers, street address, etc. 

2748

It's up to you.

2749

2750

<P>

2751

spamcan = /home/eklhad/.recycle/save-spam

2752

<P>

2753

There is no perfect spam filter. 

2754

But I can't live without one,

2755

so I wrote a simple ip blocker. 

2756

(This is discussed below.) 

2757

When spam is received,

2758

edbrowse prints the line "spam from such and so",

2759

and saves the mail in this file. 

2760

If you recognize the name, spam from your friend,

2761

you can call up this file, find the email, and read it. 

2762

This should not happen, as there is no particular reason to block the ip address of your friend's computer,

2763

but hey, better safe than sorry.

2764

2765

<P>

2766

ipblack = /home/eklhad/.ebsys/ip-blacklist

2767

<P>

2768

A line oriented text file holds the ip addresses of known porn/spam sites. 

2769

The syntax is the usual: numbers separated by dots,

2770

with an optional /xx netmask indicator at the end. 

2771

If the file contains the following two lines,

2772

any ip address that starts with 192.168,

2773

or 10.11.12.13, are forbidden addresses.

2774

<P>

2775

192.168.0.0/16

2776

<br>

2777

10.11.12.13

2778

2779

<P>

2780

If an email refers to a website that resolves to any of these addresses it is considered spam,

2781

and flagged as such. 

2782

Let's be clear; I am not blocking email that comes from certain sources. 

2783

After all, your friend's computer may well be sending you viruses or spyware. 

2784

Rather, I screen email that has certain urls in its body. 

2785

If the button that says "cheap meds for you" leads to a forbidden website,

2786

you'll never see the email.

2787

2788

<P>

2789

Note, I use the very same blacklist in my firewall. 

2790

A shell script reads in the addresses and issues the appropriate iptables commands. 

2791

My file has some 2,000 entries. 

2792

This is large, but manageable. 

2793

If the list gets much larger, I may rebuild the kernel

2794

with the "large ip tables" option enabled. 

2795

This makes packet matching more efficient when there are many rules. 

2796

I suppose it sorts them or something.

2797

2798

<H3 align=center> <A NAME=agent> User Agent </A> </H3>

2799

2800

Every time you fetch a web page from the internet,

2801

your browser identifies itself to the host. 

2802

This is done automatically. 

2803

Edbrose identifies itself as "edbrowse/2.2.9",

2804

where the number after the slash indicates the current version of edbrowse.

2805

2806

<P>

2807

All well and good, but some websites have no respect for edbrowse,

2808

or lynx for that matter. 

2809

They won't even let you in the door unless you look like Explorere or Netscape. 

2810

Clickbank.com, a major credit card processor, is one example.

2811

<P>

2812

So what do we do? 

2813

We lie!

2814

2815

<P>

2816

You can specify different agents in your .ebrc file,

2817

and activate them with the `ua' (user agent) command. 

2818

If the following lines are in your .ebrc file,

2819

you can type ua1 to pretend to bee lynx,

2820

and ua2 to pretend to be Mozilla. 

2821

Type ua0 to resurrect the standard edbrowse identification. 

2822

Let's hope there aren't too many asinine websites out there,

2823

like Clickbank, that force us to lie. 

2824

It's just so stupid, and pointless.

2825

2826

<P>

2827

agent = Lynx/2.8.4rel.1 libwww-FM/2.14

2828

<br>

2829

agent = Mozilla/4.0 (compatible; MSIE 5.5; Windows 98; Win 9x 4.90)

2830

2831

<P>

2832

This feature was written pre-javascript,

2833

and is not 100% compatible with the navigator object. 

2834

Navigator.userAgent returns the correct string, according to the agent you select,

2835

but other aspectss of the navigator object do not change with the agent,

2836

and they should.

2837

2838

<H3 align=center> <A NAME=script> Edbrowse Functions </A> </H3>

2839

2840

You can bundle a set of edbrowse commands together under one name,

2841

similar to a macro. 

2842

If the following appears in your .ebrc file,

2843

you can type <ud to undos a file.

2844

<P>

2845

function:ud {

2846

<br>

2847

  ,s/\r$//

2848

<br>

2849

}

2850

2851

<P>

2852

The new < command is suppose to remind you of redirection,

2853

i.e. read input commands from this macro. 

2854

And macros can invoke other macros,

2855

by using a < command in the body. 

2856

Almost any edbrowse command is fair game. 

2857

A macro can fetch web pages from the internet,

2858

fill out forms, submit requests, and send mail.

2859

2860

<P>

2861

Normally, edbrowse marches along, whether a command succeeds or not. 

2862

However, you can tell a macro to stop if it encounters an error

2863

by using this syntax.

2864

<P>

2865

function+hw {

2866

<br>

2867

  /hello/p

2868

<br>

2869

  /world/p

2870

<br>

2871

}

2872

2873

<P>

2874

The plus sign after the word function means each command in that function must succeed. 

2875

If there is no line containing the word hello, the function stops. 

2876

If there is such a line, then the function moves on,

2877

and looks for a line containing the word world.

2878

2879

<P>

2880

Other than some indenting, the format is fixed, and unforgiving. 

2881

You cannot, for instance, put the opening brace on its own line, as K&R would suggest.

2882

2883

<P>

2884

These functions, or macros, can accept parameters. 

2885

Let's make the previous function a bit more general.

2886

<P>

2887

function+hw {

2888

<br>

2889

  /~1/p

2890

<br>

2891

  /~2/p

2892

<br>

2893

}

2894

2895

<P>

2896

You can reproduce the earlier behavior by typing <hw hello world. 

2897

Or you can search for different lines by invoking <hw foo bar. 

2898

The latter looks for a line containing foo and prints it,

2899

and if this succeeds it looks for a line containing bar and prints that. 

2900

Let's build a more useful function, a shortcut to google. 

2901

The variable ~0 represents all the arguments together. 

2902

In this case ~0 is the keywords you pass to google, for your search.

2903

<P>

2904

function+gg {

2905

<br>

2906

  b www.google.com/search?q=~0&hl=n&btnG=Google+Search&meta=

2907

<br>

2908

}

2909

2910

<P>

2911

With this in place, you simply type `<gg kangaroo habitat'

2912

to find out where kangaroos live.

2913

2914

<P>

2915

Finally, an edbrowse function can branch,

2916

based upon the success or failure of the previous command. 

2917

Use if(*) for success, and if(?) for failure. 

2918

The ? is suppose to remind you of the question mark that you get when an edbrowse command fails. 

2919

The following looks for a line containing foo, and if it finds one,

2920

it advances to the next line, and if that line contains bar, it deletes it.

2921

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+silly {

2922

/foo/

2923

if(*) {

2924

+s/bar//

2925

if(*) {

2926

d

2927

}

2928

}

2929

}

2930

</font></PRE>

2931

2932

<P>

2933

I deliberately used function+ instead of function: in the above example. 

2934

Normally the + will cause the function to abort if an edbrowse command fails. 

2935

However, if the result of that command is used by a control statement,

2936

the function does not abort. 

2937

This is similar to set -e in the shell,

2938

which causes a script to abort,

2939

unless the result of the command is used by an if statement.

2940

2941

<P>

2942

Other control statements include while(*) while(?) until(*) and until(?). 

2943

The following deletes lines from the top of the file,

2944

as long as they contain foo or bar. 

2945

It then deletes the blank lines at the top.

2946

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+topclean {

2947

until(?) {

2948

1g/foo\|bar/d

2949

}

2950

until(?) {

2951

1g/^$/d

2952

}

2953

}

2954

</font></PRE>

2955

2956

<P>

2957

You can use loop(100){ ... } to repeat a set of commands 100 times. 

2958

I haven't used this feature very often.

2959

2960

<H3 align=center> <A NAME=init> The Init Script </A> </H3>

2961

2962

The script named "init" is run at edbrowse startup. 

2963

You can use this to establish your default settings - even read in your bookmark file,

2964

so your "favorites" are close at hand. 

2965

Here is an example.

2966

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+init {

2967

# turn debug off, so we don't see any status messages from this script

2968

db0

2969

# Assume directories can be modified

2970

dw

2971

# Put beginning and end markers around listed lines

2972

el

2973

# Let session 99 hold your favorites, ready to surf.

2974

e99

2975

b $bookmarks

2976

# back to session 1, ready to go to work

2977

e1

2978

# Restore debug level to something reasonable, 1 or 2

2979

db1

2980

}

2981

</font></PRE>

2982

2983

<P>

2984

This is just a sample. 

2985

Put anything you like in your init script,

2986

or leave it out altogether if you are happy with edbrowse out of the box.

2987

2988

<H3 align=center> <A NAME=ma> Mail Accounts </A> </H3>

2989

2990

The next chapter describes edbrowse as a mail client,

2991

so let's use the config file to define your email accounts. 

2992

You can define several accounts, as necessary. 

2993

They are implicitly numbered,

2994

in the order they appear in the config file. 

2995

So the first mail account becomes #1, the second becomes #2, and so on.

2996

2997

<P>

2998

We already discussed the relevant keywords for an email account. 

2999

All you have to do is enclose them in mail{...}, like this.

3000

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>mail {

3001

default

3002

inserver = pop3.some-domain.com

3003

outserver = smtp.some-domain.com

3004

login = eklhad

3005

password = secret

3006

from = Karl Dahlke

3007

reply = karl.dahlke@some-domain.com

3008

}

3009

</font></PRE>

3010

3011

<P>

3012

The "default" directive makes this account the default. 

3013

One and only one account should be labeled default. 

3014

If you do not specify an account when fetching or sending mail, the default account is used. 

3015

Beyond this, the default smtp server is <em>always</em> used to send mail,

3016

no matter which account you specify. 

3017

If account #1 is default, and you send mail using account #3,

3018

the name and reply address from account #3 will be sent to the recipient,

3019

and if he replies, his reply will be sent to your third email account. 

3020

However, the smtp server from your default account is always used to physically transmit the message. 

3021

There are technical reasons for doing this,

3022

that are beyond the scope of this document. 

3023

Trust me, it's the right thing to do.

3024

3025

<P>

3026

Mail filtering, by sender and/or subject,

3027

is controlled by your config file as well. 

3028

This will be <A HREF=#filter>described later</A>,

3029

as part of the fetchmail client.

3030

3031

<H3 align=center> <A NAME=mt> Mime Descriptors </A> </H3>

3032

3033

Mime types are determined by the extension of the file, or in some cases the protocol. 

3034

They might tell edbrowse to use /usr/bin/play to play file.wav or file.voc,

3035

and /usr/bin/mpg123 to play file.mp3, and so on. 

3036

Rather than repeat it all here, I suggest you look at the mime {...} sections in the sample config file provided below. 

3037

Linux users can probably copy this part directly into their own config file. 

3038

It generally does the right thing. 

3039

Here is one example.

3040

3041

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>mime {

3042

type = audio/mp3

3043

desc = audio file in mp3 format

3044

suffix = mp3

3045

program = mpg123 -q -

3046

}

3047

</font></PRE>

3048

3049

<P>

3050

If you have pulled down a file from the internet that ends in .mp3,

3051

type `pb' to play the contents of the buffer. 

3052

The data is piped into the program,

3053

whose options tell it to expect data from standard in. 

3054

If the mp3 player works better from a file,

3055

use a trailing percent to turn the buffer into a temp file with the proper suffix.

3056

3057

<P>

3058

program = mpg123 -q %

3059

3060

<P>

3061

The command `pb' could mean process buffer,as well as play buffer. 

3062

For instance, a mime descriptor might unzip a zip archive.

3063

3064

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>mime {

3065

type = data/zip

3066

desc = a compressed zip archive

3067

suffix = zip

3068

# use %, since unzip cannot read data from standard in

3069

program = unzip %

3070

}

3071

</font></PRE>

3072

3073

<H3 align=center> <A NAME=sampcfg> A Sample Config File </A> </H3>

3074

3075

The best documentation is an example,

3076

so I have provided a sample config file with fake data. 

3077

It is well commented. 

3078

You can download a copy <A HREF=sample.ebrc>here</A>.

3079

3080

3081

3082

You can email the contents of your current editing session to someone else

3083

via the `sm' command. 

3084

Your email accounts are described in your <A HREF=#cfg>config file</A>.

3085

3086

<P>

3087

The contents of your .signature file, in your home directory, are automatically appended. 

3088

This is standard behavior for Unix mail clients.

3089

3090

<P>

3091

The recipients, attachments, and subject must appear at the top of your file. 

3092

The sm command is picky, so observe the following syntax carefully.

3093

3094

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>To: fred.flintstone@bedrock.us

3095

CC: barney.rubble@bedrock.us

3096

account: 1

3097

attach: hollyrock-brochure.pdf

3098

Subject: Hollyrock Vacation

3099

Come visit Hollyrock.

3100

Brochure attached.

3101

Sincerely,

3102

Rock studios incorporated.

3103

</font></PRE>

3104

3105

<P>

3106

The account line is optional. 

3107

It tells edbrowse to use the first mail account specified in your .ebrc config file. 

3108

If you don't include an account: line,

3109

edbrowse uses the default account, indicated by "default" in your .ebrc file.

3110

3111

<P>

3112

Typing sm5 causes edbrowse to use account number 5

3113

in your config file. 

3114

This overrides the account: line in your file, if there is one. 

3115

It is often easier to type sm5 than to insert an account:5 line. 

3116

Note, sm-5 is the same as sm5, but the .signature file is not included. 

3117

Sometimes you want a different ending on your email, for a particular situation.

3118

3119

<P>

3120

Use the attach: lines to add attachments to your email. 

3121

Each line should specify a file to attach,

3122

and they must appear before the subject line. 

3123

If the filename is simply a number,

3124

the corresponding edbrowse session is used instead. 

3125

Return to the earlier example,

3126

where we are trying to attach a Hollyrock brochure. 

3127

Another way to do this is to switch to session 2 and read in the pdf file. 

3128

This is a binary file, but that doesn't matter. 

3129

Don't try to edit it, just hold it in session 2. 

3130

Then switch back to session 1 and use the line attach:2.

3131

3132

<P>

3133

If you use attach:2, instead of attach:hollyrock-brochure.pdf,

3134

Fred will notice one difference. 

3135

The attachment is not prenamed for him. 

3136

If he wants to save the attachment,

3137

he'll have to come up with a filename himself. 

3138

Other than that, the email looks the same.

3139

3140

<P>

3141

The alt: directive is almost the same as the attach: directive. 

3142

If you use alt:, the attachment is not treated as an adjunct file. 

3143

Instead, it is an alternate representation of the same email. 

3144

The mail client will use the alternate representation if it can. 

3145

This is usually used to send multimedia email,

3146

with hyperlinks and pictures etc. 

3147

The primary email is in plain text,

3148

but the alternate attachment is in html or rich text. 

3149

Unless something is amiss, the user sees the alternate presentation,

3150

complete with graphics and hyperlinks.

3151

3152

<P>

3153

Like attachments,

3154

the alt: line can refer to a file or an edbrowse session.

3155

3156

<P>

3157

As you may have guessed,

3158

the to: lines establish the recipients. 

3159

Please don't specify more than a few recipients. 

3160

Some servers, my mail server included,

3161

set a hard limit of 100 on the number of recipients. 

3162

If you exceed this number,

3163

the remaining recipients simply don't get their mail. 

3164

Best to limit your "to:" lines to a couple dozen.

3165

3166

<P>

3167

Remember that CC stands for carbon copy. 

3168

This tells the recipient, in this case Barney Rubble,

3169

that he is receiving a copy of the email for his convenience;

3170

he need not respond. 

3171

Use BCC for blind carbon copy, so that each person does not see all the other email addresses.

3172

3173

<P>

3174

When specifying recipients, you can use aliases instead of full email addresses. 

3175

Aliases are checked against your address book,

3176

a text file that is specified in your .ebrc file. 

3177

If your address book contains the line

3178

<P>

3179

fred : fred.flintstone@bedrock.us : 226 cobblestone way : 5553827

3180

<P>

3181

then you can simply write "To:fred" at the top of your file. 

3182

Only the first two fields in the address book are significant

3183

as far as edbrowse is concerned. 

3184

Other fields might hold phone/fax numbers, street address, etc.

3185

<P>

3186

Note that "Reply to fred" is an alternate syntax for "to: fred".

3187

3188

<P>

3189

Some web pages include sendmail links. 

3190

They look just like other hyperlinks, but they send email to the appropriate person. 

3191

Click here for

3192

3193

technical details</A>.

3194

3195

<P>

3196

If you activate a sendmail link,

3197

you will be placed in a new editing session with the "to" and "subject" lines preloaded. 

3198

If the url did not specify a subject,

3199

the subject is simply "Hello". 

3200

You will probably want to replace this with a better subject line. 

3201

Write your mail message and type `sm' to send it on its way. 

3202

Then type ^ to return to the web page you were looking at. 

3203

Note that the body of your email may also be preloaded with some default text,

3204

so be sure to check before you write and send.

3205

3206

<P>

3207

You can include attachments by placing "attach:" lines at the top of the file,

3208

assuming the recipient can handle these attachments. 

3209

This might make sense when the sendmail link is asking for {bug reports} -

3210

you might attach a program and/or its output. 

3211

Yet this is somewhat unusual. 

3212

Most sendmail links expect a few sentences of feedback, and nothing more.

3213

3214

<P>

3215

Some web forms are submitted via email, rather than a direct http transmission. 

3216

Edbrowse handles this properly. 

3217

It shows you the destination email address,

3218

sends the mail through smtp,

3219

and tells you to watch for a reply. 

3220

This reply could be an email response, or even a phone call

3221

if you provided your phone number in the form. 

3222

But remember, nothing happens immediately. 

3223

You are still on the same web page, still looking at the same submit button. 

3224

Don't push the button again! 

3225

The mail has been sent,

3226

and you'll be hearing from the company in the next few days.

3227

3228

<H3 align=center> <A NAME=smc> Send Mail Client </A> </H3>

3229

3230

as described in the previous section,

3231

edbrowse incorporates the features of a mail client. 

3232

In addition to the interactive `sm' command,

3233

you can send mail in a batch fashion, from the command line. 

3234

If fred and barney are in your address book,

3235

and you want to send them mail from the command line, with an attachment,

3236

using your primary email account, do this. 

3237

(I'm assuming e has been aliased to an edbrowse executable.)

3238

<P>

3239

e -m1 fred ^barney hollyrock-notice +hollyrock-brochure.pdf

3240

3241

<P>

3242

The ^ in front of barney means he is a CC recipient. 

3243

Use "?barney" for BCC.

3244

3245

<P>

3246

Files with a leading + are assumed to be attachments. 

3247

If they are binary they will be encoded properly,

3248

according to the mime standard. 

3249

A leading - indicates an alternate format, like this.

3250

3251

<P>

3252

e -m1 fred ^barney hollyrock-notice -hollyrock-graphical.html

3253

3254

<P>

3255

Remember, you can specify several mail accounts in your .ebrc file. 

3256

The first account is indicated by index 1, as in -m1, and so on. 

3257

You can make your life a lot easier with some aliases in your .bashrc file.

3258

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif># My mail, home account

3259

alias mymail="e -m1"

3260

# My wife's account.

3261

alias wifemail="e -m2"

3262

# My work account.

3263

alias workmail="e -m3"

3264

# mail is obsolete

3265

alias mail="echo use mymail, wifemail, or workmail"

3266

</font></PRE>

3267

3268

<H3 align=center> <A NAME=fmc> Fetch Mail Client </A> </H3>

3269

3270

If edbrowse is run with the -m1 option, and no other arguments,

3271

it is an interactive fetch mail client,

3272

retrieving mail from your first pop3 account. 

3273

The first thing it tells you is how many messages you have. 

3274

If there are no messages it says "No mail", and exits. 

3275

If there are messages, it retrieves each one in turn. 

3276

For each message, it displays some header information (such as subject

3277

and sender) and the first page of text, and then presents a prompt. 

3278

A '?' prompt means the message is complete --

3279

a '*' prompt means there is more text to read. 

3280

You respond by hitting a key. 

3281

Keys have the following meaning.

3282

3283

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>? summary of key commands

3284

q quit the program

3285

x abort the program, deleted mail is not really deleted

3286

space display more text

3287

n read the next message

3288

d delete this message

3289

i show referenced ip addresses, then delete this message

3290

j junk this message, and any messages with this subject, for 10 days

3291

J junk this subject for a year

3292

w write this message to a file and delete it

3293

k keep this message in a file, but don't delete it

3294

u write this message unformatted to a file and delete it

3295

</font></PRE>

3296

3297

<P>

3298

The last three commands, k w and u, require a filename, which you enter. 

3299

The reserved filename "x" is essentially /dev/null,

3300

whence the mail message is discarded. 

3301

You can save the mail message to x (discard) and still save the attachments. 

3302

If the file is anything other than x,

3303

and the program cannot write to the specified file, it asks you for a new filename. 

3304

Note that capital X will do the same thing.

3305

3306

<P>

3307

The junk command adds a filter rule to your config file,

3308

sending any message with this subject to oblivion. 

3309

This is useful when you don't want to read a particular discussion thread in a mailing list. 

3310

Use the j command to junk it for ten days. 

3311

If the subject pops up again in two months, you might be interested. 

3312

Use the capital J command to junk a subject for a year. 

3313

This is typically used for spam subjects, such as

3314

"Cheap meds for you."

3315

3316

<P>

3317

Issue the i command when the mail is obviously porn/spam. 

3318

You will see the ip addresses, which you can add to your blacklist file. 

3319

This is not done automatically, because I believe in a certain amount of manual control over the process. 

3320

For example, if you, as a human, notice that you have blocked out

3321

7 addresses starting with 10.16.29,

3322

you may want to get rid of those rules and replace them with the single rule 10.16.29.0/24. 

3323

There is a slight risk in doing this,

3324

since a valid address might be nestled in amongst all these spam sites. 

3325

But it's not likely. 

3326

In fact, I sometimes take a leap of faith and exclude an entire two-byte block. 

3327

That's 65,536 websites that are locked out of my computer, for email or browsing. 

3328

A bit heavy handed perhaps, but I really hate all this spam and spyware crap!

3329

3330

<P>

3331

If one of those 65,536 addresses turns out to be valid,

3332

use a bang to negate the sense of the address, like this.

3333

3334

<P>

3335

10.5.33.177!

3336

<br>

3337

10.5.0.0/16

3338

3339

<P>

3340

Doing these ip lookups in real-time can slow the process of fetching your mail. 

3341

You can disable the whole thing by omiting, or commenting out, the ipblack= line in your config file.

3342

3343

<P>

3344

IP filtering only works for hyperlinks. 

3345

If an email has an online form that is submitted to a forbidden site, I don't detect that. 

3346

I should though - as these are the most dangerous emails of all. 

3347

They pretend to come from your bank, then send your account numbers to a thief in Russia. 

3348

So yes, this form of ip blocking is on my list of fun things to do.

3349

3350

<P>

3351

Like spam keywording, ip blocking is no panacea. 

3352

For example, a spammer with half a brain can sign up for http redirection at no cost. 

3353

Suddenly the domain in the email does not reflect the true destination at all. 

3354

I could add software to pull down the html page and test for redirection,

3355

but that would <em>really</em> slow down the interactive mail process. 

3356

Beyond this, a spammer can use javascript to assemble his destination url on the fly,

3357

and as you know, there is no way to anticipate the actions of a javascript program and pre-determine the destination url. 

3358

And so, the arms race continues,

3359

and just like the real world, the offensive team will always have the upper hand.

3360

3361

<H3 align=center> <A NAME=mailfmt> Formatted Mail </A> </H3>

3362

3363

By default, incoming mail is formatted for readability. 

3364

If you want to save a copy of the mail, exactly as it was received (unformatted),

3365

type u at the interactive prompt. 

3366

If you don't want the formatting at all, use the -u option on the command line,

3367

as in `e -um1'. 

3368

This is occasionally necessary,

3369

if a bug in my formatting routine causes edbrowse to blow up. 

3370

You still want to get your mail,

3371

(and send me a copy so I can fix the bug),

3372

so use the -u option to bypass formatting.

3373

3374

<P>

3375

When an html mail message is rendered, javascript is disabled. 

3376

Thus the mail appears sooner, and the mail client is less likely to crash due to a bug in the javascript machinery. 

3377

There really isn't much loss here, because you couldn't activate the links or fill out the form anyways. 

3378

If you want to "interact" with this email message,

3379

you have to save it unformatted to a file,

3380

finish your email session, edit that file,

3381

and type b to browse. 

3382

Now the html is active, as though you were looking at a web page on somebody's site.

3383

3384

<P>

3385

There is a reason for this falderal. 

3386

When you are running edbrowse as a fetchmail client, there is a time limit, imposed by your pop3 server. 

3387

You have about 20 seconds to decide the fate of each message. 

3388

Throw it away, skip it, save it to a file, etc. 

3389

If you doddle, the mail server hangs up and you have to start all over again. 

3390

This is not the time to interact with your message;

3391

this is not the time to fill out forms or follow hyperlinks to other interesting websites. 

3392

If you are that interested, save the message to a file and move on.

3393

3394

<P>

3395

Your sighted friend, running Outlook Express,

3396

doesn't have to worry about this, because every message is saved to a file automatically. 

3397

When he scans his mail, he is actually looking at files that have been transferred to his computer

3398

some time in the past. 

3399

He is not in the middle of a pop3 session, and there are no time limits. 

3400

This may be a better approach; I don't know. 

3401

Someday I may add a feature to grab all your messages and copy them to local files in your mail directory. 

3402

You could then use edbrowse in directory mode to step through each file in turn. 

3403

Personally, I get a lot of silly little emails, and spam too,

3404

so I am happy to delete the majority of my messages as they come,

3405

in real time,

3406

and save the few that are interesting. 

3407

Other filtering options can simplify this process. 

3408

For instance, mail from my friend Dorothy will always be saved in a particular place,

3409

because I always want to read that at my leisure. 

3410

this is described in the next section.

3411

3412

<H3 align=center> <A NAME=filter> Mail Filtering </A> </H3>

3413

3414

Your config file supports a modest level of mail filtering. 

3415

You can redirect incoming mail

3416

based upon the sender, the receiver, or the subject. 

3417

These parameters are established in your config file. 

3418

A mail filtering rule has the form:

3419

<P>

3420

matchString > destinationFile

3421

3422

<P>

3423

Actually the > is a bit misleading. 

3424

If the file exists, the email is appended to the end; the file is not truncated. 

3425

So perhaps we should use >>,

3426

but I didn't want to bother with the extra greater, over and over again.

3427

3428

<P>

3429

The destination file is interpreted relative to the mail directory,

3430

which is set in your config file. 

3431

Of course you can override with an absolute path if you wish.

3432

3433

<P>

3434

A mail filtering rule always occurs in the context of a filter block. 

3435

For instance, if you wish to redirect mail from certain people, do this.

3436

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>fromfilter {

3437

fred flintstone > fredmail

3438

fred.flintstone@bedrock.us > fredmail

3439

jerk@hotmail.com > x

3440

word@m-w.com > -wod

3441

}

3442

</font></PRE>

3443

3444

<P>

3445

You can specify the sender's name, or his email address. 

3446

It's not a bad idea to do both,

3447

in case he sends mail from some other account etc.

3448

3449

<P>

3450

Notice that I didn't capitalize Fred Flintstone. 

3451

Matches are case insensitive.

3452

3453

<P>

3454

The file name "x" is special; it discards the mail entirely. 

3455

You can use this to throw away mail from people

3456

who are constantly harassing you, or sending you spam.

3457

3458

<P>

3459

The last entry sends mail to -wod. 

3460

The leading - is special;

3461

it means the mail should be saved to wod unformatted. 

3462

This happens to be the word of the day from Merriam Webster. 

3463

I like to save it unformatted, so I can browse it,

3464

and click on {audio} to hear the word pronounced. 

3465

If an email contains hyperlinks,

3466

you may want to save it unformatted,

3467

so you can browse it later.

3468

3469

<P>

3470

You can also filter mail based on the to: field. 

3471

This is useful if you have several mail accounts,

3472

or mail aliases that are forwarded to your primary account. 

3473

Here is a sample block.

3474

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>tofilter {

3475

support@my-side-business.com > support

3476

sales@my-side-business.com > sales

3477

@my-side-business.com > business

3478

me@my-regular-dayjob.com > work

3479

}

3480

</font></PRE>

3481

3482

<P>

3483

The third entry is a catchall address,

3484

saving any mail that is sent to that domain. 

3485

Since rules are applied in order,

3486

support requests are stored in a file called "support",

3487

sales are stored in a file called "sales",

3488

and all other emails sent to your business are stored in "business".

3489

3490

<P>

3491

You can use catchall addresses in the fromfilter block as well. 

3492

Anything from this domain goes here, etc.

3493

3494

<P>

3495

You can filter based on subject, using the subjfilter{...} block. 

3496

This can close the door on the virus de jure. 

3497

If a virus uses a subject line of "Come Kiss Me",

3498

you can redirect "come kiss me" to x, and it's gone.

3499

3500

<P>

3501

You can also use this feature to block warnings from other ISPs,

3502

complaining that you sent them emails with virus attachments. 

3503

You didn't, of course, because you run linux. 

3504

You're immune! 

3505

Your reply address was forged, so the virus warning was sent back to you,

3506

but you really had nothing to do with it. 

3507

Lines like this one can throw these spurious warnings away.

3508

3509

<P>

3510

subjfilter {

3511

<br>

3512

Come Kiss Me > x

3513

<br>

3514

Net Integrator Virus Alert > x

3515

<br>

3516

}

3517

3518

<P>

3519

Finally, the reply address is checked against your address book. 

3520

If there is a match, the mail is saved in a file whose name is the email alias. 

3521

Consider a line in your address book that looks like fred:Fred.Flintstone@SomeDomain.com. 

3522

When you receive email from this particular address, it is saved to the file fred. 

3523

Thus you don't have to enter and maintain redundant entries in the filter. 

3524

There is no need to include Fred.Flintstone@SomeDomain.com > fred. 

3525

It's taken care of.

3526

3527

<P>

3528

If you want to save mail from Fred unformatted, place a minus sign,

3529

i.e. -fred, in your address book. 

3530

This is the same convention as the from filter. 

3531

If you don't want mail from Fred to be redirected,

3532

but you still want to use the alias fred when sending mail,

3533

place an exclamation mark at the start, i.e. !fred.

3534

3535

<P>

3536

Note that mail filtering occurs before spam detection. 

3537

Thus mail from your friend,

3538

or to your business,

3539

will always be saved in a file,

3540

even if it references a forbidden website.

3541

3542

<P>

3543

If an email is redirected to a file, and it includes attachments,

3544

edbrowse will ask you what to do with those attachments,

3545

as though you had used the w command to save the mail yourself. 

3546

If your friend has send you a program (attached) that he wants you to look at, just hit return

3547

to save it to the default filename. 

3548

If your friend's mail has some kind of logo, or background image, that you don't care about,

3549

just type x and it will go away. 

3550

If the image has a recognizable suffix, such as gif, I discard it automatically. 

3551

If you really want these images, you'll have to save the email unformatted, and browse it later.

3552

3553

<P>

3554

When brousing an email inside the editor,

3555

edbrowse offers you all the attachments, be they images or not. 

3556

You can discard a single attachment by entering x,

3557

or all the image attachments by entering capital X.

3558

3559

<P>

3560

Use the -p option to pass over the filters, as in `e -pm1'. 

3561

This also stops spam detection. 

3562

I set this when looking at other people's mail, such as my wife's account. 

3563

I don't want her mail sent somewhere else because it matches one of my filter rules.

3564

3565

<H3 align=center> <A NAME=sqlb> Building edbrowse with Database Access </A> </H3>

3566

3567

If you simply type make, you get edbrowse, with no database interface. 

3568

Two other targets support database access. 

3569

Run either `make edbrowseodbc' or make `edbrowseinf'. 

3570

The former uses odbc to access just about any sql database,

3571

and the latter uses the

3572

<A HREF=http://www.informix.com>Informix</A> interface. 

3573

If you would like to test the odbc interface,

3574

or write a new interface, e.g. for Oracle or mysql,

3575

I will be eternally grateful. 

3576

You are basically implementing the interface described in dbapi.h,

3577

using the C database development toolkit provided by the vendor. 

3578

The easiest way to proceed is to copy one of the two files that is already there,

3579

dbinfx.ec or dbodbc.c, and make changes as necessary.

3580

3581

<H3 align=center> <A NAME=rtb> Reading Tables </A> </H3>

3582

3583

When a file name is of a certain format, with the http:// in front etc,

3584

it is deemed to be a url. 

3585

Edbrowse does not look on your computer for the file; it goes out to the internet. 

3586

Similarly, when the file name has a certain format,

3587

it is assumed to be a table or view in the database. 

3588

If you have a table called customers, you follow it up with a right bracket.

3589

3590

<P>

3591

e customers]

3592

3593

<P>

3594

This allows you to bring in the entire table,

3595

or portions thereof, one row per line, with fields delimited by pipes. 

3596

If the result looks like a bunch of numbers and pipes,

3597

and you have forgottten the structure of the table,

3598

use the sc (show columns) command. 

3599

The output might look like this.

3600

3601

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>Table customers, 536281 rows

3602

1 *custnum int

3603

2 firstname string

3604

3 lastname string

3605

4 birthdate date

3606

5 sex char

3607

6 email string

3608

7 picture blob

3609

</font></PRE>

3610

3611

<P>

3612

The first column is a unique number that designates this particular customer. 

3613

After all, two customers could have the same first and last name,

3614

and even the same birthdate. 

3615

Serial numbers are <em>always</em> a good idea,

3616

and that usually becomes the primary key. 

3617

This is indicated by a star, just before the column name. 

3618

If edbrowse changes or deletes a record, the primary key is used. 

3619

I assume, at all times, that the key determines a unique record in the database,

3620

and that each record appears at most once in an editing session.

3621

3622

<P>

3623

Note that edbrowse can support a primary key with two columns, such as a serial number and a modifier. 

3624

I actually have some tables at work that look like this.

3625

3626

<P>

3627

The table syntax is more than just an identifier and a right bracket. 

3628

You can follow the right bracket with a where clause. 

3629

This is important if you don't want the entire table,

3630

especially if there are millions of rows. 

3631

Here are some table commands and their meanings.

3632

3633

<P>

3634

customers]

3635

<br>

3636

Set the buffer up for the customers table, but don't fetch any rows.

3637

3638

<P>

3639

customers]*

3640

<br>

3641

Fetch all the rows in the table.

3642

3643

<P>

3644

customers]37

3645

<br>

3646

Fetch the customer whose serial number is 37. 

3647

The primary key is assumed; your table has to have a primary key

3648

if you are going to use this syntax.

3649

3650

<P>

3651

customers]1=37

3652

<br>

3653

Fetch the row whose first column is 37.

3654

3655

<P>

3656

customers]37-59

3657

<br>

3658

Fetch the customers with serial numbers between 37 and 59 inclusive.

3659

3660

<P>

3661

customers]3=Smith

3662

<br>

3663

Fetch the customers whose last name is Smith.

3664

3665

<P>

3666

customers]lastname=Smith

3667

<br>

3668

Same as above.

3669

3670

<P>

3671

customers]last=Smith

3672

<br>

3673

Same as above. 

3674

If the string uniquely gloms onto a column name, we're all set.

3675

3676

<P>

3677

customers]last=Barn*

3678

<br>

3679

Fetch the customers whose last names begin with Barn.

3680

3681

<P>

3682

customers]birth=01/01/1960-12/31/1960

3683

<br>

3684

Fetch the customers who were born in 1960.

3685

3686

<P>

3687

It is sometimes best to edit with a blank template, i.e. without a where clause. 

3688

Then, you can read in whatever rows you like. 

3689

Type an r before any of the strings shown above to read rows into your buffer. 

3690

Note, you cannot read data from different tables into the same buffer,

3691

but you can switch to another editing session to look at another table,

3692

without losing the rows you are working on.

3693

3694

<P>

3695

When reading rows into a growing buffer, you can usually omit the table, since it has to be customers] every time. 

3696

For instance, you can bring in customer #738 by typing `r customers]738' or `r 738'.

3697

3698

<P>

3699

If you want a clean slate, type `rf' to refresh the buffer. 

3700

This brings you back to a template for the table, with no rows. 

3701

WARNING - do not clear your buffer by deleting all the rows,

3702

as that will delete the corresponding entries in the database. 

3703

This feature works just like directory mode -

3704

your edits are translated into actions in the real world, so be careful. 

3705

Referential integrity will usually save you from this accidental delete disaster,

3706

if you routinely use this sql feature to link tables together,

3707

which is a good idea at many levels.

3708

3709

<P>

3710

Now, how about the seventh column in our example, the one called "picture"? 

3711

This is the customer's picture, a jpg image that is in binary,

3712

and cannot be easily folded into an editing session. 

3713

Instead, it is stored in another buffer,

3714

e.g. buffer 9, and this is indicated by <9>. 

3715

You can switch to session 9 and save the file, or throw it away.

3716

3717

<P>

3718

2139|Fred|Flintstone|08/21/1969|M|foo@bar.bar.com|<9>

3719

3720

<P>

3721

To do anything with the database, your config file must specify

3722

the name of the database, the login, and the password. 

3723

(The last two can sometimes be omitted, if they are inferred from your identity on the computer.) 

3724

Here is how the line might look

3725

if you are tapping into the retail database, where the customers table resides.

3726

3727

<P>

3728

database = retail,mylogin,mypassword

3729

3730

<P>

3731

Although this cannot be changed on the fly, you can access other databases by vectoring through this one. 

3732

For instance, you can read the parts table in the inventory database by calling up inventory:parts]. 

3733

This is standard sql syntax for looking at tables in another database;

3734

I just pass it through.

3735

3736

<H3 align=center> <A NAME=insupd> Insert, Update, Delete </A> </H3>

3737

3738

Adding database rows is substantially different from adding text. 

3739

Since a row may contain a dozen fields, and you may not remember what goes where,

3740

edbrowse prompts you for each field in turn. 

3741

It also checks the integrity of each field as you go,

3742

e.g. a date has to look like mm/dd/yyyy etc. 

3743

If a row cannot be added because of a database error,

3744

edbrowse prints the error,

3745

and data entry continues;

3746

giving you a chance to reenter the row. 

3747

Data entry stops when you enter a period all by itself,

3748

no matter what field you are on. 

3749

The rows that were entered successfully will be present in your buffer,

3750

and the current line is the last entered row. 

3751

Note that blobs cannot be entered at this time.

3752

3753

<P>

3754

Use the substitute command to update a row. 

3755

Make sure you don't accidentally introduce an additional pipe, or remove a pipe. 

3756

Key columns cannot be modified. 

3757

If you are updating many rows with one command,

3758

through a range or through g//s,

3759

and an error occurs while updating the database,

3760

substitution stops in its tracks. 

3761

The editing session will reflect the database,

3762

with some rows changed and others untouched. 

3763

There are many reasons for these update errors, including datatype mismatch

3764

(e.g. pushing an integer into a date field), and check constraints

3765

(e.g. putting J in for sex, instead of M or F). 

3766

If you have any say in the database design,

3767

apply check constraints wherever they make sense. 

3768

They will protect you from erroneous substitutions, wich would produce inconsistent updates.

3769

3770

<P>

3771

Delete works as you would expect; delete a row,

3772

and the corresponding entry disappears. 

3773

There is no undo command. 

3774

It couldn't be done in any case, since you may have selected only part of the row (see below),

3775

and I wouldn't have all the data to put the row back. 

3776

As mentioned before, referential integrity should be employed wherever it makes sense. 

3777

As a last check, I only let you delete 100 rows at a time. 

3778

Be careful, and run regular backups.

3779

3780

<H3 align=center> <A NAME=td> Table Descriptors </A> </H3>

3781

3782

Suppose a table contains 100 fields. 

3783

Displaying all those fields is awkward, to say the least. 

3784

Sometimes you are interested in a group of 6 fields,

3785

and sometimes you are interested in another group of 8. 

3786

You can set up virtual tables, similar to views, in your config file. 

3787

The short name is the alias, and you can call up the table using this alias. 

3788

It will contain only the columns you specify. 

3789

Here are two descriptors for the aforementioned customers table.

3790

3791

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>table {

3792

tname = customers

3793

# cnm is my cryptic shorthand for customer name

3794

# I want to be cryptic here, cause I'm going to be typing this a lot.

3795

tshort = cnm

3796

cols = custnum,firstname,lastname

3797

# Specify the primary key, in this case, the first column selected.

3798

keycol = 1

3799

}

3800

3801

table {

3802

tname = customers

3803

# All I care about here is customer and birthdate.

3804

tshort = cbd

3805

cols = birthdate,custnum

3806

keycol = 2

3807

}

3808

</font></PRE>

3809

3810

<P>

3811

When inserting a row through one of these descriptors,

3812

remember that you are only specifying a subset of the columns in the table. 

3813

The other columns will be null, or they will take on their default values,

3814

as specified by the schema. 

3815

If you receive a Not-Null error, it could be due to one of the other columns,

3816

which requires an entered value. 

3817

It is usually safer to insert a row using the complete table.

3818

3819

3820

3821

That concludes the user's guide. 

3822

As you can see, edbrowse is a difficult program to master, but an easy program to use. 

3823

I believe this is the key to success for any blind user or programmer. 

3824

One can certainly paste a screen reader on top of an existing 2 dimensional program

3825

such as emacs or lynx, and get up and running quickly,

3826

but to be truly competitive in the workplace, or efficient at home,

3827

you need a <A HREF=http://www.eklhad.net/cli.html>command line interface</a>. 

3828

Edbrowse is an important step in this direction. 

3829

It doesn't address the speech adapter, or other common applications such as spreadsheets, finances, or audio systems,

3830

but it does provide a high quality text editor and a decent browser and mail client. 

3831

It's a good start.

3832

3833

<P>

3834

3835

3836

</BODY></font>