[Doc-SIG] Slightly newer version of quickref
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Tue, 14 Aug 2001 09:14:43 +0100
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.)