[Doc-SIG] Re: Comments on DPS and reStructuredText

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> I guess now it's *my* turn to be overwhelmed. ;-) I'll be replying to
> your messages over the next few days.

Hmm - just got in this morning (Monday) and it's my turn to be flooded
back at - that's OK.

> BTW, the two SourceForge projects now have CVS and mailing
> lists set up.

Hmm. Nice in theory, but not much use to me in practise - I don't have
any useful access to CVS.

I'll look into the mailing lists. Humph - more mailing lists.

> On "reST": interesting acronym. Pronounced how? As in, "to rest"? Or
> as "ree-ess-tee"? I've been using RST.

I tend to think of it as "arr ee ess tee", and then find there's a song
coming to mind (but that's doubtless my warped mind, and even if I could
hum it at you you probably wouldn't recognise it with my bad humming -
I'll have to try to ask my other half if she can figure out what it
is...). I'm afraid RST sounds very boring to me.

With respect to the quick reference - thanks for the comments.

> - "Inline Markup": ``footnote references: [5]_`` is given, but in
>   footnote 4, "rep77" is the footnote label.

Ah - these and the like are because I was going through a phase change
in where the references *pointed to* when I stopped editing the
document - the footnotes for the first table, or the table that
describes hyperlink targets. No surprise it's confused.

I haven't done any more work on the thing, but I *may* go with TeX as my
first format, just because it lets me describe the page layout properly
(which I can't, of course, do in HTML).

>      After reading your article "Would you trust something you had to
>      pay for?", both versions, I see what you mean. For "fold in", you
>      mean: the normal way HTML hyperlinks work, with arbitrary text
>      (typically underlined and in a different colour) fronting for the
>      URI, which is not visible in the text. For the alternate, you
>      mean: automatically generated footnote references and footnotes,
>      the latter containing the URI as a standalone hyperlink, visible
>      in the text. Let's call this alterate form, "callout".

OK - it's useful to have a term for it. This is, of course, the way that
the reST user has had to type it.

>      I see how the "callout" form would be useful. How to represent
>      hyperlinks is indeed an issue for the output formatter. For HTML,
>      the default would be to fold them in.

That's what I assumed would be sensible.

>      Perhaps just clarify that
>      the representation *is* a matter for the output formatter, and
>      you're just displaying one possible representation. That applies
>      to the whole page though.

OK.

>      Good article, BTW.

Thanks. It was written for what would have been a very interesting
fanzine, but somehow it never materialised.

>   2. Enumerated lists: "List items should be sequentially numbered,
>      but need not start at 1." It may not be a good idea to start at
>      anything other than 1/A/I: the output format may not support an
>      arbitrary start value. I plan to generate a level-0 warning if a
>      list starts with ordinal-1.

Hmm. Can we think of any "obvious" output formats that *don't* give this
control?

It seems to me that an informational note from the parser makes sense,
but that it should be "allowed", and the output phase should insert a
warning (level 1) if it cannot satisfy the request.

BTW, I think it's a Bad Idea to issue a level 0 for something that might
cause representation "errors" (i.e., doing something the user doesn't
expect).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)