Block comment syntax

Block comment syntax

[David Michael]

Hi,

The block comment documentation[1] claims that the closing "!#" must
appear on its own line, but this doesn't actually seem to be the
case[2].  For example, the line "(display #! comment !# 1)"
successfully outputs "1".

Can anyone clarify whether the documentation needs to be updated, or
if the currently acceptable syntax is unintentional and should be
avoided?

Thanks.

David

[1] http://git.savannah.gnu.org/gitweb/?p=guile.git;a=blob;f=doc/ref/api-evaluation.texi;h=a23cf1ae48cf2724d5426eb3e0cf898afbf51604;hb=HEAD#l206
[2] http://git.savannah.gnu.org/gitweb/?p=guile.git;a=blob;f=libguile/read.c;h=c2d50afdfda158c8b06c20650009b7f3d175f27f;hb=HEAD#l1391

Re: Block comment syntax

[Taylan Ulrich Bayirli/Kammer]

David Michael <fedora.dm0@gmail.com> writes:

> Hi,
>
> The block comment documentation[1] claims that the closing "!#" must
> appear on its own line, but this doesn't actually seem to be the
> case[2].  For example, the line "(display #! comment !# 1)"
> successfully outputs "1".
>
> Can anyone clarify whether the documentation needs to be updated, or
> if the currently acceptable syntax is unintentional and should be
> avoided?
>
> Thanks.
>
> David
>
> [1] http://git.savannah.gnu.org/gitweb/?p=guile.git;a=blob;f=doc/ref/api-evaluation.texi;h=a23cf1ae48cf2724d5426eb3e0cf898afbf51604;hb=HEAD#l206
> [2] http://git.savannah.gnu.org/gitweb/?p=guile.git;a=blob;f=libguile/read.c;h=c2d50afdfda158c8b06c20650009b7f3d175f27f;hb=HEAD#l1391

While I don't know the answer to your question, Guile 2.0.11 already
seems to support the #| |# syntax, which has been standardized in R7RS,
so I would recommend to use that for block syntax.  Syntax highlighting
in Emacs's scheme-mode seems to already know it too, in Emacs 24.3.
Moreover, it can be nested (both per R7RS, and supported in Guile
2.0.11), whereas #! !# apparently can not.

Taylan

Re: Block comment syntax

[Marko Rauhamaa]

Taylan Ulrich Bayirli/Kammer <taylanbayirli@gmail.com>:

>> The block comment documentation[1] claims that the closing "!#" must
>> appear on its own line, but this doesn't actually seem to be the
>> case[2]. For example, the line "(display #! comment !# 1)"
>> successfully outputs "1".
>>
>> Can anyone clarify whether the documentation needs to be updated, or
>> if the currently acceptable syntax is unintentional and should be
>> avoided?
>
> While I don't know the answer to your question, Guile 2.0.11 already
> seems to support the #| |# syntax, which has been standardized in
> R7RS,

The "#!" syntax is there for one purpose only: to support the unix/linux
hash-bang syntax. Every "scripting" language needs to support it. "#|"
can't replace it. I wouldn't use "#!" anywhere else in a guile source
file.

<URL: http://en.wikipedia.org/wiki/Shebang_%28Unix%29>


Marko

Re: Block comment syntax

[Mike Gran]

On Tuesday, August 5, 2014 7:04 PM, David Michael <fedora.dm0@gmail.com> wrote:
>
>
>Hi,
>
>The block comment documentation[1] claims that the closing "!#" must
>appear on its own line, but this doesn't actually seem to be the
>case[2].  For example, the line "(display #! comment !# 1)"
>successfully outputs "1".
>
>Can anyone clarify whether the documentation needs to be updated, or
>if the currently acceptable syntax is unintentional and should be
>avoided?


The documentation needs to be clarified.  The return used to
be required
back in Guile v1.6.x but now !# will terminate any block comment without
a carriage return or line feed.

If you're using #! block comments for containing shell script headers
lines like "#!/bin/sh" or "#!/usr/bin/guile" 
it is a good idea to have the terminating !# on its own line, like the
docs suggest, though. 

Best practice here is probably to use "#!" block comments only for
containing shell script headers, and use the #| syntax otherwise.

-Mike Gran  

Re: Block comment syntax

[David Michael]

On Wed, Aug 6, 2014 at 2:19 PM, Mike Gran <spk121@yahoo.com> wrote:
>
> On Tuesday, August 5, 2014 7:04 PM, David Michael <fedora.dm0@gmail.com> wrote:
>>
>>
>>Hi,
>>
>>The block comment documentation[1] claims that the closing "!#" must
>>appear on its own line, but this doesn't actually seem to be the
>>case[2].  For example, the line "(display #! comment !# 1)"
>>successfully outputs "1".
>>
>>Can anyone clarify whether the documentation needs to be updated, or
>>if the currently acceptable syntax is unintentional and should be
>>avoided?
>
>
> The documentation needs to be clarified.  The return used to
> be required
> back in Guile v1.6.x but now !# will terminate any block comment without
> a carriage return or line feed.
>
> If you're using #! block comments for containing shell script headers
> lines like "#!/bin/sh" or "#!/usr/bin/guile"
> it is a good idea to have the terminating !# on its own line, like the
> docs suggest, though.
>
> Best practice here is probably to use "#!" block comments only for
> containing shell script headers, and use the #| syntax otherwise.
>
> -Mike Gran

Thanks for the responses; I've restructured my script according to
these suggestions.

David

Re: Block comment syntax

[Ludovic Courtès]

David Michael <fedora.dm0@gmail.com> skribis:

> The block comment documentation[1] claims that the closing "!#" must
> appear on its own line, but this doesn't actually seem to be the
> case[2].  For example, the line "(display #! comment !# 1)"
> successfully outputs "1".

Yes, reader.test even has this:

--8<---------------cut here---------------start------------->8---
  (pass-if "block comment"
    (equal? '(+ 1 2 3)
            (read-string "(+ 1 #! this is a\ncomment !# 2 3)")))
--8<---------------cut here---------------end--------------->8---

> Can anyone clarify whether the documentation needs to be updated, or
> if the currently acceptable syntax is unintentional and should be
> avoided?

It’s the documentation that needs to be updated.
Done in commit 1e9249e.

Thanks,
Ludo’.

Re: Block comment syntax

[Ludovic Courtès]

Mike Gran <spk121@yahoo.com> skribis:

> The documentation needs to be clarified.  The return used to
> be required
> back in Guile v1.6.x but now !# will terminate any block comment without
> a carriage return or line feed.

Yeah I may have introduced the change inadvertently when I refactored
the reader in the 1.8 days.

Ludo’.