~ubuntu-branches/ubuntu/karmic/edbrowse/karmic-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, a User's Guide </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=#phil> Philosophy </A>

28

<LI><A HREF=#curve> Learning Curve </A>

29

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

30

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

31

</UL>

32

33

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

34

35

<UL>

36

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

37

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

38

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

39

</UL>

40

41

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

42

43

<UL>

44

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

45

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

46

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

47

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

48

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

49

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

50

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

51

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

52

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

53

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

54

</UL>

55

56

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

57

58

<UL>

59

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

60

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

61

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

62

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

63

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

64

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

65

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

66

67

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

68

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

69

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

70

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

71

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

72

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

73

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

74

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

75

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

76

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

77

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

78

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

79

80

</UL>

81

82

<H4> Chapter 5, Javascript </H4>

83

84

<UL>

85

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

86

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

87

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

88

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

89

</UL>

90

91

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

92

93

<UL>

94

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

95

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

96

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

97

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

98

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

99

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

100

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

101

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

102

</UL>

103

104

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

105

106

<UL>

107

108

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

109

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

110

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

111

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

112

<LI><A HREF=#reply> Mail Reply </A>

113

</UL>

114

115

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

116

117

<UL>

118

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

119

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

120

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

121

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

122

</UL>

123

124

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

125

126

Karl Dahlke

127

<A HREF=mailto:eklhad@gmail.com>eklhad@gmail.com</A>

128

129

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

130

131

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

132

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

133

as articulated by the Free Software Foundation. 

134

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

135

136

<P>

137

As a special exception, I hereby grant permission to link

138

the code of this program with the OpenSSL library

139

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

140

and distribute linked combinations including the two. 

141

You must obey the GNU General Public License in all respects

142

for all of the code used other than OpenSSL. 

143

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

144

program, but you are not obligated to do so. 

145

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

146

147

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

148

149

This program borrows some code and design concepts from the

150

151

links project</A>,

152

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

153

My thanks to the authors for all their hard work.

154

155

<P>

156

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

157

Their technical writing puts mine to shame. 

158

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

159

160

<P>

161

162

Writing html

163

</A>

164

165

An html Code Tutorial

166

</A>

167

168

So You Want to Write some html...

169

</A>

170

171

Javascript for Webmasters

172

</A>

173

174

Javascript, the Definitive Guide

175

</A>

176

177

<P>

178

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

179

You can

180

181

download it here</A>. 

182

Programmers and maintainers of this package should take advantage of the

183

184

online documentation</A>.

185

186

<H3 align=center> <A NAME=phil> Philosophy </A> </H3>

187

188

Edbrowse is part of a larger philosophy,

189

wherein editers, browsers, mail clients, spreadsheets, and other critical applications

190

are rewritten, from the ground up if necessary,

191

to support various disabilities. 

192

Once this is done,

193

Other applications

194

can leverage these tools,

195

and be immediately accessible to a wide range of computer users. 

196

You can read more about this philosophy

197

<A HREF=philosophy.html>here</A>.

198

199

<H3 align=center> <A NAME=curve> Learning Curve </A> </H3>

200

201

Here is what William McEwan

202

of the

203

204

murga Puppy Linux community forum</A>

205

has to say about edbrowse. 

206

(Reprinted here with permission.)

207

208

<P>

209

"The first few days I tried to use this program (based partly on the old UNIX

210

ed) I thought I was in a living nightmare. 

211

But once the sun began to shine, I began to wonder:

212

is this apparently simple program actually one of the best programs out there? 

213

Depends on the definition of best of course. 

214

No graphics here, but no Gnome/KDE/Microsoft bloat either. 

215

No X required. 

216

But it covers so many daily needs: text editing, web-browsing, email,

217

database access, file management, ftp. 

218

Sure, it has its limitations,

219

limited javascript support and so on,

220

but it also comes with much potent magic. 

221

A learning curve, sure, took me two full days, and I'm still learning,

222

but its so easy now. 

223

I can literally do it with my eyes closed. 

224

Prepare for some pain. 

225

Survive it, and enjoy its pleasures."

226

227

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

228

229

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

230

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

231

actually running my program. 

232

But as you proceed

233

you will eventually discover some discrepancies,

234

areas where my program differs from ed. 

235

(These are discussed below.)

236

237

<P>

238

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

239

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

240

a browser embedded inside ed. 

241

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

242

and activate browse mode to render the html tags

243

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

244

In other words, we discard most of the formatting information

245

and retain the links and fill-out forms. 

246

This allows blind users to access the Internet

247

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

248

249

<P>

250

I find this approach superior to the "quick fix"

251

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

252

or graphical browser (Netscape). 

253

Of course that's just my opinion. 

254

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

255

I'm glad it works for them, but this approach is an unending source of frustration for me. 

256

If you also prefer linear applications,

257

give this browser a try.

258

259

<P>

260

This documentation assumes you are familiar with ed. 

261

In fact it helps if you are fluent in ed. 

262

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

263

264

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

265

266

First, a few words about character sets (charsets). 

267

English is easily contained within a byte stream, one letter per byte. 

268

Furthermore, each letter fits in 7 bits; the eighth bit is not needed, and is set to 0. 

269

However, the

270

271

Indo-european languages</A>

272

bring in more characters,

273

such as ñ (Spanish), è (French),

274

and ö (German). 

275

These can still fit within single bytes,

276

by setting the 8<font size=3><sup>th</sup></font> bit to 1, according to the

277

278

ISO8859-1</A> standard. 

279

However, another standard is taking over, at least in the Unix/Linux world. 

280

This charset,

281

known as

282

283

utf8</A>,

284

packs the same European letters into two-byte sequences. 

285

Thus, within your computer, ñ is represented by either one or two bytes. 

286

This is transparent to you; you see the same letter on the screen,

287

and you hear the same sounds (if your screen reader passes these letters to a speech synthesizer). 

288

A quick way to tell which system you are on is to echo $LANG. 

289

If it contains the string utf8, or utf-8,

290

in upper or lower case,

291

your console is using utf8, and it expects two-byte sequences. 

292

Your files will contain these underlying sequences, and you (probably) aren't even aware of it.

293

294

<P>

295

There's much more to say about charsets; this is merely a brief introduction to the subject. 

296

I need not go further, because edbrowse only suppports these two systems at this time. 

297

Chinese, for example, requires 3 and 4 byte sequences, which map into unicode. 

298

Edbrowse just doesn't handle this level of complexity at this time.

299

300

<P>

301

The output and error messages,

302

such as "search string not found",

303

have been internationalized,

304

so that edbrowse can support most European languages. 

305

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

306

(It's probably already set.) 

307

Supported languages are shown below. 

308

At present we are restricted to ISO8859-1 characters,

309

facilitating many (though by no means all) of the indo-european languages,

310

as described above. 

311

If you can help translate edbrowse into these languages,

312

please let me know.

313

314

<P>

315

English: LANG=en (this is the default)

316

317

<P>

318

French: LANG=fr by

319

320

Erwin Bliesenick</A>

321

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

322

323

<P>

324

Brazilian Portuguese: LANG=pt_br by

325

326

Cleverson</A>

327

328

<P>

329

When an output or error message is displayed,

330

accented letters are printed as 8-bit bytes, i.e. ISO8859-1,

331

unless the string utf8 or utf-8 appears in $LANG,

332

whence the nonascii characters are generated using utf8. 

333

LANG=fr-FR.UTF-8 is a common settting in France. 

334

These are the only charsets that are currently supported. 

335

Similarly, the contents of a buffer, be it a local document or an internet website,

336

are displayed as 8-bit bytes or two-byte sequences,

337

according to your locale. 

338

If a file is read into edbrowse,

339

i.e. read into an empty buffer,

340

and it is currently in the "other" charset,

341

it is converted on the fly, before you ever see it. 

342

Thus it will look normal to you. 

343

If I did everything right, you shouldn't notice any difference. 

344

(Use the iu command to disable this feature.)

345

346

<P>

347

When you write data out to the same file,

348

e.g. if you have made some corrections or additions,

349

I convert it back to its original charset. 

350

Thus you can send the edited file back to your friend,

351

and it will be in his charset, as he expects. 

352

However, if you write the data, or any portion of that data, to any other file,

353

I will leave it in the charset that is used by your computer.

354

355

<P>

356

These conversions should never take place on zip files, or executable files,

357

or other forms of binary data. 

358

If you see the words

359

"converting to iso8859"

360

or "converting to utf8",

361

and the file is something other than international text,

362

we have a problem. 

363

Don't try to run the converted executable; it won't work.

364

365

<P>

366

If your world is utf8, the search function can lead to some confusion. 

367

Consider the Spanish word niño, for a boy child. 

368

If you search for ni.o, you may not find this line of text. 

369

The dot stands for one character, and should match ñ, but this accented letter takes up two bytes. 

370

Ironically, you have to search for ni..o, and you will find what you are looking for. 

371

Needless to say, this is very confusing.

372

373

<P>

374

Search and substitute is performed by the pcre library,

375

and fortunately for us, the latest version supports utf8. 

376

In other words, I can pass pcre an option that tells it to treat certain two-byte sequences as single letters,

377

and it will behave the way you want it to. 

378

Searching for ni.o will work again. 

379

Unfortunately, some older pcre packages do not have this capability built in. 

380

If this is the case, you will receive a warning message,

381

then pcre will revert back to its original one-byte-per-letter behavior. 

382

To disable the utf8 feature, and suppress this warning message, set the environment variable PCREUTF8=off.

383

384

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

385

386

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

387

This is a quick reference guide. 

388

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

389

390

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

391

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

392

!command: shell escape

393

p: print the current line

394

4,7p: print lines 4 through 7

395

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

396

kb: mark the current line as b

397

l: list the current line, showing invisible chars and end markers

398

n: print the current line with its line number

399

=: print the number of lines in the file

400

z22: print the next 22 lines

401

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

402

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

403

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

404

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

405

/x/: look for the line containing x

406

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

407

ci: searches and substitutions are case insensitive

408

cs: searches and substitutions are case sensitive

409

sg: substitution strings are global across sessions

410

sl: substitution strings are local to their sessions

411

lc: convert line to lower case

412

mc: convert line to mixed case

413

uc: convert line to upper case

414

h: help, explain the last question mark

415

f: print the name of the current file

416

f foo: set the file name to foo

417

f/: retain only the lass component of the filename

418

e: print the number of the current session

419

e3: move to session 3

420

e foo: edit the file named foo

421

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

422

w foo: write the current buffer to foo

423

w+ foo: append to foo

424

w/: write to the lass component of the filename

425

d: delete the current line

426

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

427

D: delete the current line and print the next line

428

u: undo the last command

429

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

430

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

431

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

432

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

433

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

434

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

435

3,4j: join lines 3 and 4 together

436

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

437

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

438

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

439

B: find the line with the balancing brace

440

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

441

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

442

b url: fetch url from the internet and browse it

443

ub: unbrowse a file

444

g: go to the link on the current line

445

g2: go to the second link on the current line

446

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

447

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

448

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

449

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

450

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

451

db: set debug level [0-7]

452

cd: change directory

453

bl: break line into sentences and phrases

454

dr: directory is readonly

455

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

456

dx: directory is writable, and d deletes files

457

hf: show hidden files in directory listing (toggle)

458

bd: binary detection on files (toggle)

459

eo: end markers off

460

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

461

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

462

lna: expand all nonascii chars into hex when a line is listed (toggle)

463

pb: play buffer

464

ft: show the title of the current web page

465

fd: show the description of the current web page

466

fk: show the keywords of the current web page

467

hr: http redirection (toggle)

468

js: allow javascript (toggle)

469

sr: send referrer (toggle)

470

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

471

iu: automatically convert between iso8859 and utf8 (toggle)

472

fma: ftp mode active

473

fmp: ftp mode passive

474

fmd: ftp mode default, passive then active

475

rf: refresh the web page or directory listing

476

et: edit this web page as pure text

477

vs: verify ssl connections (toggle)

478

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

479

sc: show columns

480

sm: send mail [account number]

481

re: reply to a mail message

482

rea: reply to all

483

</font></PRE>

484

485

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

486

487

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

488

I often receive complaints about line numbers. 

489

People hate line numbers. 

490

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

491

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

492

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

493

Haven't for years.

494

495

<P>

496

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

497

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

498

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

499

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

500

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

501

Start with 1z20 to get the first 20 lines. 

502

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

503

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

504

505

<P>

506

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

507

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

508

after you hit return,

509

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

510

511

<P>

512

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

513

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

514

This comes with practice. 

515

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

516

I wind up somewhere else and have to search again. 

517

This doesn't happen very often. 

518

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

519

520

<P>

521

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

522

Use the k command to mark them. 

523

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

524

while kc marks the new location. 

525

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

526

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

527

528

<P>

529

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

530

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

531

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

532

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

533

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

534

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

535

536

<P>

537

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,

538

provided you are familiar with the page. 

539

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

540

no matter what system you use.) 

541

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

542

or edit the common documents that we work on together.

543

544

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

545

546

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

547

You can join by sending mail to

548

549

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

550

551

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

552

553

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

554

This is because the regular expressions are interpreted

555

by the perl compatible regular expression (pcre) library,

556

rather than the traditional regexp library. 

557

Hence regular expressions have more features, and more power,

558

than the regular expressions employed by /bin/ed. 

559

The syntax is also somewhat different. 

560

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

561

to delimit sections of matched text. 

562

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

563

whereas ed uses \1 ... \9. 

564

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

565

along with the traditional g suffix for global substitute. 

566

There is no reason to describe all the nuances here. 

567

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

568

of regular expressions under perl. 

569

Once you are accustomed to their power and flexibility,

570

you'll never go back to ed.

571

572

<P>

573

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

574

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

575

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

576

as in searching for myFunction(),

577

so I reverse the sense of escaped parentheses in perl. 

578

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

579

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

580

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

581

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

582

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

583

to mean what it means in ed. 

584

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

585

as described in the perlre man page. 

586

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

587

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

588

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

589

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

590

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

591

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

592

if you are a perl expert. 

593

Sorry about that, but I think these changes make this

594

editor much easier to use for everyone,

595

especially the experienced ed users. 

596

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

597

598

<UL>

599

<P><LI>

600

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

601

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

602

603

<P><LI>

604

Lines beginning with ! implement a shell escape. 

605

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

606

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

607

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

608

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

609

610

<P><LI>

611

Type `cd dirname' to change directories. 

612

The new directory is always printed. 

613

Type cd alone to find out where you are. 

614

I don't know what happens under dos

615

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

616

617

<P>

618

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

619

Thus .. is always the physical parent directory.

620

621

<P>

622

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

623

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

624

625

<P>

626

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

627

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

628

and foo will be copied to the parent directory. 

629

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

630

631

<P><LI>

632

r operates on the current line by default,

633

rather then the last line. 

634

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

635

636

<P><LI>

637

The w+ command appends to the file. 

638

Some versions of ed use w> for this operation,

639

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

640

so using > for append is somewhat confusing. 

641

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

642

643

<P><LI>

644

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

645

of the current file name. 

646

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

647

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

648

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

649

650

<P><LI>

651

Whenever a file is read from or written to disk,

652

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

653

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

654

provided $adbook has been set in your environment. 

655

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

656

making it easy to edit files in your home directory

657

such as ~/.profile.

658

659

<P>

660

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

661

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

662

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

663

as this expansion is already done by the Unix shell. 

664

Windows users should compile using the setargv.obj utility,

665

which performs wildcard expansion on command line arguments. 

666

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

667

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

668

669

<P><LI>

670

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

671

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

672

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

673

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

674

The extraneous $ character just gets in my way.

675

676

<P>

677

However, I realize most people still use screen readers,

678

where trailing whitespace is indistinguishable from the blank screen,

679

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

680

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

681

Listed lines begin with ^ and end with $. 

682

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

683

Use `eo' to turn end markers off.

684

685

<P><LI>

686

q quits without a warning message if the text

687

has never been associated with a file.

688

689

<P><LI>

690

Capital Q does not quit the editor absolutely. 

691

This is because I often hit caps lock by mistake,

692

or even shift q by mistake,

693

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

694

those changes are gone! 

695

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

696

but it has happened to me many times,

697

so I disabled capital Q. 

698

Type qt to quit absolute.

699

700

<P><LI>

701

Capital J joins lines together with spaces between them.

702

703

<P><LI>

704

x (encryption) is not implemented.

705

706

<P><LI>

707

P (prompt) is not implemented.

708

709

<P><LI>

710

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

711

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

712

713

<P><LI>

714

You cannot enter one command across two physical lines

715

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

716

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

717

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

718

<br>

719

s/doghouse/dog-\nhouse/

720

721

<P><LI>

722

Only the first 500 characters of a line are displayed. 

723

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

724

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

725

as in the doghouse example above.

726

727

<P><LI>

728

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

729

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

730

731

<P><LI>

732

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

733

<br>

734

57 , 63 p will not fly.

735

736

<P><LI>

737

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

738

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

739

740

<P><LI>

741

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

742

This is used to split lines at phrase boundaries. 

743

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

744

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

745

s,3 splits the line after the third comma. 

746

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

747

748

<P><LI>

749

Type s by itself for s//%.

750

751

<P><LI>

752

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

753

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

754

and change some of them to bar at your discretion,

755

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

756

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

757

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

758

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

759

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

760

The sl command returns this editor to its local behavior,

761

where each file has its own search/replace strings.

762

763

<P><LI>

764

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

765

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

766

whence you must type h to read the explanation. 

767

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

768

769

<P><LI>

770

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

771

making the current line +7. 

772

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

773

somewhere other than the last line printed. 

774

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

775

whence dot actually is the last line printed. 

776

So I have changed the z command slightly. 

777

In this program z7 means +,+7p,

778

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

779

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

780

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

781

782

</UL>

783

784

<P>

785

Subsequent sections describe

786

new and interesting features, completely foreign to ed. 

787

These include the simultaneous edit of multiple files

788

similar to emacs and vi,

789

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

790

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

791

792

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

793

794

The capital B command is of interest to programmers,

795

and will probably not be used by casual home users. 

796

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

797

Consider the following code fragment.

798

799

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

800

y == 7) {

801

printf("hello\n");

802

} else {

803

printf("world\n");

804

exit(1);

805

}

806

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

807

808

<P>

809

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

810

moves to the middle line "} else {",

811

because that balances the open brace. 

812

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

813

which balances the open parenthesis. 

814

The second line balances {, rather than ),

815

because braces have precedence over parentheses,

816

which have precedence over brackets. 

817

You can force a parenthesis match by typing B),

818

which moves from line 2 back to line 1.

819

820

<P>

821

The B command on the else line is ambiguous -

822

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

823

You must type B{ or B}.

824

825

<P>

826

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

827

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

828

829

<P>

830

Comments or literal strings that contain balancing punctuation marks will

831

definitely throw edbrowse off the track. 

832

If you are the author of the source,

833

you might want to avoid braces in comments,

834

or use comments to keep braces in balance.

835

836

<P>

837

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

838

839

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

840

841

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

842

and transfer text between them. 

843

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

844

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

845

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

846

e1 through e6. 

847

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

848

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

849

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

850

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

851

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

852

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

853

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

854

Typing h will produce the explanation:

855

"Expecting `w' on session 5".

856

857

<P>

858

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

859

wrapping around to session 1 if necessary. 

860

The program exits when the last session quits.

861

862

<P>

863

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

864

If you switch to another session, then switch back,

865

you cannot undo your last edit. 

866

You'd think this would be easy to fix,

867

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

868

I just wanted you to know. 

869

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

870

871

<P>

872

Let's run through a cut&paste example. 

873

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

874

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

875

Here is how it might look. 

876

Lines beginning with < are the user's input,

877

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

878

The # sign delimits my injected comments.

879

880

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

881

> new session

882

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

883

# buffer is empty.

884

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

885

# The text is not linked to the file bar,

886

# and we cannot accidentally corrupt this file.

887

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

888

< r bar

889

> 28719

890

< /start/

891

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

892

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

893

< /end/

894

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

895

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

896

< e1

897

> foo

898

< r2

899

> 3279 # size of text read from session 2

900

< q2 # clean house, get rid of session 2

901

< w # write foo, with the new paragraph included

902

> 62121

903

</font></PRE>

904

905

<P>

906

The following moves the data from one file to another.

907

908

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

909

> new session

910

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

911

> 28719

912

< /start/

913

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

914

< ka # mark the paragraph

915

< /end/

916

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

917

< kb

918

< 'a,'bw3

919

> 3279

920

< 'a,'bd

921

< w # write bar, without the cool paragraph

922

> 25440

923

< q

924

> no file # now in session 3

925

< e1

926

> foo # back to session 1

927

< r3

928

> 3279

929

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

930

< w # write foo, with the new paragraph included

931

> 62121

932

</font></PRE>

933

934

<P>

935

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

936

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

937

938

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

939

940

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

941

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

942

Try to ignore this for now. 

943

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

944

rather than an editor. 

945

This will be discussed later.

946

947

<P>

948

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

949

The default is -d1,

950

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

951

Some people like -d2, which prints the URLs

952

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

953

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

954

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

955

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

956

957

<P>

958

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

959

This is usually used by batch scripts. 

960

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

961

962

<P>

963

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

964

(This config file will be described later.) 

965

And why would you want to do this? 

966

Suppose you have made a change to this file,

967

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

968

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

969

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

970

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

971

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

972

It is automatically loaded into buffer 1. 

973

Note that -c must be the first option.

974

975

<P>

976

The arguments are the files to edit. 

977

Edbrowse reads these files into corresponding sessions,

978

and starts you off in session 1. 

979

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

980

but there is no text and no associated file.

981

982

<P>

983

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

984

you can set the following Unix alias.

985

986

<P>

987

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

988

989

<P>

990

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

991

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

992

Very convenient.

993

994

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

995

996

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

997

for binary codes. 

998

Sorry, but I like hex better than octal. 

999

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

1000

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

1001

which is the code for 1/2. 

1002

Similarly, if you list a line with lna active, the 1/2 character

1003

is displayed as ~bd. 

1004

All nonascii and most control characters

1005

are entered and displayed in this manner. 

1006

Tab and newline must be entered directly from the keyboard. 

1007

Tab and backspace are displayed as > and < respectively. 

1008

If the following line is entered,

1009

1010

<P>

1011

Hello~07 ~x is ~bd of y

1012

1013

<P>

1014

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

1015

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

1016

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

1017

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

1018

use two tildes, ~~.

1019

1020

<P>

1021

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

1022

This program converts ~xx, as a hex value,

1023

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

1024

Thus any of the following will undos a file. 

1025

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

1026

1027

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

1028

,s/\15$//

1029

,s/\r$//

1030

</font></PRE>

1031

1032

<P>

1033

Embedded escape characters are always displayed in hex,

1034

whether the line is listed or not. 

1035

Most terminals and terminal emulaters, including the Linux console

1036

and my speech adapter,

1037

interpret various escape sequences as control commands. 

1038

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

1039

making recovery difficult. 

1040

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

1041

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

1042

1043

<P>

1044

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

1045

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

1046

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

1047

Every line ends in ~0d. 

1048

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

1049

1050

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

1051

1052

Data is considered binary if it is sufficiently large

1053

(more than 50 bytes)

1054

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

1055

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

1056

but most of the characters should still be ascii. 

1057

Therefore binary data is not international text. 

1058

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

1059

at least not by this program. 

1060

But don't let that stop you. 

1061

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

1062

then edit the executable using this editor. 

1063

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

1064

Write the file and run the executable. 

1065

You should now see "hello jorld".

1066

1067

<P>

1068

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

1069

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

1070

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

1071

1072

<P>

1073

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

1074

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

1075

1076

<P>

1077

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

1078

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

1079

and it leaves binary data alone. 

1080

These distinctions are not relevant on Unix/Linux.

1081

1082

<P>

1083

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

1084

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

1085

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

1086

If you speak an Asian language,

1087

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

1088

so edbrowse comes up the way you want -

1089

treating your international files as text files.

1090

1091

<P>

1092

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

1093

and binary detection is disabled,

1094

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

1095

as they will get corrupted! 

1096

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

1097

1098

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

1099

1100

If you edit a directory

1101

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

1102

in alphabetical order. 

1103

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

1104

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

1105

Type ^ to return to the parent directory. 

1106

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

1107

Thus you can traverse an entire directory tree

1108

as though you were inside a file manager.

1109

1110

<P>

1111

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

1112

This slash is not part of the filename. 

1113

Similarly, named pipe is indicated by |,

1114

symbolic link by @,

1115

block special by *, character special by <,

1116

and socket by ^. 

1117

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

1118

but it won't confuse this program. 

1119

Edbrowse knows whether that trailing | is part of the filename

1120

or a pipe indicator. 

1121

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

1122

files with newlines embedded in their names cannot be accessed.

1123

1124

<P>

1125

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

1126

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

1127

You must edit a directory in its own session

1128

or read a directory into an empty session

1129

if you want to access the underlying files. 

1130

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

1131

and in that session the words are just words. 

1132

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

1133

1134

<P>

1135

By default, directories are readonly. 

1136

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

1137

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

1138

I'm trying to save you from yourself! 

1139

Type dw to enable directory writes,

1140

and dr to make directories readonly again.

1141

1142

<P>

1143

When directory writes are enabled,

1144

you can remove files using the d command. 

1145

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

1146

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

1147

there is no undo capability. 

1148

When you make a change it is made. 

1149

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

1150

The deleted file isn't actually deleted;

1151

it is moved to your trash bin,

1152

located in $HOME/.Trash. 

1153

(This is consistent with the Mac and many versions of Linux.) 

1154

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

1155

you can recover them from your trash bin. 

1156

You may want to set up a cron job that removes

1157

all the files from your trash bin once a week. 

1158

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

1159

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

1160

After all, some of your deleted files might be private.

1161

1162

<P>

1163

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

1164

there are a few restrictions based on your operating system. 

1165

If your OS can move directories,

1166

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

1167

The entire subtree is moved to your trash bin. 

1168

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

1169

1170

<P>

1171

If the trash bin is on another file system,

1172

the file is copied, rather than moved. 

1173

It's practically the same; though the file will have your permissions, and a current time stamp. 

1174

Directories cannot be copied in this way. 

1175

You must copy the directory tree yourself, then delete it,

1176

using cp -r and rm -r.

1177

1178

<P>

1179

Note that the dx command, wherein files are truly deleted, is the only way to free up space on the disk. 

1180

Symbolic links and special files are always deleted;

1181

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

1182

1183

<P>

1184

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

1185

"What's wrong with the shell?"

1186

1187

<P>

1188

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

1189

But sometimes the file names are long and cumbersome,

1190

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

1191

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

1192

Meta characters such as the * can help,

1193

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

1194

This isn't always the case. 

1195

Suppose an application generates log files as follows.

1196

1197

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

1198

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

1199

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

1200

</font></PRE>

1201

1202

<P>

1203

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

1204

or rename them to something more manageable? 

1205

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

1206

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

1207

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

1208

Sometimes I want/need that kind of power.

1209

1210

<P>

1211

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

1212

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

1213

so you can't lose any data this way. 

1214

Again, I'm saving you from yourself.

1215

1216

<P>

1217

The search and substitute commands ignore the trailing filetype characters. 

1218

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

1219

you can type s/$/bar/. 

1220

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

1221

1222

<P>

1223

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

1224

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

1225

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

1226

But sometimes you don't own the files,

1227

and sometimes they must retain their original names. 

1228

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

1229

using their existing filenames. 

1230

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

1231

1232

<P>

1233

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

1234

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

1235

(This is standard ed syntax.) 

1236

Then run !program 'x

1237

to invoke your program on that file. 

1238

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

1239

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

1240

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

1241

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

1242

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

1243

1244

<P>

1245

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

1246

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

1247

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

1248

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

1249

then write the text to the file.

1250

1251

<P>

1252

You can expand multiple tokens in one shell command. 

1253

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

1254

1255

<P>

1256

This feature is not limited to directory scans. 

1257

You may be editing a simple file,

1258

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

1259

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

1260

but you can.

1261

1262

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

1263

1264

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

1265

and `uc' converts it to upper case. 

1266

Perl users will recognize these directives. 

1267

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

1268

and the d in mcdonald.

1269

1270

<P>

1271

This is especially useful in a directory scan. 

1272

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

1273

If directory write mode is enabled,

1274

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

1275

It's that simple.

1276

1277

<P>

1278

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

1279

This converts the word to upper case. 

1280

All the other substitution suffixes apply. 

1281

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

1282

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

1283

1284

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

1285

1286

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

1287

each about 70 characters long. 

1288

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

1289

If the line contains return characters,

1290

these are turned into line separaters -

1291

places where the line will definitely be cut. 

1292

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

1293

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

1294

This is a modest attemp to keep indented text indented,

1295

if that makes any sense?

1296

1297

<P>

1298

I use this feature in two different ways. 

1299

If I am familiar with the document,

1300

(I probably wrote it),

1301

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

1302

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

1303

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

1304

"I think we need a break after the third comma

1305

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

1306

issuing the s punctuation commands along the way. 

1307

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

1308

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

1309

Also, bl compresses accidental double spaces,

1310

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

1311

1312

<P>

1313

When the document comes in from the outside,

1314

usually from another word processor such as MS-Word,

1315

bl serves a completely different function. 

1316

Paragraphs are often stored on a single physical line. 

1317

Sometimes the entire document is on a single line,

1318

with return characters, \r, separating paragraphs. 

1319

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

1320

that's what word wrap is for. 

1321

Well - bl is our version of word wrap. 

1322

It doesn't try to conform to any screen;

1323

it merely cuts the text into manageable chunks,

1324

each piece a separate semantic unit. 

1325

When bl is issued,

1326

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

1327

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

1328

1329

<P>

1330

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

1331

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

1332

it is assumed to be a self-contained paragraph,

1333

and a blank line is added before and after. 

1334

Thus a disassembled paragraph containing 20 sentences

1335

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

1336

An empty line separates the two paragraphs. 

1337

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

1338

or the entire document,

1339

as might occur when making an outside document readable.

1340

1341

<P>

1342

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

1343

such as a table or ascii art. 

1344

If you're not sure what to expect,

1345

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

1346

scan through it first,

1347

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

1348

Often this is the entire document (,bl). 

1349

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

1350

1351

<P>

1352

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

1353

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

1354

f _

1355

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

1356

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

1357

,bl # break lines and paragraphs

1358

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

1359

</font></PRE>

1360

1361

<P>

1362

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

1363

This is often bundled with xls2cvs. 

1364

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

1365

1366

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

1367

1368

Suppose you are writing a file,

1369

and edbrowse truncates the existing file,

1370

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

1371

When you bring your computer back to life,

1372

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

1373

1374

<P>

1375

This is a narrow window to be sure;

1376

the computer has to fail at precisely the wrong millisecond. 

1377

To guard against this improbable calamity,

1378

some editors write your data to a temp file,

1379

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

1380

This way your data cannot be lost. 

1381

Either the new or the old file will survive.

1382

1383

<P>

1384

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

1385

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

1386

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

1387

and move the temp file over to the link. 

1388

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

1389

and your filesystem is not what it use to be. 

1390

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

1391

has not been changed at all. 

1392

This is not what you want! 

1393

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

1394

a link to some other file. 

1395

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

1396

and hope that nothing bad happens in between. 

1397

And you know what, it never does. 

1398

The window is just too small.

1399

1400

<P>

1401

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

1402

I just don't bother. 

1403

I truncate the file and write out the data,

1404

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

1405

1406

<P>

1407

Another race condition is more subtle. 

1408

Suppose you are editing a file and your friend,

1409

or a system program, edits the same file. 

1410

Your file has actually been changed out from under you,

1411

while you held it in memory. 

1412

When you go to write your changes,

1413

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

1414

Most text editors guard against this by watching the timestamp. 

1415

When you first edit the file foo,

1416

an editor might remember the timestamp on foo. 

1417

then, when you are ready to write your changes,

1418

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

1419

it issues a warning message. 

1420

"File has been updated by someone else -

1421

do you really want to write?"

1422

1423

<P>

1424

This is a good feature,

1425

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

1426

I'm the only user on my PC,

1427

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

1428

so this feature is not in high demand. 

1429

Still, I should implement it some day.

1430

1431

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

1432

1433

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

1434

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

1435

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

1436

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

1437

Because the text was retrieve from another machine,

1438

it cannot be written back to that machine,

1439

hence the `w' command will not work. 

1440

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

1441

or another editing session `w3'.

1442

1443

<P>

1444

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

1445

another machine and editing it locally. 

1446

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

1447

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

1448

on their websites for retrieval. 

1449

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

1450

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

1451

thus implementing an http download.

1452

1453

<P>

1454

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

1455

to leave the current buffer and

1456

retrieve text from a remote machine. 

1457

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

1458

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

1459

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

1460

1461

<P>

1462

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

1463

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

1464

is treated as a URL. 

1465

You can usually omit the http:// prefix. 

1466

Try invoking `e www.space.com',

1467

as an example. 

1468

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

1469

Browsing will be discussed later.

1470

1471

<P>

1472

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

1473

might change the filename out from under you. 

1474

This is because the resource has moved,

1475

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

1476

If debugging is set to 2 or higher,

1477

you might see a series of three or four different URLs

1478

as the editor is redirected across the internet. 

1479

Finally it retrieves your document,

1480

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

1481

You might want to update your bookmark file accordingly. 

1482

Then again, you might not. 

1483

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

1484

and subsequent redirections occur inside the company. 

1485

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

1486

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

1487

Use youre best judgment.

1488

1489

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

1490

1491

If the editor contains html text, from any source,

1492

you can type `b' to activate browse mode. 

1493

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

1494

or the editor is already in browse mode. 

1495

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

1496

or any other tag we recognize -

1497

it will always try to convert such a file. 

1498

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

1499

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

1500

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

1501

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

1502

If you write the transformed data, deliberately or accidentally,

1503

the reformatted text will be saved in a new file,

1504

whatever.html.browse,

1505

without disturbing the original html. 

1506

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

1507

BTW, I believe blind people should write raw html,

1508

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

1509

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

1510

I can create headings, lists, tables, etc,

1511

without using a wysiwyg editor or a screen reader. 

1512

This

1513

1514

excellent tutorial</A>

1515

will get you started.

1516

1517

<P>

1518

When the browse conversion is executed, the system checks for

1519

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

1520

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

1521

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

1522

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

1523

the first syntax error is displayed,

1524

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

1525

Type `ub' to undo the browse conversion. 

1526

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

1527

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

1528

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

1529

Repeat this process until `b' runs without errors.

1530

1531

<P>

1532

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

1533

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

1534

You could write the browsed text into file.browse,

1535

and that will satisfy the "write" criteria,

1536

but this isn't really what you want. 

1537

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

1538

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

1539

1540

<P>

1541

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

1542

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

1543

on some other website,

1544

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

1545

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

1546

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

1547

the raw html and the browsable text.

1548

1549

<P>

1550

The browse reformatting is relatively simple,

1551

because a blind person doesn't want complexity. 

1552

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

1553

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

1554

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

1555

1556

<P>

1557

I don't indent subsections or list items. 

1558

The visual effect is lost on us,

1559

and sometimes the extra spaces get in the way.

1560

1561

<P>

1562

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

1563

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

1564

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

1565

usually at a sentence or phrase boundary. 

1566

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

1567

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

1568

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

1569

any document. 

1570

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

1571

you'll see what I mean. 

1572

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

1573

1574

<P>

1575

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

1576

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

1577

and whitespace at the end of lines is stripped. 

1578

This preserves the structure of street addresses,

1579

and other preformatted blocks.

1580

1581

<P>

1582

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

1583

Pipes separate the fields on each row. 

1584

There is no whitespace around the pipes,

1585

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

1586

It isn't pretty,

1587

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

1588

especially when using a line editor such as this. 

1589

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

1590

Here is a sample table.

1591

1592

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

1593

2635|2|$34.80

1594

1398|1|$67.50

1595

8118|5|$125.00

1596

</font></PRE>

1597

1598

<P>

1599

Empty fields at the end of a row are dropped. 

1600

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

1601

sometimes an entire table of images. 

1602

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

1603

1604

<P>

1605

Note that the browsable text is readonly. 

1606

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

1607

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

1608

but this will be discussed later. 

1609

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

1610

Issue a copy or insert or substitute command,

1611

and you'll get an error.

1612

1613

<P>

1614

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

1615

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

1616

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

1617

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

1618

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

1619

1620

<P>

1621

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

1622

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

1623

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

1624

1625

<P>

1626

If a url is opened from the command line,

1627

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

1628

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

1629

1630

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

1631

1632

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

1633

1634

<P>

1635

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

1636

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

1637

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

1638

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

1639

This is not ambiguous, as you might first think;

1640

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

1641

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

1642

Even 17a3b3 is not ambiguous;

1643

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

1644

1645

<P>

1646

Superscripts are enclosed in parentheses, with a preceeding arrow. 

1647

The parentheses are omited if the superscript is a number. 

1648

Thus x cubed looks like x^3,

1649

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

1650

1651

<P>

1652

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

1653

in html. 

1654

At present edbrowse only supports one of them,

1655

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

1656

This is the unicode system,

1657

where the Greek letter theta is specified as

1658

&#952;. 

1659

Explorer turns this expression into θ,

1660

one character on the screen,

1661

while edbrowse turns it into the word theta. 

1662

We also put spaces around the word

1663

if its neighbors are also words. 

1664

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

1665

These three tokens are usually squashed together,

1666

and there is no confusion in the sighted world,

1667

where pi is a separate Greek letter. 

1668

But if pi is spelled out,

1669

and the tokens are left together,

1670

the result is 2pir. 

1671

Now pir looks like a three letter word. 

1672

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

1673

1674

<P>

1675

These translations are designed to work with the pages of the

1676

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

1677

an archive of advanced mathematics

1678

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

1679

This may be impossible,

1680

but I'm giving it a whirl.

1681

1682

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

1683

1684

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

1685

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

1686

These are normally not visible to the user. 

1687

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

1688

The description is a more complete explanation,

1689

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

1690

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

1691

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

1692

Like the rest of the browsable text,

1693

these three attributes are readonly. 

1694

If it is your web page,

1695

you can modify them by returning to the raw html. 

1696

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

1697

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

1698

1699

<P>

1700

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

1701

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

1702

which is probably not what you want.

1703

1704

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

1705

1706

Type `rf' to refresh the current file. 

1707

This rereads the file or url into the current buffer. 

1708

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

1709

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

1710

1711

<P>

1712

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

1713

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

1714

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

1715

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

1716

1717

<P>

1718

On your local machine,

1719

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

1720

such as a log file. 

1721

Or you can reread a directory,

1722

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

1723

For example, you might use the shell escape to execute

1724

`cat x y >z',

1725

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

1726

1727

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

1728

1729

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

1730

1731

<P>

1732

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

1733

1734

<P>

1735

Behind the scenes, "recent reports" is linked to

1736

www.pecanbread.com/BTVCautismchapter.html,

1737

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

1738

or view the raw html.

1739

1740

<P>

1741

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

1742

especially if the web page is technical in nature. 

1743

Hence there is some ambiguity. 

1744

However, I believe it is clear from context. 

1745

{More information} is probably a link,

1746

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

1747

1748

<P>

1749

Some web pages present a series of icons

1750

that are actually links to other pages. 

1751

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

1752

These icons are suppose to be intuitive. 

1753

Sometimes they are -- sometimes they're not. 

1754

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

1755

Sometimes the web designer is kind enough to supply

1756

a text phrase that roughly describes the image. 

1757

In this case the phrase is used as the link. 

1758

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

1759

If there is no alternate phrase,

1760

the filename of the hyperlink reference is used. 

1761

This name can be surprisingly helpful,

1762

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

1763

If this name canot be determined,

1764

the generic link {image} is used. 

1765

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

1766

1767

<P>

1768

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

1769

Yes, `g' also initiates a global command,

1770

such as a global substitute,

1771

but only when it is followed by a regular expression. 

1772

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

1773

g2 follows the second link on the current line,

1774

and 4g follows the link on line 4. 

1775

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

1776

the line containing the left brace.

1777

1778

<P>

1779

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

1780

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

1781

If your friend sends you an interesting url via email,

1782

and you save it to a text file,

1783

you can "go" to that link,

1784

even though the file is not html,

1785

and you've never issued a browse command.

1786

1787

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

1788

1789

Although most links lead to other web pages,

1790

some links point to other sections within the current document. 

1791

Again, you will be able to tell by context. 

1792

Links in the table of contents are usually

1793

shortcuts to chapters in the current document. 

1794

The same holds for links that look like:

1795

see {Appendix I},

1796

or, see the section on {Hardware Configuration}.

1797

1798

<P>

1799

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

1800

Either way you find yourself in a different place. 

1801

However, if the link is internal,

1802

you are still browsing the same file. 

1803

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

1804

The new line is displayed,

1805

and should correspond to the link you activated. 

1806

Often the words are the same. 

1807

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

1808

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

1809

1810

1811

1812

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

1813

and you already have text in the buffer,

1814

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

1815

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

1816

This is suppose to be intuitive --

1817

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

1818

1819

<P>

1820

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

1821

but it makes sense when surfing the net. 

1822

Often we descend through two or three links,

1823

only to find ourselves at a dead end. 

1824

"I didn't want to go here." 

1825

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

1826

We can now proceed in a new direction. 

1827

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

1828

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

1829

1830

<P>

1831

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

1832

including the file name,

1833

the last search/replace strings for substitutions,

1834

the hyperlinks and forms,

1835

the compiled javascript,

1836

everything!

1837

1838

<P>

1839

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

1840

I never really saw a need for this feature. 

1841

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

1842

and that's it. 

1843

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

1844

It is a one key command in my browser.

1845

1846

<P>

1847

The stack should not be confused with parallel edits,

1848

as described in an earlier section. 

1849

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

1850

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

1851

or cut&paste between them. 

1852

However, one session, with its internal stack,

1853

is usually sufficient to surf the net.

1854

1855

<P>

1856

If a browse command fails completely,

1857

giving you a rather uninteresting empty buffer,

1858

the stack is popped automatically,

1859

taking you back to the previous web page. 

1860

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

1861

or follow a different link on the page. 

1862

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

1863

if the remote server is well-designed. 

1864

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

1865

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

1866

After you've read the explanation,

1867

follow its directions,

1868

or type ^ to back up and try again.

1869

1870

<P>

1871

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

1872

The number is the size of the new file. 

1873

Use the ^ command to get back. 

1874

If there is no number, merely an error message,

1875

then edbrowse did not create a new buffer. 

1876

It probably didn't get that far. 

1877

Typing . will produce the same line you saw before.

1878

1879

<P>

1880

Following an internal link to another section in the current document

1881

does not push anything onto the stack. 

1882

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

1883

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

1884

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

1885

mark the current position with `kr'. 

1886

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

1887

1888

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

1889

1890

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

1891

pages that would normally stack up,

1892

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

1893

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

1894

Once the web page has moved to another session,

1895

edbrowse issues the ^ command for you. 

1896

Now you are back to the previous page.

1897

1898

<P>

1899

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

1900

with all its javascript objects etc,

1901

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

1902

and takes you back to the previous page. 

1903

Note, this command works just as well with files.

1904

1905

<P>

1906

Suppose a web page presents

1907

<P>

1908

{planes}

1909

<br>

1910

{trains}

1911

<br>

1912

{automobiles}

1913

1914

<P>

1915

If you are curious about all three topics,

1916

issue these commands in this order.

1917

1918

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

1919

M2

1920

2g

1921

M3

1922

3g

1923

M4

1924

</font></PRE>

1925

1926

<P>

1927

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

1928

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

1929

or stay in session 1 and do something else.

1930

1931

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

1932

1933

If you are trying to listen to a speech synthesizer,

1934

the last thing you need is background music. 

1935

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

1936

<P>

1937

{Background Music}

1938

<P>

1939

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

1940

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

1941

and play it at your convenience. 

1942

Use the play buffer `pb' command. 

1943

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

1944

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

1945

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

1946

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

1947

1948

<P>

1949

The config file (described below)

1950

includes mime type descriptors,

1951

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

1952

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

1953

It will say something like,

1954

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

1955

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

1956

1957

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

1958

1959

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

1960

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

1961

1962

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

1963

Advanced parsing: <->

1964

Language: <en>

1965

Search now: <GO>

1966

Cleaar form: <RESET>

1967

</font></PRE>

1968

1969

<P>

1970

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

1971

You supply the keywords to search for. 

1972

Entering and editing input fields is discussed later.

1973

1974

<P>

1975

The second line is a checkbox. 

1976

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

1977

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

1978

The feature is disabled, indicated by -. 

1979

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

1980

A + means the checkbox is on.

1981

1982

<P>

1983

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

1984

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

1985

We'll describe how to view the options later.

1986

1987

<P>

1988

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

1989

and retrieves the results. 

1990

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

1991

1992

<P>

1993

The fifth line is also a button to push. 

1994

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

1995

Default values will be restored. 

1996

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

1997

1998

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

1999

2000

Filling out a form is relatively easy,

2001

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

2002

Yes, i by itself means insert text,

2003

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

2004

2005

<P>

2006

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

2007

displays information about that input field. 

2008

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

2009

as in i3? for the third field. 

2010

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

2011

then the field name. 

2012

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

2013

the option list is displayed as well,

2014

with menu numbers prepended. 

2015

When you want to select an option,

2016

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

2017

such as mich for Michigan,

2018

or you can type in its menu number. 

2019

Needless to say, the latter is often easier. 

2020

Recall the sample form in the previous section. 

2021

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

2022

2023

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

2024

1: english

2025

2: french

2026

3: german

2027

4: italian

2028

5: spanish

2029

</font></PRE>

2030

2031

<P>

2032

If a select list contains hundreds of options,

2033

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

2034

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

2035

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

2036

2037

<P>

2038

Now let's do some data entry. 

2039

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

2040

Remember, you will need to type i3=xyz

2041

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

2042

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

2043

and you didn't pick one of those options. 

2044

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

2045

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

2046

and edbrowse will fill in the rest. 

2047

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

2048

(case insensitive) of the string you entered. 

2049

Thus you could enter tali above and get Italian,

2050

as that is the only language with those four letters. 

2051

This is useful when you are entering your address,

2052

and they ask for the state. 

2053

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

2054

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

2055

Note the paradigm here:

2056

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

2057

2058

<P>

2059

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

2060

In this case I perform three matches. 

2061

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

2062

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

2063

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. 

2064

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

2065

2066

<P>

2067

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

2068

Session 7 must have one line of text. 

2069

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

2070

Again, the file should contain one line of text. 

2071

The filename is expanded in the usual way. 

2072

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

2073

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

2074

2075

<P>

2076

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

2077

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

2078

No problem -- use the substitute command. 

2079

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

2080

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

2081

The usual substitution syntax is honored. 

2082

Don't overgenralize the g suffix in your mind. 

2083

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.

2084

2085

<P>

2086

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

2087

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

2088

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

2089

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

2090

You only need specify a field number

2091

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

2092

2093

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

2094

2095

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

2096

This is done inside a window within the screen,

2097

having a fixed number of rows and columns,

2098

although that is usually an artificial constraint. 

2099

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

2100

and the window scrolls appropriately. 

2101

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

2102

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

2103

if you were running a visual browser. 

2104

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

2105

2106

<P>

2107

The lynx implementation of the text area is particularly hideous. 

2108

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

2109

You can correct small typos on the current line,

2110

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

2111

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

2112

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

2113

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

2114

2115

<P>

2116

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

2117

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

2118

You can move text, make global substitutions,

2119

or read comments in from a prepared file. 

2120

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

2121

Consider the following form.

2122

2123

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

2124

Enter your comments: <buffer 2>

2125

</font></PRE>

2126

2127

<P>

2128

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

2129

The browser allocated session 2 specifically for this input field. 

2130

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

2131

and type e1 to return to the input form. 

2132

On most web pages the text area starts out blank,

2133

whence buffer 2 will be empty,

2134

but this is not always the case. 

2135

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

2136

A particularly arrogant site might preload the text area with:

2137

"I love your website because:".

2138

2139

<P>

2140

When you finally submit the form,

2141

as discussed in the next section,

2142

text buffer 2, associated with the second editing session,

2143

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

2144

Thus your carefully crafted comments are on their way. 

2145

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

2146

2147

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

2148

2149

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

2150

you can press the button via i3*. 

2151

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

2152

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

2153

2154

<P>

2155

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

2156

This is similar to following an internet link,

2157

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

2158

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

2159

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

2160

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

2161

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

2162

2163

<P>

2164

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

2165

the most common http protocols,

2166

and they seem to work on most sites.

2167

2168

<P>

2169

Once you have submitted your form,

2170

and you are viewing the results,

2171

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

2172

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

2173

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

2174

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

2175

you entered into the form. 

2176

It becomes part of the virtual URL. 

2177

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

2178

2179

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

2180

2181

The capital A command shows you the web addresses behind

2182

the links on the current line. 

2183

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

2184

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

2185

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

2186

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

2187

assumeing you have set the environment variable bookmarks appropriately. 

2188

They will be appended at the end;

2189

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

2190

For many, with dial up connections,

2191

connect time is precious,

2192

and should not be spent rearranging bookmark files. 

2193

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

2194

Here is how it might look.

2195

2196

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

2197

> 16834 # size of the raw html

2198

> 7855 # size of the browsable text

2199

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

2200

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

2201

< A # capture the URLs

2202

> 144 # size of the URLs

2203

< ,p # let's see them

2204

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

2205

> more information about kangaroos

2206

> </A>

2207

> send us mail:info@kangaroo.org

2208

< 4d # don't need the email address

2209

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

2210

> 336

2211

< ^ # back to browsing

2212

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

2213

</font></PRE>

2214

2215

<P>

2216

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

2217

and append the URL to that file automatically,

2218

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

2219

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

2220

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

2221

though in this example the description is pretty reasonable.

2222

2223

<P>

2224

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

2225

appending it to your address book. 

2226

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

2227

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

2228

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

2229

to that recipient. 

2230

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

2231

2232

<P>

2233

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

2234

the current filename is used. 

2235

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

2236

rather than some other page pointed to by a link.

2237

2238

<P>

2239

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

2240

may include your input fields after the question mark. 

2241

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

2242

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

2243

and activated again and again,

2244

as though you had filled out the form each time. 

2245

Every week you can call up this virtual URL

2246

to see if there is any new information on kangaroos. 

2247

A more practical example might be a canned query that retrieves

2248

the weather for a certain city

2249

or the stock prices for the companies in your portfolio. 

2250

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

2251

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

2252

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

2253

or the current price of any stock.

2254

2255

<P>

2256

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

2257

the same data will appear,

2258

but the question mark is replaced with a control a. 

2259

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

2260

When in doubt, list the line.

2261

2262

<P>

2263

One last warning about adding links to your bookmark file. 

2264

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

2265

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

2266

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

2267

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

2268

Years of accumulated links are gone. 

2269

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

2270

I know, we haven't talked about user defined macros yet, but we will. 

2271

And when we do, you should write a "bookmark append" macro that looks like this.

2272

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+bma {

2273

w+ $bookmarks

2274

}

2275

</font></PRE>

2276

2277

<P>

2278

Now you can type <bma to add a link to your favorites,

2279

and you don't have to worry about typos. 

2280

It's shorter than `w+ $bookmarks' anyways. 

2281

We'll return to this topic when we introduce macros,

2282

actually functions,

2283

that are defined in your config file.

2284

2285

<H3 align=center> <A NAME=cook> Cookies </A> </H3>

2286

2287

Some websites serve "cookies",

2288

which your browser is expected to retain

2289

and pass back during subsequent exchanges. 

2290

In fact many websites simply won't work without cooky support. 

2291

Therefore edbrowse always accepts cookies.

2292

2293

<P>

2294

Note that only Netscape-style cookies are supported. 

2295

However, this is the most common flavor of cooky. 

2296

It will probably meet your needs.

2297

2298

<P>

2299

Persistent cookies are stored in a file,

2300

usually $HOME/.cookies,

2301

and are thus available for subsequent edbrowse sessions. 

2302

These cookies are used to store long-term information about you,

2303

such as your login and password into amazon.com. 

2304

Hence your .cookies file should be mode 0600. 

2305

In fact the file is created mode 0600, for your own protection.

2306

2307

<P>

2308

You probably won't need to view your .cookies file, ever,

2309

but it is text based, and can be edited directly if you wish.

2310

2311

<H3 align=center> <A NAME=ssl> Secure Connections </A> </H3>

2312

2313

Edbrowse supports the most common method of encrypting web traffic,

2314

HTTP over SSL/TLS, colloquially known as secure http. 

2315

Websites that support

2316

secure http have URLs of the form:

2317

https://secure.server.com. 

2318

Notice the protocol is https:// rather than http://. 

2319

The extra s stands for "secure". 

2320

The traffic is encrypted, i.e. mathematically scrambled,

2321

and cannot be intercepted by a nefarious third party.

2322

2323

<P>

2324

Edbrowse will verify ssl connections,

2325

if you supply a file of ssl certificates. 

2326

This is an antispoofing measure, to make sure a hacker isn't posing as your bank,

2327

trying to steal your account numbers and passwords. 

2328

You can grab a certificate file <A HREF=ssl-certs>here</A>,

2329

but I don't always keep it up to date. 

2330

On some Linux distributions, you can run `cd /etc/ssl/certs ; cat * >../edbrowse-certs'

2331

to capture ssl certificates that are as current as your linux system.

2332

If you don't have or create this file,

2333

or, if you don't specify its location in your config file,

2334

you will not be able to verify secure connections, and you will be warned accordingly. 

2335

Some browsers don't have this feature at all, so it's not the end of the world,

2336

but in general it's a good idea to verify your secure connections,

2337

unless it prevents you from getting to a website whose authenticity you accept at face value. 

2338

In that case you can use the vs command to turn the feature off. 

2339

This is a toggle command; type vs again to turn the feature on.

2340

2341

<P>

2342

Never send sensitive information,

2343

such as social security numbers or credit card numbers,

2344

over an insecure channel. 

2345

Make sure the form is using ssl. 

2346

How can you tell? 

2347

The submit button will have the word "secure" added to its text.

2348

<P>

2349

2350

<P>

2351

This is similar to the lock icon that Explorer uses to tell you that your connection is secure,

2352

although my system is not quite as foolproof. 

2353

A website could fake you out by putting the word secure in the submit text.

2354

2355

<P>

2356

Note that generic buttons (besides the submit button) can also submit your form,

2357

through javascript. 

2358

I don't know if that button is going to submit the form or not,

2359

and I don't want to put the word "secure" on every button on the page. 

2360

I only add it to the submit button,

2361

but if that button is secure then they are all secure. 

2362

They all use the same form, and the same url.

2363

2364

<P>

2365

In theory, it is possible for javascript too switch the destination url out from under you at the last minute,

2366

from https://this.is.safe.com to http://this.is.untrusted.com. 

2367

I don't know if other browsers watch for this bait-and-switch, but edbrowse does. 

2368

If the original url was secure,

2369

and I reported this to you via <submit secure>,

2370

and javascript changes it to an insecure connection, I won't submit the form. 

2371

This is really paranoid,

2372

because the first website, the one that asked for your credit card number,

2373

also supplies the javascript,

2374

and they have no incentive to breech security,

2375

since you're going to hand them your credit card number anyways.

2376

2377

<P>

2378

If you have logins on secure servers,

2379

such as PayPal.com,

2380

you must keep your password absolutely safe. 

2381

Never send that password over an insecure connection. 

2382

It becomes as valuable as your credit card numbers. 

2383

I have a special password that I use for my secure logins,

2384

and <em>only</em> for those logins. 

2385

I use other, expendable passwords when the connection is not secure.

2386

2387

<P>

2388

Please don't fall for all those "phishing" email scams

2389

that tell you your login has expired, and would you please log in again using this convenient form. 

2390

The mail is forged to look legitimate,

2391

and the form actually sends your secret password to a thief,

2392

who then rades your account. 

2393

A reputable company will

2394

never, never, never, ask you to login through an email form. 

2395

They will always tell you to go back to the website and log in there.

2396

2397

<P>

2398

Internet security is complex, to say the least,

2399

and it is beyond the scope of this document. 

2400

If you have any questions about it,

2401

please send them to me directly. 

2402

As a general rule,

2403

secure http is really quite safe, and you can use it to send sensitive information across the Net. 

2404

It's probably safer than giving your credit card number to the clerk on the phone,

2405

who use to take your order before there was e-commerce. 

2406

so it's ok to be a little bit paranoid,

2407

in fact it's probably a good idea,

2408

but don't let that stop you from making your online purchases.

2409

2410

<H3 align=center> <A NAME=ftp> FTP Retrievals </A> </H3>

2411

2412

This browser supports the retrieval of ftp files and directories. 

2413

You can provide an FTP URL like:

2414

ftp://ftp.random.com/tarball.tar.gz

2415

and the file will be fetched. 

2416

It doesn't matter whether you type in the url yourself,

2417

or it is a hyperlink on a web page. 

2418

The file is retrieved, and placed in a local file of the same name. 

2419

You will ssee the words:

2420

<P>

2421

ftp download

2422

<br>

2423

some stats on the size of the file and the bits per second

2424

<br>

2425

success

2426

2427

<P>

2428

Of course the download could fail, in which case you will receive an error message. 

2429

If it was simply interrupted,

2430

due to some internet glitch,

2431

you can issue the command again,

2432

and edbrowse will resume the download from where it left off. 

2433

This can save time when fetching a large file.

2434

2435

<P>

2436

By default, edbrowse uses the account name "anonymous" and the password

2437

"some-user@edbrowse.net" for ftp connections. 

2438

However, you can override this in the url,

2439

and some web pages take advantage of this feature. 

2440

For example, let's say you want to access the file /etc/passwd on whatever.localdomain. 

2441

This file isn't readable by anonymous users. 

2442

You have to log in as a real person. 

2443

Within edbrowse, you might use the command:

2444

<P>

2445

e ftp://chris:xxx@whatever.localdomain/etc/passwd

2446

2447

<P>

2448

The ftp connection will be made as user "Chris", with password "XXX".

2449

2450

<P>

2451

Some ftp URLs point at directories, not files. If you visit one of these,

2452

and it is located on a Unix-like server, you will receive the listing as an

2453

html file with hyperlinks. You can visit the directory members just as

2454

though you were exploring a website. 

2455

If the server does not run some

2456

flavore of Unix, you will receive the directory listing in plain

2457

text.

2458

2459

<P>

2460

The ftp mode, i.e. the style of data connection,

2461

can be either active or passive. 

2462

One works well when the client is behind a router,

2463

and the other works well when the server is behind a router. 

2464

You can specify ftp mode active by entering the command `fma',

2465

or ftp mode passive by `fmp'. 

2466

The command `fmd' sets the ftp mode to a default,

2467

which tries to establish a passive connection first,

2468

and then an active connection as a fallback. 

2469

This is a reasonable default, so you should probably leave this alone.

2470

2471

<P>

2472

Edbrowse doesn't actually establish the ftp connections,

2473

rather, it invokes the program ncftpget to fetch the file,

2474

and ncftpls to list the directory. 

2475

These programs are distributed with most Unix systems. 

2476

If you don't have these programs, please visit

2477

<A HREF=http://www.ncftp.com>ncftp.com</A>.

2478

2479

<P>

2480

Once again, review the differences. 

2481

Http pulls a file into a buffer in memory, i.e. an edbrowse session,

2482

while ftp copies the file directly to disk. 

2483

Also, ftp does not print dots every 100K to indicate progress,

2484

so you just have to wait until it's done. 

2485

(Depending on your operating system, you could switch to another virtual console/window and check on the length of the local file.)

2486

2487

<H3 align=center> <A NAME=proxy> Proxy Servers </A> </H3>

2488

2489

A proxy server is a web server that sits between your web browser and remote websites. 

2490

It intercepts your requests for web pages and forwards them to the system that hosts

2491

the site you are browsing. 

2492

Proxy servers are used for a variety of reasons. 

2493

Here are just a few of them:

2494

2495

<OL>

2496

<P><LI>Efficiency. 

2497

The proxy server may be able to store previously-accessed webpages

2498

(known as caching). 

2499

If your connection to the proxy is faster than your connection to the rest of the network,

2500

then caching insures that frequently-accessed web pages load quickly.

2501

<P><LI>Policies. 

2502

Some firewall administrators require their users to use

2503

a proxy server.

2504

<P><LI>Anonymity. 

2505

There are so-called anonymizing

2506

proxy servers that hide your IP address from the websites that you browse.

2507

</OL>

2508

2509

<P>

2510

If you wish to use a proxy server for http traffic, simply set the proxy

2511

option in your configuration file. 

2512

Provide the hostname and port, separated by a colon. 

2513

For example:

2514

<P>

2515

proxy = proxy.campus.edu:3128

2516

2517

<p>

2518

Note that proxies often listen on ports other than port 80. 

2519

Squid is a proxy server that comes bundled with some Linux distributions, and it uses

2520

port 3128 by default.

2521

2522

<p>

2523

Presently, edbrowse only handles proxying of standard http. 

2524

Secure http and ftp

2525

can both be proxied, but this functionality is not implemented.

2526

2527

<H3 align=center> <A NAME=frame> Frames </A> </H3>

2528

2529

Frames are a mechanism whereby a web page can fetch and display several other web pages on the screen at once. 

2530

Each subpage is called a frame, and lives in its own space on the screen. 

2531

Sometimes the frames are top middle and bottom;

2532

sometimes they are left middle and right. 

2533

Edbrowse presents these frames as hyperlinks,

2534

and you can call up each in turn,

2535

or jump straight to a specific frame if you are familiar with the website. 

2536

Usually the top frame is navigational in nature,

2537

and the bottom is a legal disclaimer/copyright notice,

2538

so you're just as happy to skip these and cut to the chase. 

2539

On rare occasions, and I've only seen this once,

2540

you <em>must</em> open the top frame,

2541

whether you are interested in it or not,

2542

because that particular html page sets some cookies that you need to run the website.

2543

2544

<P>

2545

A page of frames might look like this. 

2546

I think you can guess which one to click on.

2547

2548

<P>

2549

Frame {navigation}

2550

<br>

2551

Frame {main}

2552

<br>

2553

Frame {bottom}

2554

2555

<P>

2556

I thought about a FetchFrame feature that fetches all the frames and presents them in one go,

2557

just as they are all displayed on the screen for a sighted user,

2558

but this feature is <em>very</em> difficult to implement,

2559

and so far, nobody seems to want it. 

2560

So as you might imagine, it's way down on the list.

2561

2562

2563

2564

PDF is a portable document format developed by <A HREF=http://www.adobe.com>adobe.com</A>. 

2565

A document, using this format, and designated with the suffix .pdf, prints the same way, every time, on every printer. 

2566

That is its principle advantage. 

2567

However, pdf files are entirely unreadable by blind individuals. 

2568

Fortunately, there is a utility,

2569

2570

pdftohtml</A>,

2571

that converts pdf to html. 

2572

Sometimes it works well, and sometimes lines are broken in bizarre places;

2573

but it's better than nothing. 

2574

If you install this package, edbrowse will automatically convert pdf files into html files,

2575

and then render them as text.

2576

2577

<P>

2578

Note, there are also pdf to text converters that skip the middle (html) step,

2579

but I wanted to preserve the functionality of any hyperlinks that might be embedded within pdf. 

2580

So I thought it worthwhile going through html, even though it adds a little complexity.

2581

2582

<H3 align=center> <A NAME=js> Introduction to Javascript </A> </H3>

2583

2584

Javascript is software, embedded in the web page, that runs on your computer. 

2585

These functions do not run on the web server,

2586

they run right on your box. 

2587

Hence it is sometimes called client side javascript. 

2588

And javascript can do almost anything. 

2589

You could, for instance, download a web page that includes a javascript function to compute the digits of pi,

2590

right on your computer,

2591

although that would be rather silly. 

2592

Most of the time javascript is used to validate and/or modify forms,

2593

or create fancy visual effects.

2594

2595

<P>

2596

The first version of edbrowse, written in perl, ignored javascript completely,

2597

and that was ok for a while,

2598

but more and more sites use javascript,

2599

and these websites were simply inaccessible. 

2600

Most of the e-commerce sites fall into this category. 

2601

If you want to make purchases, or manage your bank account online,

2602

you <em>need</em> a javascript enabled browser.

2603

2604

<P>

2605

The second version of edbrowse, written in C,

2606

and indicated by a version number that starts with 2,

2607

included a home grown javascript compiler and engine

2608

that I wrote myself. 

2609

This worked pretty well, for a spare time project,

2610

but javascript evolves, like any other language or standard,

2611

and I just couldn't keep up.

2612

2613

<P>

2614

The third version, which is the "latest and greatest", uses a javascript engine from Mozilla.com,

2615

which is open source under the Mozzilla Public License. 

2616

This allows me to leverage, rather than reinvent, some 70,000 lines of code -

2617

and somebody else is maintaining that code as javascript evolves. 

2618

this illustrates the power of the open source community.

2619

2620

<P>

2621

Edbrowse does not support all the features of client side (DOM) javascript,

2622

and it never will. 

2623

For example, many websites use javascript to change images

2624

on the fly as you move your mouse around the screen. 

2625

This has no meaning in edbrowse. 

2626

Other websites bring up multiple windows,

2627

and let you control the contents of subwindows using icons in a master window. 

2628

This would be very difficult to simulate in a command-line environment -

2629

so we don't try.

2630

2631

<P>

2632

As a rough approximation, I expect to implement about half of javascript,

2633

the half that will satisfy 95% of the websites we care about. 

2634

So you may see warning messages about this or that feature not supported. 

2635

If you are tired of wading through these messages,

2636

or if a bug in my javascript interpreter causes edbrowse to crash completely,

2637

you can turn javascript off via the `js' command. 

2638

This is useful when you are casually surfing the net, looking for information,

2639

and you know you're not going to need javascript. 

2640

You can also disable javascript for specific domains. 

2641

This will be discussed later, when we describe the edbrowse config file.

2642

2643

<H3 align=center> <A NAME=valid> Validating Forms </A> </H3>

2644

2645

When a web page asks for user input,

2646

it often includes a

2647

"validate&submit" function. 

2648

This function checks your entries:

2649

have you filled in all the riquired fields -

2650

is there an @ sign in your email address -

2651

are there 5 digits in your zip code -

2652

and so on. 

2653

If there are no errors, it submits the form. 

2654

These functions usually behave well under edbrowse. 

2655

When you push the button, you will either see the error message,

2656

or the form will be submitted,

2657

and a confirmation page should appear shortly.

2658

2659

<P>

2660

In some cases the javascript function

2661

reformats your data. 

2662

It may fill in some of the "hidden" fields for you,

2663

or it may compute sales tax and adjust the purchase price accordingly. 

2664

This is more than form validation, this is active javascript,

2665

and the data won't be right unless the javascript runs properly

2666

on your computer. 

2667

More and more sites are using active javascript,

2668

so a javascript enabled browser is a must.

2669

2670

<P>

2671

Some javascript functions manage menus dynamically. 

2672

Make a primary selection,

2673

and javascript populates a second dropdown list with options

2674

corresponding to your first selection. 

2675

You can now make a second selection,

2676

which further refines your search. 

2677

If the first menu presents "meats", "vegetables", "fruits", and "grains",

2678

and you select fruits,

2679

the second menu might contain

2680

"apples", "oranges", "lemons", etc. 

2681

Javascript makes this possible. 

2682

Unfortunately these dynamic menus are not yet supported by edbrowse.

2683

2684

<H3 align=center> <A NAME=popup> Popups and Popunders </A> </H3>

2685

2686

A popup is a window that suddenly appears in front of the window you really want to see. 

2687

It usually advertises something, and is often annoying,

2688

although in rare cases it is a necessary aspect of the website.

2689

2690

<P>

2691

You have a distinct advantage over all those other surfers with their graphical browsers. 

2692

The popup window does not open automatically. 

2693

Windows are not well defined in a command line browser anyways,

2694

so it would be folly to try to implement this feature,

2695

or any other aspect of multi-windowing for that matter. 

2696

Instead, the popup appears as a hyperlink at or near the top of the page,

2697

and you can click on it if you like, or ignore it. 

2698

This is similar to the <A HREF=#music>background music</A>, described in an earlier section. 

2699

The popup link might look like this.

2700

<P>

2701

{Popup: specials()}

2702

2703

<P>

2704

Popunders are not as common. 

2705

They appear after you have closed the window. 

2706

In some sense they are hidden "under" your web page, and when you close the page they pop out. 

2707

In edbrowse, this does not happen automatically. 

2708

When you type q, you quit, and that's the end of it. 

2709

As you might expect, the popunder function appears as a hyperlink. 

2710

It might look like this.

2711

<P>

2712

{On Close: foo()}

2713

2714

<P>

2715

Remember, the popup link is a simple html link to another web page,

2716

while the Close link calls a javascript function on the current page. 

2717

However, this javascript function usually links to another web page,

2718

so don't be surprised if you find yourself somewhere else on the internet. 

2719

In either case, popup or popunder, you can use the back key to return to the

2720

page you were looking at. 

2721

If you need access to a popup window and the main page in parallel,

2722

use the <A HREF=#move>M command</A>.

2723

2724

<P>

2725

Javascript also includes timer functions,

2726

that fire after a specified number of seconds. 

2727

These are implemented as hyperlinks at the top of the page. 

2728

They usually manage visual effects, and are rather pointless. 

2729

The following timer might draw a star burst on the screen in 16 seconds.

2730

<P>

2731

{Timer 16: starburst()}

2732

2733

<H3 align=center> <A NAME=onc> Onchange and Undo </A> </H3>

2734

2735

When you set or change the value of an input field,

2736

the form can (optionally) call a javascript routine. 

2737

It doesn't usually, but it can. 

2738

In an earlier example, I described a primary and secondary menu. 

2739

When the first selection is made,

2740

e.g. fruits,

2741

javascript sets up the second menu commensurate with your primary selection,

2742

using the "onchange" feature.

2743

2744

<P>

2745

This is all well and good,

2746

but edbrowse has something

2747

your graphical browser does not, the undo command. 

2748

And in this context, it doesn't really work. 

2749

Change fruits to vegetables, and the second menu presents carrots and peas and the like. 

2750

Now type u for undo,

2751

and the first field reverts back to fruits,

2752

but the second menu still contains vegetables. 

2753

This is because the undo feature was originally written for the text editor. 

2754

It simply puts the text back the way it was, and has no capacity to "undo" the side effects of javascript code. 

2755

So the moral of the story, if there is one,

2756

is to set and change the values of an input form directly,

2757

and avoid the undo command, unless you're pretty sure there are no javascript side effects associated with that field.

2758

2759

<H3 align=center> <A NAME=cfg> Config File </A> </H3>

2760

2761

At startup, edbrowse reads and parses a config file. 

2762

It's ok if this file is missing, but if it is present,

2763

it has to be syntactically correct. 

2764

An error in your config file will cause edbrowse to abort. 

2765

If this happens, use the -c option to edit the config file directly. 

2766

This bypasses initialization, and places you in the editor,

2767

with the config file preloaded. 

2768

Make your corrections, write the file,

2769

quit, and invoke edbrowse again. 

2770

Repeate these steps until there are no errors,

2771

and you see the words "edbrowse ready".

2772

2773

<P>

2774

The config file is in $HOME/.ebrc. 

2775

The "eb" is shorthand for edbrowse. 

2776

You cannot rename the config file; it is what it is. 

2777

This is true on Windows as well, so make sure HOME is set.

2778

2779

<P>

2780

The config file is line oriented. 

2781

Lines begining with # are comments, and are ignored. 

2782

Blank lines are also ignored. 

2783

All other lines fall into one of 5 categories.

2784

2785

<OL>

2786

<P><LI> Define an option, using the keyword=value syntax.

2787

<P><LI> Define an edbrowse script that can be invoked from the command line,

2788

or from another script.

2789

<P><LI> An edbrowse command, that becomes part of an edbrowse script.

2790

<P><LI> Establish an email account. 

2791

This will be described later, when we talk about the email client.

2792

<P><LI> A mail filtering rule. 

2793

</OL>

2794

2795

<H3 align=center> <A NAME=keyval> Keyword = Value </A> </H3>

2796

2797

The best documentation is an example, so let's dive right in.

2798

2799

<P>

2800

Recall the section on <A HREF=#cook>cookies</A>. 

2801

You'll need a file, often called a cookie jar,

2802

to store your cookies. 

2803

The line that establishes this cookie jar might look like this.

2804

<P>

2805

jar = /home/eklhad/.ebsys/cookie-jar

2806

2807

<P>

2808

This is a simple keyword = value syntax. 

2809

It's ok if the filename has embedded spaces, or even an equals sign. 

2810

No need to quote it.

2811

2812

<P>

2813

When edbrowse sees this line in its config file, it records the location of the cookie jar,

2814

and it checks the validity of that file. 

2815

If the file is a directory (or something weird),

2816

or is otherwise inaccessible,

2817

edbrowse prints an error message and aborts. 

2818

If this happens,

2819

use the -c option to edit your config file,

2820

and change the cookie jar.

2821

2822

<P>

2823

Here are some additional name=value directives. 

2824

Some of these are used to set up an email account. 

2825

This will become clearer when we talk about the mail client.

2826

2827

<P>

2828

certfile = /home/eklhad/.ebsys/ssl-certs

2829

2830

<P>

2831

Specify the file that holds the certificates for secure connections. 

2832

This was explained in the section on <A HREF=#ssl>secure connections</A>.

2833

2834

<P>

2835

maildir = /home/eklhad/mbox

2836

<P>

2837

Go to this directory when fetching mail. 

2838

thus, if you save a mail message, you'll always know where it is.

2839

2840

<P>

2841

webtimer = 30

2842

<br>

2843

mailtimer = 180

2844

2845

<P>

2846

Wait 30 seconds for a response from a web server, and 3 minutes for a response from the mail server. 

2847

A time value of 0 waits forever. 

2848

Sorry, there seems to be no way to interrupt a socket call,

2849

other than control backslash (quit), which kills the entire program. 

2850

That's why these timers are here - so you don't hang forever. 

2851

The defaults are 20 and 0 respectively.

2852

2853

<P>

2854

nojs = space.com

2855

<P>

2856

Specify domains that don't need javascript. 

2857

You can eliminate annoying error messages and speed up access

2858

by disabling javascript for certain websites. 

2859

Javascript will not be run on pages within these domains,

2860

nor will it be fetched from these domains.

2861

2862

<P>

2863

The above directive will also drop javascript from subdomains such as www.space.com.

2864

2865

<P>

2866

You can include a path or partial path after the domain, as in space.com/popups. 

2867

This will block the popup ads that you don't want to see, and often generate edbrowse errors in any case. 

2868

Subdomains are not considered when a path is given; the domain must match exactly.

2869

2870

<P>

2871

inserver = pop3.some-domain.com

2872

<br>

2873

inport = 110

2874

<br>

2875

outserver = smtp.some-domain.com

2876

<br>

2877

outport = 25

2878

<P>

2879

Specify the machines and ports that you use to fetch mail and send mail respectively. 

2880

You can use the fully qualified domain names, or aliases, as defined in /etc/hosts. 

2881

The ports shown here are standard, and usually correct. 

2882

They are also default in edbrowse, so you need not set inport and outport unless they are different from that shown above. 

2883

Note, these keywords are only valid in the context of a mail account, as indicated by mail{}.

2884

2885

<P>

2886

A star in front of the port number,

2887

e.g. inport *110,

2888

means the socket is to be encrypted, for security. 

2889

When the smtp port is encrypted, login authentication is assumed. 

2890

No other authentication method is implemented at this time,

2891

nor is authentication possible outside the context of an encrypted stream.

2892

2893

<P>

2894

login = eklhad

2895

<br>

2896

password = secret

2897

<P>

2898

Specify the login and password that edbrowse uses to fetch your mail.

2899

2900

<P>

2901

from = Karl Dahlke

2902

<br>

2903

reply = karl.dahlke@some-domain.com

2904

<P>

2905

These lines are added in to the emails that you send. 

2906

They tell the recipient who you are, and how to reply. 

2907

It is

2908

2909

illegal</A> to use these lines for deceptive purposes. 

2910

Make sure they identify you, and that the reply address is indeed one of your email accounts.

2911

2912

<P>

2913

adbook = /home/eklhad/.ebsys/address-book

2914

<P>

2915

When specifying recipients, you can use aliases instead of full email addresses. 

2916

Aliases are checked against your address book,

2917

a line oriented text file that is specified here. 

2918

If your address book contains the line

2919

<P>

2920

fred : fred.flintstone@bedrock.us : 226 cobblestone way : 5553827

2921

<P>

2922

then you can use the alias fred,

2923

and edbrowse will substitute Fred's email address when sending mail. 

2924

Only the first two fields in the address book are significant

2925

as far as edbrowse is concerned. 

2926

Other fields might hold phone/fax numbers, street address, etc. 

2927

It's up to you.

2928

2929

<P>

2930

spamcan = /home/eklhad/.Trash/save-spam

2931

<P>

2932

There is no perfect spam filter. 

2933

But I can't live without one,

2934

so I wrote a simple ip blocker. 

2935

(This is discussed below.) 

2936

When spam is received,

2937

edbrowse prints the line "spam from such and so",

2938

and saves the mail in this file. 

2939

If you recognize the name, spam from your friend,

2940

you can call up this file, find the email, and read it. 

2941

This should not happen, as there is no particular reason to block the ip address of your friend's computer,

2942

but hey, better safe than sorry.

2943

2944

<P>

2945

ipblack = /home/eklhad/.ebsys/ip-blacklist

2946

<P>

2947

A line oriented text file holds the ip addresses of known porn/spam sites. 

2948

The syntax is the usual: numbers separated by dots,

2949

with an optional /xx netmask indicator at the end. 

2950

If the file contains the following two lines,

2951

any ip address that starts with 192.168,

2952

or 10.11.12.13, are forbidden addresses.

2953

<P>

2954

192.168.0.0/16

2955

<br>

2956

10.11.12.13

2957

2958

<P>

2959

If an email refers to a website that resolves to any of these addresses it is considered spam,

2960

and flagged as such. 

2961

Let's be clear; I am not blocking email that comes from certain sources. 

2962

After all, your friend's computer may well be sending you viruses or spyware. 

2963

Rather, I screen email that has certain urls in its body. 

2964

If the button that says "cheap meds for you" leads to a forbidden website,

2965

you'll never see the email.

2966

2967

<P>

2968

Note, I use the very same blacklist in my firewall. 

2969

A shell script reads in the addresses and issues the appropriate iptables commands. 

2970

My file has some 2,000 entries. 

2971

This is large, but manageable. 

2972

If the list gets much larger, I may rebuild the kernel

2973

with the "large ip tables" option enabled. 

2974

This makes packet matching more efficient when there are many rules. 

2975

I suppose it sorts them or something.

2976

2977

<H3 align=center> <A NAME=agent> User Agent </A> </H3>

2978

2979

Every time you fetch a web page from the internet,

2980

your browser identifies itself to the host. 

2981

This is done automatically. 

2982

Edbrose identifies itself as "edbrowse/2.2.9",

2983

where the number after the slash indicates the current version of edbrowse.

2984

2985

<P>

2986

All well and good, but some websites have no respect for edbrowse,

2987

or lynx for that matter. 

2988

They won't even let you in the door unless you look like Explorere or Netscape. 

2989

Clickbank.com, a major credit card processor, is one example.

2990

<P>

2991

So what do we do? 

2992

We lie!

2993

2994

<P>

2995

You can specify different agents in your .ebrc file,

2996

and activate them with the `ua' (user agent) command. 

2997

If the following lines are in your .ebrc file,

2998

you can type ua1 to pretend to bee lynx,

2999

and ua2 to pretend to be Mozilla. 

3000

Type ua0 to resurrect the standard edbrowse identification. 

3001

Let's hope there aren't too many asinine websites out there,

3002

like Clickbank, that force us to lie. 

3003

It's just so stupid, and pointless.

3004

3005

<P>

3006

agent = Lynx/2.8.4rel.1 libwww-FM/2.14

3007

<br>

3008

agent = Mozilla/4.0 (compatible; MSIE 5.5; Windows 98; Win 9x 4.90)

3009

3010

<P>

3011

This feature was written pre-javascript,

3012

and is not 100% compatible with the navigator object. 

3013

Navigator.userAgent returns the correct string, according to the agent you select,

3014

but other aspectss of the navigator object do not change with the agent,

3015

and they should.

3016

3017

<H3 align=center> <A NAME=script> Edbrowse Functions </A> </H3>

3018

3019

You can bundle a set of edbrowse commands together under one name,

3020

similar to a macro. 

3021

If the following appears in your .ebrc file,

3022

you can type <ud to undos a file.

3023

<P>

3024

function:ud {

3025

<br>

3026

  ,s/\r$//

3027

<br>

3028

}

3029

3030

<P>

3031

The new < command is suppose to remind you of redirection,

3032

i.e. read input commands from this macro. 

3033

And macros can invoke other macros,

3034

by using a < command in the body. 

3035

Almost any edbrowse command is fair game. 

3036

A macro can fetch web pages from the internet,

3037

fill out forms, submit requests, and send mail.

3038

3039

<P>

3040

Normally, edbrowse marches along, whether a command succeeds or not. 

3041

However, you can tell a macro to stop if it encounters an error

3042

by using this syntax.

3043

<P>

3044

function+hw {

3045

<br>

3046

  /hello/p

3047

<br>

3048

  /world/p

3049

<br>

3050

}

3051

3052

<P>

3053

The plus sign after the word function means each command in that function must succeed. 

3054

If there is no line containing the word hello, the function stops. 

3055

If there is such a line, then the function moves on,

3056

and looks for a line containing the word world.

3057

3058

<P>

3059

Other than some indenting, the format is fixed, and unforgiving. 

3060

You cannot, for instance, put the opening brace on its own line, as K&R would suggest.

3061

3062

<P>

3063

These functions, or macros, can accept parameters. 

3064

Let's make the previous function a bit more general.

3065

<P>

3066

function+hw {

3067

<br>

3068

  /~1/p

3069

<br>

3070

  /~2/p

3071

<br>

3072

}

3073

3074

<P>

3075

You can reproduce the earlier behavior by typing <hw hello world. 

3076

Or you can search for different lines by invoking <hw foo bar. 

3077

The latter looks for a line containing foo and prints it,

3078

and if this succeeds it looks for a line containing bar and prints that. 

3079

Let's build a more useful function, a shortcut to google. 

3080

The variable ~0 represents all the arguments together. 

3081

In this case ~0 is the keywords you pass to google, for your search.

3082

<P>

3083

function+gg {

3084

<br>

3085

  b www.google.com/search?q=~0&hl=n&btnG=Google+Search&meta=

3086

<br>

3087

}

3088

3089

<P>

3090

With this in place, you simply type `<gg kangaroo habitat'

3091

to find out where kangaroos live.

3092

3093

<P>

3094

Finally, an edbrowse function can branch,

3095

based upon the success or failure of the previous command. 

3096

Use if(*) for success, and if(?) for failure. 

3097

The ? is suppose to remind you of the question mark that you get when an edbrowse command fails. 

3098

The following looks for a line containing foo, and if it finds one,

3099

it advances to the next line, and if that line contains bar, it deletes it.

3100

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+silly {

3101

/foo/

3102

if(*) {

3103

+s/bar//

3104

if(*) {

3105

d

3106

}

3107

}

3108

}

3109

</font></PRE>

3110

3111

<P>

3112

I deliberately used function+ instead of function: in the above example. 

3113

Normally the + will cause the function to abort if an edbrowse command fails. 

3114

However, if the result of that command is used by a control statement,

3115

the function does not abort. 

3116

This is similar to set -e in the shell,

3117

which causes a script to abort,

3118

unless the result of the command is used by an if statement.

3119

3120

<P>

3121

Other control statements include while(*) while(?) until(*) and until(?). 

3122

The following deletes lines from the top of the file,

3123

as long as they contain foo or bar. 

3124

It then deletes the blank lines at the top.

3125

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+topclean {

3126

until(?) {

3127

1g/foo\|bar/d

3128

}

3129

until(?) {

3130

1g/^$/d

3131

}

3132

}

3133

</font></PRE>

3134

3135

<P>

3136

You can use loop(100){ ... } to repeat a set of commands 100 times. 

3137

I haven't used this feature very often.

3138

3139

<H3 align=center> <A NAME=init> The Init Script </A> </H3>

3140

3141

The script named "init" is run at edbrowse startup. 

3142

You can use this to establish your default settings - even read in your bookmark file,

3143

so your "favorites" are close at hand. 

3144

Here is an example.

3145

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>function+init {

3146

# turn debug off, so we don't see any status messages from this script

3147

db0

3148

# Assume directories can be modified

3149

dw

3150

# Put beginning and end markers around listed lines

3151

el

3152

# Let session 99 hold your favorites, ready to surf.

3153

e99

3154

b $bookmarks

3155

# back to session 1, ready to go to work

3156

e1

3157

# Restore debug level to something reasonable, 1 or 2

3158

db1

3159

}

3160

</font></PRE>

3161

3162

<P>

3163

This is just a sample. 

3164

Put anything you like in your init script,

3165

or leave it out altogether if you are happy with edbrowse out of the box.

3166

3167

<H3 align=center> <A NAME=ma> Mail Accounts </A> </H3>

3168

3169

The next chapter describes edbrowse as a mail client,

3170

so let's use the config file to define your email accounts. 

3171

You can define several accounts, as necessary. 

3172

They are implicitly numbered,

3173

in the order they appear in the config file. 

3174

So the first mail account becomes #1, the second becomes #2, and so on.

3175

3176

<P>

3177

We already discussed the relevant keywords for an email account. 

3178

All you have to do is enclose them in mail{...}, like this.

3179

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

3180

default

3181

inserver = pop3.some-domain.com

3182

outserver = smtp.some-domain.com

3183

login = eklhad

3184

password = secret

3185

from = Karl Dahlke

3186

reply = karl.dahlke@some-domain.com

3187

}

3188

</font></PRE>

3189

3190

<P>

3191

The "default" directive makes this account the default. 

3192

One and only one account should be labeled default. 

3193

If you do not specify an account when fetching or sending mail, the default account is used. 

3194

Beyond this, the default smtp server is always used to send mail,

3195

no matter which account you specify. 

3196

If account #1 is default, and you send mail using account #3,

3197

the name and reply address from account #3 will be sent to the recipient,

3198

and if he replies, his reply will be sent to your third email account. 

3199

However, the smtp server from your default account is used to physically transmit the message. 

3200

There are technical reasons for doing this,

3201

having to do with security. 

3202

However, if an account has its sendmail stream encrypted, then security is not an issue,

3203

and we can use these settings to send and receive mail. 

3204

Here is a typical configuration for Google's gmail.

3205

3206

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

3207

inserver = pop.gmail.com

3208

outserver = smtp.gmail.com

3209

inport = *995

3210

outport = *465

3211

login = somebody@gmail.com

3212

password = secret

3213

reply = somebody@gmail.com

3214

from = Karl Dahlke

3215

}

3216

</font></PRE>

3217

3218

<P>

3219

Mail filtering, by sender and/or subject,

3220

is controlled by your config file as well. 

3221

This will be <A HREF=#filter>described later</A>,

3222

as part of the fetchmail client.

3223

3224

<H3 align=center> <A NAME=mt> Mime Descriptors </A> </H3>

3225

3226

Mime types are determined by the extension of the file, or in some cases the protocol. 

3227

They might tell edbrowse to use /usr/bin/play to play file.wav or file.voc,

3228

and /usr/bin/mpg123 to play file.mp3, and so on. 

3229

Rather than repeat it all here, I suggest you look at the mime {...} sections in the sample config file provided below. 

3230

Linux users can probably copy this part directly into their own config file. 

3231

It generally does the right thing. 

3232

Here is one example.

3233

3234

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

3235

type = audio/mp3

3236

desc = audio file in mp3 format

3237

suffix = mp3

3238

program = mpg123 -q -

3239

}

3240

</font></PRE>

3241

3242

<P>

3243

If you have pulled down a file from the internet that ends in .mp3,

3244

type `pb' to play the contents of the buffer. 

3245

The data is piped into the program,

3246

whose options tell it to expect data from standard in. 

3247

If the mp3 player works better from a file,

3248

use a trailing percent to turn the buffer into a temp file with the proper suffix.

3249

3250

<P>

3251

program = mpg123 -q %

3252

3253

<P>

3254

The command `pb' could mean process buffer,as well as play buffer. 

3255

For instance, a mime descriptor might unzip a zip archive.

3256

3257

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

3258

type = data/zip

3259

desc = a compressed zip archive

3260

suffix = zip

3261

# use %, since unzip cannot read data from standard in

3262

program = unzip %

3263

}

3264

</font></PRE>

3265

3266

<H3 align=center> <A NAME=sampcfg> A Sample Config File </A> </H3>

3267

3268

The best documentation is an example,

3269

so I have provided a sample config file with fake data. 

3270

It is well commented. 

3271

You can download a copy <A HREF=sample.ebrc>here</A>.

3272

3273

3274

3275

You can email the contents of your current editing session to someone else

3276

via the `sm' command. 

3277

Your email accounts are described in your <A HREF=#cfg>config file</A>.

3278

3279

<P>

3280

The contents of your .signature file, in your home directory, are automatically appended. 

3281

This is standard behavior for Unix mail clients.

3282

3283

<P>

3284

The recipients, attachments, and subject must appear at the top of your file. 

3285

The sm command is picky, so observe the following syntax carefully.

3286

3287

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>To: fred.flintstone@bedrock.us

3288

CC: barney.rubble@bedrock.us

3289

account: 1

3290

attach: hollyrock-brochure.pdf

3291

Subject: Hollyrock Vacation

3292

Come visit Hollyrock.

3293

Brochure attached.

3294

Sincerely,

3295

Rock studios incorporated.

3296

</font></PRE>

3297

3298

<P>

3299

The account line is optional. 

3300

It tells edbrowse to use the first mail account specified in your .ebrc config file. 

3301

If you don't include an account: line,

3302

edbrowse uses the default account, indicated by "default" in your .ebrc file.

3303

3304

<P>

3305

Typing sm5 causes edbrowse to use account number 5

3306

in your config file. 

3307

This overrides the account: line in your file, if there is one. 

3308

It is often easier to type sm5 than to insert an account:5 line. 

3309

Note, sm-5 is the same as sm5, but the .signature file is not included. 

3310

Sometimes you want a different ending on your email, for a particular situation.

3311

3312

<P>

3313

Use the attach: lines to add attachments to your email. 

3314

Each line should specify a file to attach,

3315

and they must appear before the subject line. 

3316

If the filename is simply a number,

3317

the corresponding edbrowse session is used instead. 

3318

Return to the earlier example,

3319

where we are trying to attach a Hollyrock brochure. 

3320

Another way to do this is to switch to session 2 and read in the pdf file. 

3321

This is a binary file, but that doesn't matter. 

3322

Don't try to edit it, just hold it in session 2. 

3323

Then switch back to session 1 and use the line attach:2.

3324

3325

<P>

3326

If you use attach:2, instead of attach:hollyrock-brochure.pdf,

3327

Fred will notice one difference. 

3328

The attachment is not prenamed for him. 

3329

If he wants to save the attachment,

3330

he'll have to come up with a filename himself. 

3331

Other than that, the email looks the same.

3332

3333

<P>

3334

The alt: directive is almost the same as the attach: directive. 

3335

If you use alt:, the attachment is not treated as an adjunct file. 

3336

Instead, it is an alternate representation of the same email. 

3337

The mail client will use the alternate representation if it can. 

3338

This is usually used to send multimedia email,

3339

with hyperlinks and pictures etc. 

3340

The primary email is in plain text,

3341

but the alternate attachment is in html or rich text. 

3342

Unless something is amiss, the user sees the alternate presentation,

3343

complete with graphics and hyperlinks.

3344

3345

<P>

3346

Like attachments,

3347

the alt: line can refer to a file or an edbrowse session.

3348

3349

<P>

3350

As you may have guessed,

3351

the to: lines establish the recipients. 

3352

Please don't specify more than a few recipients. 

3353

Some servers, my mail server included,

3354

set a hard limit of 100 on the number of recipients. 

3355

If you exceed this number,

3356

the remaining recipients simply don't get their mail. 

3357

Best to limit your "to:" lines to a couple dozen.

3358

3359

<P>

3360

Remember that CC stands for carbon copy. 

3361

This tells the recipient, in this case Barney Rubble,

3362

that he is receiving a copy of the email for his convenience;

3363

he need not respond. 

3364

Use BCC for blind carbon copy, so that each person does not see all the other email addresses.

3365

3366

<P>

3367

When specifying recipients, you can use aliases instead of full email addresses. 

3368

Aliases are checked against your address book,

3369

a text file that is specified in your .ebrc file. 

3370

If your address book contains the line

3371

<P>

3372

fred : fred.flintstone@bedrock.us : 226 cobblestone way : 5553827

3373

<P>

3374

then you can simply write "To:fred" at the top of your file. 

3375

Only the first two fields in the address book are significant

3376

as far as edbrowse is concerned. 

3377

Other fields might hold phone/fax numbers, street address, etc.

3378

<P>

3379

Note that "Reply to fred" is an alternate syntax for "to: fred".

3380

3381

<P>

3382

Some web pages include sendmail links. 

3383

They look just like other hyperlinks, but they send email to the appropriate person. 

3384

Click here for

3385

3386

technical details</A>.

3387

3388

<P>

3389

If you activate a sendmail link,

3390

you will be placed in a new editing session with the "to" and "subject" lines preloaded. 

3391

If the url did not specify a subject,

3392

the subject is simply "Hello". 

3393

You will probably want to replace this with a better subject line. 

3394

Write your mail message and type `sm' to send it on its way. 

3395

Then type ^ to return to the web page you were looking at. 

3396

Note that the body of your email may also be preloaded with some default text,

3397

so be sure to check before you write and send.

3398

3399

<P>

3400

You can include attachments by placing "attach:" lines at the top of the file,

3401

assuming the recipient can handle these attachments. 

3402

This might make sense when the sendmail link is asking for {bug reports} -

3403

you might attach a program and/or its output. 

3404

Yet this is somewhat unusual. 

3405

Most sendmail links expect a few sentences of feedback, and nothing more.

3406

3407

<P>

3408

Some web forms are submitted via email, rather than a direct http transmission. 

3409

Edbrowse handles this properly. 

3410

It shows you the destination email address,

3411

sends the mail through smtp,

3412

and tells you to watch for a reply. 

3413

This reply could be an email response, or even a phone call

3414

if you provided your phone number in the form. 

3415

But remember, nothing happens immediately. 

3416

You are still on the same web page, still looking at the same submit button. 

3417

Don't push the button again! 

3418

The mail has been sent,

3419

and you'll be hearing from the company in the next few days.

3420

3421

<H3 align=center> <A NAME=smc> Send Mail Client </A> </H3>

3422

3423

as described in the previous section,

3424

edbrowse incorporates the features of a mail client. 

3425

In addition to the interactive `sm' command,

3426

you can send mail in a batch fashion, from the command line. 

3427

If fred and barney are in your address book,

3428

and you want to send them mail from the command line, with an attachment,

3429

using your primary email account, do this. 

3430

(I'm assuming e has been aliased to an edbrowse executable.)

3431

<P>

3432

e -m1 fred ^barney hollyrock-notice +hollyrock-brochure.pdf

3433

3434

<P>

3435

The ^ in front of barney means he is a CC recipient. 

3436

Use "?barney" for BCC.

3437

3438

<P>

3439

Files with a leading + are assumed to be attachments. 

3440

If they are binary they will be encoded properly,

3441

according to the mime standard. 

3442

A leading - indicates an alternate format, like this.

3443

3444

<P>

3445

e -m1 fred ^barney hollyrock-notice -hollyrock-graphical.html

3446

3447

<P>

3448

Remember, you can specify several mail accounts in your .ebrc file. 

3449

The first account is indicated by index 1, as in -m1, and so on. 

3450

You can make your life a lot easier with some aliases in your .bashrc file.

3451

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif># My mail, home account

3452

alias mymail="e -m1"

3453

# My wife's account.

3454

alias wifemail="e -m2"

3455

# My work account.

3456

alias workmail="e -m3"

3457

# mail is obsolete

3458

alias mail="echo use mymail, wifemail, or workmail"

3459

</font></PRE>

3460

3461

<H3 align=center> <A NAME=fmc> Fetch Mail Client </A> </H3>

3462

3463

If edbrowse is run with the -m1 option, and no other arguments,

3464

it is an interactive fetch mail client,

3465

retrieving mail from your first pop3 account. 

3466

The first thing it tells you is how many messages you have. 

3467

If there are no messages it says "No mail", and exits. 

3468

If there are messages, it retrieves each one in turn. 

3469

For each message, it displays some header information (such as subject

3470

and sender) and the first page of text, and then presents a prompt. 

3471

A '?' prompt means the message is complete --

3472

a '*' prompt means there is more text to read. 

3473

You respond by hitting a key. 

3474

Keys have the following meaning.

3475

3476

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>? summary of key commands

3477

q quit the program

3478

x abort the program, deleted mail is not really deleted

3479

space display more text

3480

n read the next message

3481

d delete this message

3482

i show referenced ip addresses, then delete this message

3483

j junk this message, and any messages with this subject, for 10 days

3484

J junk this subject for a year

3485

w write this message to a file and delete it

3486

k keep this message in a file, but don't delete it

3487

u write this message unformatted to a file and delete it

3488

</font></PRE>

3489

3490

<P>

3491

The last three commands, k w and u, require a filename, which you enter. 

3492

The reserved filename "x" is essentially /dev/null,

3493

whence the mail message is discarded. 

3494

You can save the mail message to x (discard) and still save the attachments. 

3495

If the file is anything other than x,

3496

and the program cannot write to the specified file, it asks you for a new filename. 

3497

Note that capital X will do the same thing.

3498

3499

<P>

3500

The junk command adds a filter rule to your config file,

3501

sending any message with this subject to oblivion. 

3502

This is useful when you don't want to read a particular discussion thread in a mailing list. 

3503

Use the j command to junk it for ten days. 

3504

If the subject pops up again in two months, you might be interested. 

3505

Use the capital J command to junk a subject for a year. 

3506

This is typically used for spam subjects, such as

3507

"Cheap meds for you."

3508

3509

<P>

3510

Issue the i command when the mail is obviously porn/spam. 

3511

You will see the ip addresses, which you can add to your blacklist file. 

3512

This is not done automatically, because I believe in a certain amount of manual control over the process. 

3513

For example, if you, as a human, notice that you have blocked out

3514

7 addresses starting with 10.16.29,

3515

you may want to get rid of those rules and replace them with the single rule 10.16.29.0/24. 

3516

There is a slight risk in doing this,

3517

since a valid address might be nestled in amongst all these spam sites. 

3518

But it's not likely. 

3519

In fact, I sometimes take a leap of faith and exclude an entire two-byte block. 

3520

That's 65,536 websites that are locked out of my computer, for email or browsing. 

3521

A bit heavy handed perhaps, but I really hate all this spam and spyware crap!

3522

3523

<P>

3524

If one of those 65,536 addresses turns out to be valid,

3525

use a bang to negate the sense of the address, like this.

3526

3527

<P>

3528

10.5.33.177!

3529

<br>

3530

10.5.0.0/16

3531

3532

<P>

3533

Doing these ip lookups in real-time can slow the process of fetching your mail. 

3534

You can disable the whole thing by omiting, or commenting out, the ipblack= line in your config file.

3535

3536

<P>

3537

IP filtering only works for hyperlinks. 

3538

If an email has an online form that is submitted to a forbidden site, I don't detect that. 

3539

I should though - as these are the most dangerous emails of all. 

3540

They pretend to come from your bank, then send your account numbers to a thief in Russia. 

3541

So yes, this form of ip blocking is on my list of fun things to do.

3542

3543

<P>

3544

Like spam keywording, ip blocking is no panacea. 

3545

For example, a spammer with half a brain can sign up for http redirection at no cost. 

3546

Suddenly the domain in the email does not reflect the true destination at all. 

3547

I could add software to pull down the html page and test for redirection,

3548

but that would <em>really</em> slow down the interactive mail process. 

3549

Beyond this, a spammer can use javascript to assemble his destination url on the fly,

3550

and as you know, there is no way to anticipate the actions of a javascript program and pre-determine the destination url. 

3551

And so, the arms race continues,

3552

and just like the real world, the offensive team will always have the upper hand.

3553

3554

<H3 align=center> <A NAME=mailfmt> Formatted Mail </A> </H3>

3555

3556

By default, incoming mail is formatted for readability. 

3557

If you want to save a copy of the mail, exactly as it was received (unformatted),

3558

type u at the interactive prompt. 

3559

If you don't want the formatting at all, use the -u option on the command line,

3560

as in `e -um1'. 

3561

This is occasionally necessary,

3562

if a bug in my formatting routine causes edbrowse to blow up. 

3563

You still want to get your mail,

3564

(and send me a copy so I can fix the bug),

3565

so use the -u option to bypass formatting.

3566

3567

<P>

3568

When an html mail message is rendered, javascript is disabled. 

3569

Thus the mail appears sooner, and the mail client is less likely to crash due to a bug in the javascript machinery. 

3570

There really isn't much loss here, because you couldn't activate the links or fill out the form anyways. 

3571

If you want to "interact" with this email message,

3572

you have to save it unformatted to a file,

3573

finish your email session, edit that file,

3574

and type b to browse. 

3575

Now the html is active, as though you were looking at a web page on somebody's site.

3576

3577

<P>

3578

There is a reason for this falderal. 

3579

When you are running edbrowse as a fetchmail client, there is a time limit, imposed by your pop3 server. 

3580

You have about 20 seconds to decide the fate of each message. 

3581

Throw it away, skip it, save it to a file, etc. 

3582

If you doddle, the mail server hangs up and you have to start all over again. 

3583

This is not the time to interact with your message;

3584

this is not the time to fill out forms or follow hyperlinks to other interesting websites. 

3585

If you are that interested, save the message to a file and move on.

3586

3587

<P>

3588

Your sighted friend, running Outlook Express,

3589

doesn't have to worry about this, because every message is saved to a file automatically. 

3590

When he scans his mail, he is actually looking at files that have been transferred to his computer

3591

some time in the past. 

3592

He is not in the middle of a pop3 session, and there are no time limits. 

3593

This may be a better approach; I don't know. 

3594

Someday I may add a feature to grab all your messages and copy them to local files in your mail directory. 

3595

You could then use edbrowse in directory mode to step through each file in turn. 

3596

Personally, I get a lot of silly little emails, and spam too,

3597

so I am happy to delete the majority of my messages as they come,

3598

in real time,

3599

and save the few that are interesting. 

3600

Other filtering options can simplify this process. 

3601

For instance, mail from my friend Dorothy will always be saved in a particular place,

3602

because I always want to read that at my leisure. 

3603

this is described in the next section.

3604

3605

<H3 align=center> <A NAME=filter> Mail Filtering </A> </H3>

3606

3607

Your config file supports a modest level of mail filtering. 

3608

You can redirect incoming mail

3609

based upon the sender, the receiver, or the subject. 

3610

These parameters are established in your config file. 

3611

A mail filtering rule has the form:

3612

<P>

3613

matchString > destinationFile

3614

3615

<P>

3616

Actually the > is a bit misleading. 

3617

If the file exists, the email is appended to the end; the file is not truncated. 

3618

So perhaps we should use >>,

3619

but I didn't want to bother with the extra greater, over and over again.

3620

3621

<P>

3622

The destination file is interpreted relative to the mail directory,

3623

which is set in your config file. 

3624

Of course you can override with an absolute path if you wish.

3625

3626

<P>

3627

A mail filtering rule always occurs in the context of a filter block. 

3628

For instance, if you wish to redirect mail from certain people, do this.

3629

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

3630

fred flintstone > fredmail

3631

fred.flintstone@bedrock.us > fredmail

3632

jerk@hotmail.com > x

3633

word@m-w.com > -wod

3634

}

3635

</font></PRE>

3636

3637

<P>

3638

You can specify the sender's name, or his email address. 

3639

It's not a bad idea to do both,

3640

in case he sends mail from some other account etc.

3641

3642

<P>

3643

Notice that I didn't capitalize Fred Flintstone. 

3644

Matches are case insensitive.

3645

3646

<P>

3647

The file name "x" is special; it discards the mail entirely. 

3648

You can use this to throw away mail from people

3649

who are constantly harassing you, or sending you spam.

3650

3651

<P>

3652

The last entry sends mail to -wod. 

3653

The leading - is special;

3654

it means the mail should be saved to wod unformatted. 

3655

This happens to be the word of the day from Merriam Webster. 

3656

I like to save it unformatted, so I can browse it,

3657

and click on {audio} to hear the word pronounced. 

3658

If an email contains hyperlinks,

3659

you may want to save it unformatted,

3660

so you can browse it later.

3661

3662

<P>

3663

You can also filter mail based on the to: field. 

3664

This is useful if you have several mail accounts,

3665

or mail aliases that are forwarded to your primary account. 

3666

Here is a sample block.

3667

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

3668

support@my-side-business.com > support

3669

sales@my-side-business.com > sales

3670

@my-side-business.com > business

3671

me@my-regular-dayjob.com > work

3672

}

3673

</font></PRE>

3674

3675

<P>

3676

The third entry is a catchall address,

3677

saving any mail that is sent to that domain. 

3678

Since rules are applied in order,

3679

support requests are stored in a file called "support",

3680

sales are stored in a file called "sales",

3681

and all other emails sent to your business are stored in "business".

3682

3683

<P>

3684

You can use catchall addresses in the fromfilter block as well. 

3685

Anything from this domain goes here, etc.

3686

3687

<P>

3688

You can filter based on subject, using the subjfilter{...} block. 

3689

This can close the door on the virus de jure. 

3690

If a virus uses a subject line of "Come Kiss Me",

3691

you can redirect "come kiss me" to x, and it's gone.

3692

3693

<P>

3694

You can also use this feature to block warnings from other ISPs,

3695

complaining that you sent them emails with virus attachments. 

3696

You didn't, of course, because you run linux. 

3697

You're immune! 

3698

Your reply address was forged, so the virus warning was sent back to you,

3699

but you really had nothing to do with it. 

3700

Lines like this one can throw these spurious warnings away.

3701

3702

<P>

3703

subjfilter {

3704

<br>

3705

Come Kiss Me > x

3706

<br>

3707

Net Integrator Virus Alert > x

3708

<br>

3709

}

3710

3711

<P>

3712

Finally, the reply address is checked against your address book. 

3713

If there is a match, the mail is saved in a file whose name is the email alias. 

3714

Consider a line in your address book that looks like fred:Fred.Flintstone@SomeDomain.com. 

3715

When you receive email from this particular address, it is saved to the file fred. 

3716

Thus you don't have to enter and maintain redundant entries in the filter. 

3717

There is no need to include Fred.Flintstone@SomeDomain.com > fred. 

3718

It's taken care of.

3719

3720

<P>

3721

If you want to save mail from Fred unformatted, place a minus sign,

3722

i.e. -fred, in your address book. 

3723

This is the same convention as the from filter. 

3724

If you don't want mail from Fred to be redirected,

3725

but you still want to use the alias fred when sending mail,

3726

place an exclamation mark at the start, i.e. !fred.

3727

3728

<P>

3729

Note that mail filtering occurs before spam detection. 

3730

Thus mail from your friend,

3731

or to your business,

3732

will always be saved in a file,

3733

even if it references a forbidden website.

3734

3735

<P>

3736

If an email is redirected to a file, and it includes attachments,

3737

edbrowse will ask you what to do with those attachments,

3738

as though you had used the w command to save the mail yourself. 

3739

If your friend has send you a program (attached) that he wants you to look at, just hit return

3740

to save it to the default filename. 

3741

If your friend's mail has some kind of logo, or background image, that you don't care about,

3742

just type x and it will go away. 

3743

If the image has a recognizable suffix, such as gif, I discard it automatically. 

3744

If you really want these images, you'll have to save the email unformatted, and browse it later.

3745

3746

<P>

3747

When brousing an email inside the editor,

3748

edbrowse offers you all the attachments, be they images or not. 

3749

You can discard a single attachment by entering x,

3750

or all the image attachments by entering capital X.

3751

3752

<P>

3753

Use the -p option to pass over the filters, as in `e -pm1'. 

3754

This also stops spam detection. 

3755

I set this when looking at other people's mail, such as my wife's account. 

3756

I don't want her mail sent somewhere else because it matches one of my filter rules.

3757

3758

<H3 align=center> <A NAME=reply> Mail Reply </A> </H3>

3759

3760

The `re' command prepares a formatted email for reply. 

3761

The "Reply to" line (which must exist) is moved to the top. 

3762

This contains the email address that you will reply to,

3763

and it is created when you format (i.e. browse) your email message. 

3764

If this line is not present, the reply command will fail.

3765

3766

<P>

3767

The "Subject:" line must also be present. 

3768

This too is created when the email is formatted. 

3769

After the re command is issued, the subject may move down the page,

3770

to make room for other email headers as follows.

3771

3772

<P>

3773

If this email has just been browsed,

3774

and the unformatted data still exists within the current edbrowse session,

3775

re will look for the message id of the original email. 

3776

This should be referenced in the reply. 

3777

The resulting lines might look like this.

3778

3779

<P>

3780

Reply to somebody@foo.bar.com

3781

<br>

3782

references: <4387A55E6AF43C4F9830C74EFECE9132022D0638@foo-bar.net>

3783

<br>

3784

Subject: What's in a name?

3785

3786

<P>

3787

The reference line is not a line you should ever type in, edit, or delete. 

3788

Just leave it be. 

3789

If you participate in a discussion list, this line is important. 

3790

It tells the server that your reply is indeed a reply,

3791

and that it should be linked to the referenced message. 

3792

Using this information, the server maintains discussion threads. 

3793

If you delete this line before sending your response,

3794

you will create a new thread, and that will only confuse and annoy

3795

the other participants. 

3796

So - if you are going to reply to a message on a discussion list,

3797

take the time to save it unformatted, then browse,

3798

then reply. 

3799

Leave the References: line alone,

3800

edit the body of the email, add your comments, and send. 

3801

(You don't have to worry about these details if you are replying to a message through a web-based interface.)

3802

3803

<P>

3804

Sometimes the references line will have two IDs separated by white space. 

3805

The first is the beginning of the thread, the message that started this topic,

3806

and the second is the comment that you are replying to directly. 

3807

Again, this helps list servers organize the emails into threads.

3808

3809

<P>

3810

The command `rea' means reply to all,

3811

and this also uses the original email headers. 

3812

All the recipients will appear at the top of your file. 

3813

Some will be indicated by cc, if they were carbon copied. 

3814

You can delete any of these recipients before sending your response. 

3815

Of course you probably don't want to delete the first line,

3816

as that is the reply to address.

3817

3818

<P>

3819

Note that the re command takes the file out of browse mode, and turns it into a plain text file. 

3820

This supports text editing, to write your reply in the body of the message. 

3821

If you want to start over from scratch,

3822

you can't just unbrowse, because it is not in browse mode. 

3823

You must re-edit the saved mail message,

3824

browse, and reply.

3825

3826

<P>

3827

Like everything else in edbrowse, you'll get use to it once you play with it.

3828

3829

<H3 align=center> <A NAME=sqlb> Building edbrowse with Database Access </A> </H3>

3830

3831

If you simply type make, you get edbrowse, with no database interface. 

3832

Two other targets support database access. 

3833

Run either `make edbrowseodbc' or make `edbrowseinf'. 

3834

The former uses odbc to access just about any sql database,

3835

and the latter uses the

3836

<A HREF=http://www.informix.com>Informix</A> interface. 

3837

If you would like to test the odbc interface,

3838

or write a new interface, e.g. for Oracle or mysql,

3839

I will be eternally grateful. 

3840

You are basically implementing the interface described in dbapi.h,

3841

using the C database development toolkit provided by the vendor. 

3842

The easiest way to proceed is to copy one of the two files that is already there,

3843

dbinfx.ec or dbodbc.c, and make changes as necessary.

3844

3845

<H3 align=center> <A NAME=rtb> Reading Tables </A> </H3>

3846

3847

When a file name is of a certain format, with the http:// in front etc,

3848

it is deemed to be a url. 

3849

Edbrowse does not look on your computer for the file; it goes out to the internet. 

3850

Similarly, when the file name has a certain format,

3851

it is assumed to be a table or view in the database. 

3852

If you have a table called customers, you follow it up with a right bracket.

3853

3854

<P>

3855

e customers]

3856

3857

<P>

3858

This allows you to bring in the entire table,

3859

or portions thereof, one row per line, with fields delimited by pipes. 

3860

If the result looks like a bunch of numbers and pipes,

3861

and you have forgottten the structure of the table,

3862

use the sc (show columns) command. 

3863

The output might look like this.

3864

3865

<P><PRE><font size=3 face=Arial,Helvetica,sans-serif>Table customers, 536281 rows

3866

1 *custnum int

3867

2 firstname string

3868

3 lastname string

3869

4 birthdate date

3870

5 sex char

3871

6 email string

3872

7 picture blob

3873

</font></PRE>

3874

3875

<P>

3876

The first column is a unique number that designates this particular customer. 

3877

After all, two customers could have the same first and last name,

3878

and even the same birthdate. 

3879

Serial numbers are <em>always</em> a good idea,

3880

and that usually becomes the primary key. 

3881

This is indicated by a star just before the column name. 

3882

If edbrowse changes or deletes a record, the primary key is used. 

3883

I assume, at all times, that the key determines a unique record in the database,

3884

and that each record appears at most once in an editing session.

3885

3886

<P>

3887

Note that edbrowse can support a primary key with two columns, such as a serial number and a modifier. 

3888

I actually have some tables at work that look like this.

3889

3890

<P>

3891

The table syntax is more than just an identifier and a right bracket. 

3892

You can follow the right bracket with a where clause. 

3893

This is important if you don't want the entire table,

3894

especially if there are millions of rows. 

3895

Here are some table commands and their meanings.

3896

3897

<P>

3898

customers]

3899

<br>

3900

Set the buffer up for the customers table, but don't fetch any rows.

3901

3902

<P>

3903

customers]*

3904

<br>

3905

Fetch all the rows in the table.

3906

3907

<P>

3908

customers]37

3909

<br>

3910

Fetch the customer whose serial number is 37. 

3911

The primary key is assumed; your table has to have a primary key

3912

if you are going to use this syntax.

3913

3914

<P>

3915

customers]1=37

3916

<br>

3917

Fetch the row whose first column is 37.

3918

3919

<P>

3920

customers]37-59

3921

<br>

3922

Fetch the customers with serial numbers between 37 and 59 inclusive.

3923

3924

<P>

3925

customers]3=Smith

3926

<br>

3927

Fetch the customers whose last name is Smith.

3928

3929

<P>

3930

customers]lastname=Smith

3931

<br>

3932

Same as above.

3933

3934

<P>

3935

customers]last=Smith

3936

<br>

3937

Same as above. 

3938

If the string uniquely gloms onto a column name, we're all set.

3939

3940

<P>

3941

customers]last=Barn*

3942

<br>

3943

Fetch the customers whose last names begin with Barn.

3944

3945

<P>

3946

customers]birth=01/01/1960-12/31/1960

3947

<br>

3948

Fetch the customers who were born in 1960.

3949

3950

<P>

3951

It is sometimes best to edit with a blank template, i.e. without a where clause. 

3952

Then, you can read in whatever rows you like. 

3953

Type an r before any of the strings shown above to read rows into your buffer. 

3954

Note, you cannot read data from different tables into the same buffer,

3955

but you can switch to another editing session to look at another table,

3956

without losing the rows you are working on.

3957

3958

<P>

3959

When reading rows into a growing buffer, you can usually omit the table, since it has to be customers] every time. 

3960

For instance, you can bring in customer #738 by typing `r customers]738' or `r 738'.

3961

3962

<P>

3963

If you want a clean slate, type `rf' to refresh the buffer. 

3964

This brings you back to a template for the table, with no rows. 

3965

WARNING - do not clear your buffer by deleting all the rows,

3966

as that will delete the corresponding entries in the database. 

3967

This feature works just like directory mode -

3968

your edits are translated into actions in the real world, so be careful! 

3969

Referential integrity might save you from this accidental delete disaster,

3970

if you routinely use this sql feature to link tables together,

3971

which is a good idea at many levels. 

3972

But don't rely on it!

3973

3974

<P>

3975

Now, how about the seventh column in our example, the one called "picture"? 

3976

This is the customer's picture, a jpg image that is in binary,

3977

and cannot be easily folded into an editing session. 

3978

Instead, it is stored in another buffer,

3979

e.g. buffer 9, and this is indicated by <9>. 

3980

You can switch to session 9 and save the file, or throw it away.

3981

3982

<P>

3983

2139|Fred|Flintstone|08/21/1969|M|foo@bar.bar.com|<9>

3984

3985

<P>

3986

To do anything with the database, your config file must specify

3987

the name of the database, the login, and the password. 

3988

(The last two can sometimes be omitted, if they are inferred from your identity on the computer.) 

3989

Here is how the line might look

3990

if you are tapping into the retail database, where the customers table resides.

3991

3992

<P>

3993

database = retail,mylogin,mypassword

3994

3995

<P>

3996

Although this cannot be changed on the fly, you can access other databases by vectoring through this one. 

3997

For instance, you can read the parts table in the inventory database by calling up inventory:parts]. 

3998

This is standard sql syntax for looking at tables in another database;

3999

I just pass it through.

4000

4001

<H3 align=center> <A NAME=insupd> Insert, Update, Delete </A> </H3>

4002

4003

Adding database rows is substantially different from adding text. 

4004

Since a row may contain a dozen fields, and you may not remember what goes where,

4005

edbrowse prompts you for each field in turn. 

4006

It also checks the integrity of each field as you go,

4007

e.g. a date has to look like mm/dd/yyyy etc. 

4008

If a row cannot be added because of a database error,

4009

edbrowse prints the error,

4010

and data entry continues;

4011

giving you a chance to reenter the row. 

4012

Data entry stops when you enter a period all by itself,

4013

no matter what field you are on. 

4014

The rows that were entered successfully will be present in your buffer,

4015

and the current line is the last entered row. 

4016

Note that blobs cannot be entered at this time.

4017

4018

<P>

4019

Use the substitute command to update a row. 

4020

Make sure you don't accidentally introduce an additional pipe, or remove a pipe. 

4021

Key columns cannot be modified. 

4022

If you are updating many rows with one command,

4023

through a range or through g//s,

4024

and an error occurs while updating the database,

4025

substitution stops in its tracks. 

4026

The editing session will reflect the database,

4027

with some rows changed and others untouched. 

4028

There are many reasons for these update errors, including datatype mismatch

4029

(e.g. pushing an integer into a date field), and check constraints

4030

(e.g. putting J in for sex, instead of M or F). 

4031

If you have any say in the database design,

4032

apply check constraints wherever they make sense. 

4033

They will protect you from erroneous substitutions that would produce inconsistent updates.

4034

4035

<P>

4036

Delete works as you would expect; delete a row,

4037

and the corresponding entry disappears. 

4038

There is no undo command. 

4039

It couldn't be done in any case, since you may have selected only part of the row (see below),

4040

and I wouldn't have all the data to put the row back. 

4041

As mentioned before, referential integrity should be employed wherever it makes sense. 

4042

As a last check, I only let you delete 100 rows at a time. 

4043

Be careful, and run regular backups.

4044

4045

<H3 align=center> <A NAME=td> Table Descriptors </A> </H3>

4046

4047

Suppose a table contains 100 fields. 

4048

Displaying all those fields is awkward, to say the least. 

4049

Sometimes you are interested in a group of 6 fields,

4050

and sometimes you are interested in another group of 8. 

4051

You can set up virtual tables, similar to views, in your config file. 

4052

The short name is the alias, and you can call up the table using this alias. 

4053

It will contain only the columns you specify. 

4054

Here are two descriptors for the aforementioned customers table.

4055

4056

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

4057

tname = customers

4058

# cnm is my cryptic shorthand for customer name

4059

# I want to be cryptic here, cause I'm going to be typing this a lot.

4060

tshort = cnm

4061

cols = custnum,firstname,lastname

4062

# Specify the primary key, in this case, the first column selected.

4063

keycol = 1

4064

}

4065

4066

table {

4067

tname = customers

4068

# All I care about here is customer and birthdate.

4069

tshort = cbd

4070

cols = birthdate,custnum

4071

keycol = 2

4072

}

4073

</font></PRE>

4074

4075

<P>

4076

When inserting a row through one of these descriptors,

4077

remember that you are only specifying a subset of the columns in the table. 

4078

The other columns will be null, or they will take on their default values,

4079

as specified by the schema. 

4080

If you receive a Not-Null error, it could be due to one of the other columns,

4081

which requires an entered value. 

4082

It is usually safer to insert a row using the complete table.

4083

4084

4085

4086

That concludes the user's guide. 

4087

As you can see, edbrowse is a difficult program to master, but an easy program to use. 

4088

I believe this is the key to success for any blind user or programmer. 

4089

One can certainly paste a screen reader on top of an existing 2 dimensional program

4090

such as emacs or lynx, and get up and running quickly,

4091

but to be truly competitive in the workplace, or efficient at home,

4092

you need a command line interface. 

4093

Edbrowse is an important step in this direction. 

4094

It doesn't address the speech adapter, or other common applications such as spreadsheets, finances, or audio systems,

4095

but it does provide a high quality text editor and a decent browser and mail client. 

4096

It's a good start.

4097

4098

<P>

4099

4100

4101

</BODY></font>