From Felix.Wiemann at gmx.net Tue Jun 1 09:55:18 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Tue Jun 1 10:00:38 2004
Subject: [Doc-SIG] Re: changing comment & directive syntax
References: <87r7t0a5zu.fsf@news2.ososo.de> <40BB6BA7.1020108@python.org>
Message-ID: <87d64jgz7d.fsf@news2.ososo.de>
David Goodger wrote:
> Felix Wiemann wrote:
>
>> IMO it's much more intuitive than the '..' syntax for comments.
>>
>> When the '.. invisible::' directive is available and when it is
>> being used, we can start phasing out the present comment syntax.
>
> I'm still unconvinced that any change in the syntax is necessary.
> I don't see enough benefit to justify the cost in broken documents.
> This needs a lot of discussion before we make any changes at all.
I think it's relatively easy to turn comments into directives in
existing documents. A regexp should do for most cases.
Anyway, after having the new invisible/comment directive for some time,
we can ask in Docutils-users if there are still many old-style comments
around.
--
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.
From Felix.Wiemann at gmx.net Tue Jun 1 10:01:46 2004
From: Felix.Wiemann at gmx.net (Felix Wiemann)
Date: Tue Jun 1 10:10:06 2004
Subject: [Doc-SIG] Re: ``invisible`` reST-directive
References: <87r7t0a5zu.fsf@news2.ososo.de> <40BB6B35.4060906@python.org>
Message-ID: <878yf7gywl.fsf@news2.ososo.de>
David Goodger wrote:
> Felix Wiemann wrote:
>
>> I propose adding a new directive 'invisible' to the reST-syntax,
>> which translates to the already existing doctree element 'comment'.
>
> I don't like the name "invisible". Why not "comment"? There's a
> possible objection that it might be confused with admonition
> directives, like "note" and "caution", but I consider that to be
> minor.
For a reader unfamiliar with reST, 'comment' would be almost as
confusing as the existing '..' syntax.
'comment' is only appropriate when thinking of reST as a 'real'
language. However, it's rather a simple markup syntax, and at least it
shouldn't look like a language (as opposed to LaTeX, for example).
Thus, 'invisible' describes more obviously what it does.
> And please, let's use another thread for the syntax discussion.
What syntax discussion? Do you mean the naming?
--
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.
From goodger at python.org Tue Jun 1 10:40:43 2004
From: goodger at python.org (David Goodger)
Date: Tue Jun 1 10:40:55 2004
Subject: [Doc-SIG] Re: changing comment & directive syntax
In-Reply-To: <87d64jgz7d.fsf@news2.ososo.de>
References: <87r7t0a5zu.fsf@news2.ososo.de> <40BB6BA7.1020108@python.org>
<87d64jgz7d.fsf@news2.ososo.de>
Message-ID: <40BC956B.2090205@python.org>
Felix Wiemann wrote:
> I think it's relatively easy to turn comments into directives in
> existing documents. A regexp should do for most cases.
It may be easy, but that doesn't mean it will be done, or should be
done. Discussion is welcome, but please realize that it's an uphill
battle.
> Anyway, after having the new invisible/comment directive for some
> time, we can ask in Docutils-users if there are still many old-style
> comments around.
We shall see. But I'm currently strongly against "phasing out" the
present comment syntax. If the explicit "comment" directive dominates
usage, then we'll reconsider.
ReStructuredText *is* markup. User-friendly markup, but it's still
markup, and it requires some learning.
--
David Goodger
From goodger at python.org Tue Jun 1 10:41:00 2004
From: goodger at python.org (David Goodger)
Date: Tue Jun 1 10:41:05 2004
Subject: [Doc-SIG] Re: ``invisible`` reST-directive
In-Reply-To: <878yf7gywl.fsf@news2.ososo.de>
References: <87r7t0a5zu.fsf@news2.ososo.de> <40BB6B35.4060906@python.org>
<878yf7gywl.fsf@news2.ososo.de>
Message-ID: <40BC957C.3040601@python.org>
Felix Wiemann wrote:
> For a reader unfamiliar with reST, 'comment' would be almost as
> confusing as the existing '..' syntax.
>
> 'comment' is only appropriate when thinking of reST as a 'real'
> language. However, it's rather a simple markup syntax, and at least
> it shouldn't look like a language (as opposed to LaTeX, for
> example). Thus, 'invisible' describes more obviously what it does.
I'm not convinced. reST is as real a markup language as any other,
and for better or worse, the accepted term in every markup language I
know of is "comment". "Invisible" makes me think of the old HTML