[Doc-SIG] Slightly newer version of quickref

[Tony J Ibbs (Tibs)]

Ken Manheimer wrote:
> As a lurker, i was yearning for an overview with substance.

All egoboo greatfully accepted - but David is still finding bugs in it,
so it's not there yet! (for me, the main benefit has actually been that
at least one gaping (and stupid) misconception I had has been fixed).


> - In the _Indirect hyperlinks_ section - what is meant by
>   "fold-in"  and "call-out" forms?  Maybe that warrants
>   a note below that box.

OK - I'll add a note. They're terms David and I came up with (one each).
Fold-in style is how one would expect HTML to work - one presses on the
link and goes directly to the location, and the "footnote" is not
visible. Call-out is how a paper document would work - the links need to
be cast as *actual* footnotes.

The examples I give of this in action are

	fold-in:  http://homepage.ntlworld.com/tibsnjoan/further2.html
	call-out: http://homepage.ntlworld.com/tibsnjoan/further3.html

These two documents could (essentially) have been written in reST and
produced by two different runs of the processor.

> - _Titles_ section - it may be worth indicating how the
>   hierarchical order of the titles is inferred - not
>   sure how to say it succinctly, though

I *think* this is best left to the main document - partly because for
*many* purposes of reST use one won't need titles (heh, I'm a docstring
person), and partly because it *is* difficult to explain quickly. I see
this as a memory jogger once one has already learnt (the basics of)
reST, so fundamental things like titles can be left out.

> - I hope this isn't out of bounds, but i find that
>   yellow painful - would you consider a more understated
>   yellow-ish, eg "#ffffcc"?

And David agrees! (actually, so do I) - but it isn't intended as a
permanent colour choice (although I shall try yours). The blue started
out something else as well, until I "stole" Python blue again.

> - I think it would be awfully nice to have some kind of
>   link from each of the items in the cheat-sheet to more
>   thorough documentation for that topic.

David had already asked for a general link to the main document(s). I
like the idea of "internal" links to the main document - but I guess it
will have to wait until we have an HTML version to link to...

David Goodger wrote:
> Get yourself a SourceForge login (free),

Aha - done.

> let me know what it is

heh - I was lucky enough to get "tibs" - that's really neat. Just
waiting for the confirmation email...

> I'll add you as a developer to the two projects.

Ok - serious egoboo (well, a little bit).

> You can use CVS, SCP, or SFTP (*not* FTP, which isn't secure)
> to upload files.

Right. Well, I've got scp here at work, and since I run Debian at home I
can't imagine there's a problem there.

> Let me know if it's OK to add the quickref to the project.

Yes, please do. I'll *try* to update it a bit later in the day (if only
to tone down the yellow!)

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)