[Doc-SIG] Slightly newer version of quickref

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote on 2001-08-08 4:05 AM:
> > I *did* have time to make the next iteration of the quick
> > reference...
> >
> >     http://www.tibsnjoan.co.uk/reST/quick_reST.html
>
> Although it's a great resource, I think it has grown too
> large to be usable as a quick reference.

Actually, I agree. I'm sort of iterating towards my final goal, which
probably is more like:

> a quickref page (like the first version, just
> the yellow bits) with links to a separate details page
> (full explanations)?

but of course it's easier to produce the second first (so to speak).

One problem, though, is that tables are hard to show in the
yellow/parallel format. On the other hand, since one can do just about
anything one wants with tables, maybe a simple example would suffice...

> How about adding links to the project home page?

Easily done at the end.

> Better yet, how about adding the quickref *to* the project?

Hmm - unless that's as easily done as my current FTPing of a new version
to my website, it's not an obvious thing for me to do...

It's probably easier for you to tell me if that's how it works than for
me to try to find out!

> Once the parser is done, we can *do* the quickref with
> reStructuredText.

Probably not, as one would want closer control over the layout than reST
gives (although a version in reST is not a bad idea in itself).

And no, I *don't* want to add that much cruft to reST just so I can
produce a "pretty" HTML page!

> Bugs:

Thanks for these - I'll get on them.

> - "Inline Markup", end of blue section::
>
>       For instance, consider ``this   example,   which
>         has   lots   of   spaces``.
>
>   That won't work. The second line is indented relative to the first,
>   and will currently be recognized as a definition list. The unclosed
>   backquotes will generate a warning (level 1).
>
>   The sentence ending the preceding paragraph doesn't make sense in
>   this context: "Spaces at the *start* of a line are counted relative
>   to the left margin of the current paragraph." Perhaps the same bug.

Hmm - yes, I see what you mean. Humph.

> - "Links". This is still wrong::
>
>        Internal crossreferences, like example_.
>
>        .. _example: This is an example
>           crossreference target.
>
>   The target should be::
>
>        .. _example:
>
>        This is an example cross reference target.

Ah - fundamental misunderstanding on my part. I think I get it now.

I was seeing there as being two sorts of hyperlink target::

    .. _fred: A "footnote" like one

    .. _bill:

    And a specialisation of that which marked a piece of text.

- don't know why. I'm glad to have gotten that one sorted out.

> - "Definition lists". Still waiting for an answer on:
>
>       The spec (and the parser) require blank lines between definition
>       list items. This requirement could be relaxed, as it has been
>       for other lists. What do you think?
>
>   Your example has no blank line between definition list items.

Ah - that's either a mistake, or because I was trying to see what it
looked like (and maybe argue for it). At this moment, I can't remember
which...

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.)