Multi-line comments (question)

Glauber Ribeiro

unread,

Feb 7, 1999, 3:00:00 AM2/7/99

to

Hello,

i'd like to include some documentation with a TCL script i'm writing.
However, i don't want to have to put "#" in the beginning of each line.
So, i'm looking for the best way to do multi-line comments.

This is the way i'm doing it:

proc longcomment {} {}

longcomment{

This is a long comment,
which may span multiple lines.

}

What do you think of this approach?

Is there a better way to do this?

Thank you for any ideas.

Glauber

--
Glauber Ribeiro --- Integrated Warehousing Solutions (IWS)
mailto:gla...@iws-irms.com http://www.iws-irms.com
PGP keys available from certserver.pgp.com, pgpkeys.mit.edu

Christopher Nelson

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

Allen Flick wrote:

>
> Glauber Ribeiro wrote:
> > i'd like to include some documentation with a TCL script i'm writing.
> > However, i don't want to have to put "#" in the beginning of each line.
> > So, i'm looking for the best way to do multi-line comments.
> > This is the way i'm doing it:
> > proc longcomment {} {}
> > longcomment{
> > This is a long comment,
> > which may span multiple lines.
> > }
> > What do you think of this approach?
>

> Use the #'s. This could start a long thread, but I hope it doesn't.

Hear, hear!

Chris
--
Rens-se-LEER is a county. RENS-se-ler is a city. R-P-I is a school!

William H. Duquette

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

On Sun, 07 Feb 1999 23:22:34 -0600, Glauber Ribeiro
<gla...@iws-irms.com> wrote:

>Hello,

>
>i'd like to include some documentation with a TCL script i'm writing.
>However, i don't want to have to put "#" in the beginning of each line.
>So, i'm looking for the best way to do multi-line comments.
>
>This is the way i'm doing it:
>
>proc longcomment {} {}

One presumes you meant this:

proc longcomment {args} {}

Otherwise, longcomment is a procedure that takes no arguments,
and your example would fail.

Also, you'd need a space between longcomment and the "{"

>longcomment{
>
>This is a long comment,
>which may span multiple lines.
>
>}
>
>
>What do you think of this approach?

This is the obvious way to do it; I've written a similar
function as a way to comment out long blocks of code.

However, there are two strikes against it:

1. The comment text gets byte-compiled (I presume), while
normal "#" comments get stripped out, thus saving
memory.

2. It's non-standard. The Tcl Style Guide states how
comments should be done; among other things, you're
suppose to do multi-line comments by beginning each
line with a "#".

If problem 1 doesn't bother you, and if you're not
sharing your code with the Tcl community at large,
go right ahead!

If you're planning on sharing any of your code, though,
I would recommend using "#".

Will Duquette

Allen Flick

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

Glauber Ribeiro wrote:
> i'd like to include some documentation with a TCL script i'm writing.
> However, i don't want to have to put "#" in the beginning of each line.
> So, i'm looking for the best way to do multi-line comments.
> This is the way i'm doing it:
> proc longcomment {} {}

> longcomment{
> This is a long comment,
> which may span multiple lines.
> }
> What do you think of this approach?

Use the #'s. This could start a long thread, but I hope it doesn't.
Personally, comments should be comments. In C where you can do
something
like this:

/*
Start a multiline
comment, so I can put
in short paragraphs that just
look like text.
*/

are very deceiving to a "reader", thus maintainability is diminished.
The above looks so much better as follows:

/*
* Start a multiline
* comment, so I can put
* in short paragraphs that just
* look like text.
*/

Readable and obviously a comment in a file that is supposed to be
full of code.

So, I say, use the #'s.

///// ||||| \\\\\
( . . ) ( . . ) ( . . )
+-----ooO--U--Ooo------ooO--U--Ooo-----ooO--V--Ooo-----+
| |
| Allen Flick, Alcatel USA, Inc. |
| I take full credit/blame for anything stated herein. |
| |
+-------ooO-Ooo---------oooO-Oooo-------oooO-Oooo------+

Glauber Ribeiro

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

Christopher Nelson wrote:
[...]

> > Use the #'s. This could start a long thread, but I hope it doesn't.
>

> Hear, hear!

Please nobody get warmed up. I just wanted to know if there was a better
way than what i's doing. I kinda fell in love with the way you can keep
your code and documentation together in Perl by using POD ("Plain Old
Documentation", a markup language that can be translated into text,
HTML, man pages and other formats). I wanted to do something similar in
TCL. However, Perl's compiler has support for this, while in TCL the
comments would get compiled. This is probably a good enough argument to
shoot down what i was trying to do. As i said in another thread, one
useful extension for the future of TCL would be to have some standard
for documentation, either by adopting POD or by going one better and
using XML.

DUPERVAL, LAURENT

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

Christopher Nelson wrote:
>
> > Use the #'s. This could start a long thread, but I hope it doesn't.
>
> Hear, hear!
>

To make things easier for you, use a smart editor that can insert the
#'s for you automatically. One such editor is Vim (http://www.vim.org/).
If you can't stand vi, I'm sure editors like emacs and nedit and crisp
and.... can do the same.

--
Penguin Power!

Laurent Duperval - CGI
5 Place Ville Marie, Suite 1600 South, Montreal H3B 2G2
Tel: (514) 870-0879 Fax: (514) 391-2212
EMAIL: mailto:laurent....@bellsygma.com

Bryan Oakley

unread,

Feb 8, 1999, 3:00:00 AM2/8/99

to

Glauber Ribeiro wrote:
>
> Hello,

>
> i'd like to include some documentation with a TCL script i'm writing.
> However, i don't want to have to put "#" in the beginning of each line.
> So, i'm looking for the best way to do multi-line comments.
>
> This is the way i'm doing it:
>
> proc longcomment {} {}
>
> longcomment{
>
> This is a long comment,
> which may span multiple lines.
>
> }
>
> What do you think of this approach?

If it works for you, there's nothing at all wrong with it. I use a
slight variation of that myself sometimes:

if 0 {
blah blah blah
}

Though, most often I just use the #. With emacs' auto-fill mode it
becomes pretty painless.

--
Bryan Oakley mailto:oak...@channelpoint.com
ChannelPoint, Inc. http://purl.oclc.org/net/oakley

Dave LeBlanc

unread,

Feb 9, 1999, 3:00:00 AM2/9/99

to

You might find the following interesting, it disucsses documentation
of tcl(from the weekly "READ THIS" posting):
Bryan Oakley kicks off a discussion about using a Tk text
widget dump as a quick-loading documentation viewer, in
conjunction with XML, man pages, Windows help and others
http://x16.dejanews.com/thread/440414571
http://x16.dejanews.com/thread/440684551

Dave LeBlanc

On Mon, 08 Feb 1999 10:15:45 -0600, Glauber Ribeiro
<gla...@iws-irms.com> wrote:

>Christopher Nelson wrote:
>[...]

>
>> > Use the #'s. This could start a long thread, but I hope it doesn't.
>>
>> Hear, hear!
>
>

mrj...@best.com

unread,

Feb 9, 1999, 3:00:00 AM2/9/99

to

It is valid (but awkward) Tcl syntax to use "multi-line comments" where
each comment line ends with a backslash, see
<http://www.beedub.com/book/2nd/tclintro.doc.html#2875>.

Multi-line Tcl comments would look like:

# 1nd comment line \
2nd comment line \
3rd comment line \
... \
nth comment line

Note, the backslash is missing at the end of the last line. The example
below could then be written as

# Start a multiline \

comment, so I can put \
in short paragraphs that just \
look like text.

or maybe better as

# Start a multiline \

comment, so I can put \
in short paragraphs that just \

look like text. \
#

/Jean Brouwers

In article <36BEF8BD...@dsccc.com>, Allen Flick <afl...@dsccc.com> wrote:

>Glauber Ribeiro wrote:
>> i'd like to include some documentation with a TCL script i'm writing.
>> However, i don't want to have to put "#" in the beginning of each line.
>> So, i'm looking for the best way to do multi-line comments.
>> This is the way i'm doing it:
>> proc longcomment {} {}
>> longcomment{
>> This is a long comment,
>> which may span multiple lines.
>> }
>> What do you think of this approach?
>

>Use the #'s. This could start a long thread, but I hope it doesn't.

Alexandre Ferrieux

unread,

Feb 9, 1999, 3:00:00 AM2/9/99

to

Bryan Oakley wrote:
>
> [for long comments] I use a

> slight variation of that myself sometimes:
>
> if 0 {
> blah blah blah
> }
>

I also use this to disable well-delimited parts of code, but beware that
it adds one constraint to the quoted string: it must be 'proper code'
(i.e. after {;,\n} parsing, the individual commands should be proper
lists).
For example,

if 0 {"a}

chokes the compiler (which tries to compile {"a} as code).

So the "proc ign x {}" solution still has some advantages...

-Alex

lvi...@cas.org

unread,

Feb 9, 1999, 3:00:00 AM2/9/99

to

According to Glauber Ribeiro <gla...@iws-irms.com>:
:HTML, man pages and other formats). I wanted to do something similar in

:TCL. However, Perl's compiler has support for this, while in TCL the
:comments would get compiled. This is probably a good enough argument to

Well, actually, comments don't get compiled. Perhaps the key to get what
you want is to propose some 'markup' to go into Tcl comments, so that
software can then be written to take tcl comments out and convert it
into doc.

Before embarking on developing your own, you might take a look at software
like the following to see if they might provide ideas.

<URL: http://www.purl.org/NET/Tcl-FAQ/part4.html>

What: Autodoc
Where: <URL: http://www.oche.de/%7Ekupries/soft/autodoc/>
Description: AutoDOC is a system to embed documentation into Tcl code and
to generate HTML pages from it. Version 2.0 requires Tcl 8.x.
Includes the set of widgets called Pool.
Updated: 10/1998
Contact: <URL: mailto:a.ku...@westend.com> (Andreas Kupries)

What: ddoc
Where: From the contact
Description: Automated documentation tool - allows you to embed documentation
to the Tcl 8.x script, then extract it into an indexed HTML set of
pages.
Updated: 02/1997
Contact: <URL: mailto:mar...@mp-sun1.informatik.uni-mannheim.de> (M. Schinkmann)

What: FAQ builder
Where: <URL: ftp://ftp.nist.gov/mel/div826/subject/expect/FAQ.tcl>
<URL: http://www.cme.nist.gov/pub/msid/pubs/libes96c.ps>
Description: A generic FAQ Builder source, used to create either text or
HTML. Used as the basis of the FAQ for Expect.
The process is described in the PostScript paper on CGI.
Warning: If you try to display the above using a Netscape client
which has the Tcl plugin, you only get an empty page - the
plugin trys to execute it and cannot due to the presence of
some commands not implemented in the plugin.
Updated: 09/1997
Contact: <URL: mailto:li...@nist.gov> (Don Libes)

What: Maxtal Interscript
Where: <URL: http://www.triode.net.au/%7Eskaller/interscript/>
Description: Maxtal Interscript is a programming environment with a
strong emphasis on documentation and scripting.
Written in Python, but provides basic documentation constructs
for Tcl. Requires Python, Tcl 8.0, and C++.
Updated: 08/1998
Contact: <URL: mailto:ska...@maxtal.com.au>

What: robodoc
Where: <URL: http://gumpu.student.utwente.nl/Robo/robodoc.html>
<URL: http://gumpu.student.utwente.nl/%7Egalaxyng/GalaxyHQ/util.html>
<URL: http://gumpu.student.utwente.nl/%7Egalaxyng/GalaxyHQ/gui.html>
Description: Generate documentation from source. Requires an ANSI C
compiler. Works for many languages - C, FORTRAN, LaTeX, assember,
Tcl, etc.
Updated: 10/1998
Contact: <URL: mailto:gu...@gumpu.student.utwente.nl> (Gumpu Redkar)

What: Sdoc
Where: <URL: http://members.ping.at/risc/sdoc.html>
Description: Source documenter helps you when you create or add documentation
and produces good looking printable output. You add doc to your
source code using pod (Plain Old Documentation), the format also used
in perl. Sdoc can be used to document C, C++, Java, Tcl and Perl
programs. A preview function allows you to interactively create
documentation. Automatic indexing is supported.
Sdoc is limited to non-commerical use. A commercial version is
available which is faster, with complete documentation, more
features, and which comes with full support and upgrades.
Versions are available for Linux, HPUX, SGI Irix. Also requires
perl 5.x.
Updated: 04/1997
Contact: <URL: mailto:ri...@finwds01.tu-graz.ac.at> (Richard Schwaninger)

What: TL
Where: <URL: http://www.lnf.infn.it/%7Esfiligoi/tl.html>
<URL: http://www.lnf.infn.it/%7Esfiligoi/tl/default/doc/>
Description: A descriptive language for writing Tcl commands. TL generates
C code to interface to Tcl. Check the page to determine the current
version. Automatic documentation can now be generated.
Updated: 08/1997
Contact: <URL: mailto:sfil...@lnf.infn.it> (Sfiligoi Igor)

What: Tycho
Where: <URL: http://ptolemy.eecs.berkeley.edu/tycho/Tycho.html>
<URL: http://ptolemy.eecs.berkeley.edu/tycho/tycho0.2.1/tycho0.2.1.src.t
ar.gz>
Description: Tycho is an GUI itcl development environment.
Eventually, Tycho will include a graphical block diagram editor for
dataflow graphs, among other things. Currently, it has some
text editing features, an itcl graphical class browser, a profiler,
HTML viewer, an integrated documentation system to create HTML
from itcl classes, and provides support for creating
large applications. Tycho includes a Tcl/Java interface
that runs under Solaris and Windows NT. Future plans are to
add better interaction between Java and Tcl. Tycho is freely
distributable.
Updated: 08/1998
Contact: <URL: mailto:c...@eecs.berkeley.edu> (Christopher Hylands)

What: tydoc
Where: <URL: http://ptolemy.eecs.berkeley.edu/tycho/>
<URL: http://ptolemy.eecs.berkeley.edu/tycho/tycho0.2.1/tycho0.2.1/util/
tydoc/doc/>
<URL: ftp://ptolemy.eecs.berkeley.edu/pub/tycho/tycho0.3/tydoc3.0.src.ta
r.gz>
Description: A part of Tycho, tydoc takes itcl source code and generates
html.
Updated: 01/1999
Contact: <URL: mailto:c...@EECS.Berkeley.EDU> (Christopher Hylands)

--
<URL: mailto:lvi...@cas.org> Quote: Saving the world before bedtime.
<*> O- <URL: http://www.purl.org/NET/lvirden/>
Unless explicitly stated to the contrary, nothing in this posting
should be construed as representing my employer's opinions.

Andreas Sievers

unread,

Feb 9, 1999, 3:00:00 AM2/9/99

to

DUPERVAL, LAURENT wrote:

>
> Christopher Nelson wrote:
> >
> > > Use the #'s. This could start a long thread, but I hope it doesn't.
> >

> > Hear, hear!
> >
>
> To make things easier for you, use a smart editor that can insert the
> #'s for you automatically. One such editor is Vim (http://www.vim.org/).
> If you can't stand vi, I'm sure editors like emacs and nedit and crisp
> and.... can do the same.

Maybe you´d like "jedit" from the jstools. It is written in pure Tcl and
you can easily comment and uncomment marked lines with a single
mouseclick.

http://www.aq.org/~js/jstools/

andreas